本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon Keyspaces（Apache Cassandra 兼容）故障排除
本指南介绍使用 Amazon Keyspaces（Apache Cassandra 兼容）时各种场景下的故障排除步骤。它包括有关解决一般错误、连接问题、容量管理问题以及数据定义语言（DDL）错误的信息。
+ **一般性错误**
+ 对 `NoNodeAvailableException`、`NoHostAvailableException` 和 `AllNodesFailedException` 等顶级异常进行故障排除。
+ 将底层错误与 Java 驱动程序异常隔离开来。
+ 实施重试策略并正确配置连接。
+ **连接问题**
+ 解决使用 `cqlsh` 或 Apache Cassandra 客户端驱动程序连接 Amazon Keyspaces 端点时出现的错误。
+ 对 VPC 端点连接、Cassandra 压力连接和 IAM 配置错误进行故障排除。
+ 处理数据导入期间的连接丢失。
+ **容量管理错误**
+ 识别并解决与表、分区和连接相关的容量不足错误。
+ 监控亚马逊日志中的相关亚马逊 Keyspaces 指标。 CloudWatch
+ 优化连接和吞吐量以提高性能。
+ **数据定义语言（DDL）错误**
+ 对创建、访问或还原键空间和表时出现的错误进行故障排除。
+ 处理与自定义生存时间（TTL）设置、列限制和范围删除相关的故障。
+ 重度删除工作负载的注意事项。
有关专门针对 IAM 访问的故障排除指南，请参阅[Amazon Keyspaces 身份和访问问题排查](security_iam_troubleshoot.md)。如需了解有关安全性最佳实践的更多信息，请参阅 [Amazon Keyspaces 的安全最佳实践](best-practices-security.md)。
**Topics**
+ [一般性错误](troubleshooting.general.md)
+ [连接错误](troubleshooting.connecting.md)
+ [容量管理错误](troubleshooting.serverless.md)
+ [数据定义语言错误](troubleshooting.cql.md)
# 对 Amazon Keyspaces 中的常见错误进行故障排除
遇到一般性错误？ 以下介绍一些常见问题以及如何解决这些问题。
## 一般性错误
您会遇到以下顶级异常之一，这些异常可能因许多不同的原因而产生。
+ `NoNodeAvailableException`
+ `NoHostAvailableException`
+ `AllNodesFailedException`
这些异常是由客户端驱动程序生成的，可能发生在您建立控制连接或执行read/write/prepare/execute/batch请求时。
如果您在建立控制连接时发生错误，表明应用程序中指定的所有联系点都无法访问。如果在执行read/write/prepare/execute查询时出现错误，则表示该请求的所有重试次数都已用完。使用默认重试策略时，每次重试都是在不同的节点上尝试的。
### 如何将底层错误与顶级 Java 驱动程序异常隔离开来
这些一般错误可能是由连接问题或在执行read/write/prepare/execute操作时引起的。在分布式系统中，必须预料到会出现暂时故障，并且应通过重试请求来处理。遇到连接错误时，Java 驱动程序不会自动重试，因此建议在应用程序中建立驱动程序连接时实施重试策略。有关连接最佳实践的详细概述，请参阅[优化无服务器环境的客户端驱动程序连接](connections.md)。
默认情况下，Java 驱动程序将所有请求设置`idempotence`为 false，这意味着 Java 驱动程序不会自动重试失败的read/write/prepare请求。要将 `idempotence` 设置为 `true` 并告诉驱动程序重试失败的请求，您可以通过几种不同的方式执行此操作。以下是如何以编程方式为 Java 应用程序中的单个请求设置幂等性的示例。
```
Statement s = new SimpleStatement("SELECT * FROM my_table WHERE id = 1");
s.setIdempotent(true);
```
您也可以通过编程方式设置整个 Java 应用程序的默认幂等性，如以下示例所示。
```
// Make all statements idempotent by default:
cluster.getConfiguration().getQueryOptions().setDefaultIdempotence(true);
//Set the default idempotency to true in your Cassandra configuration
basic.request.default-idempotence = true
```
另一项建议是在应用程序级别创建重试策略。在这种情况下，应用程序需要捕获 `NoNodeAvailableException` 并重试请求。我们建议重试 10 次，指数回退从 10 毫秒开始，最长可达 100 毫秒，所有重试的总时间为 1 秒。
另一种选项是在建立 [Github](https://github.com/aws-samples/amazon-keyspaces-java-driver-helpers/blob/main/src/main/java/com/aws/ssa/keyspaces/retry/AmazonKeyspacesExponentialRetryPolicy.java) 上可用的 Java 驱动程序连接时应用 Amazon Keyspaces 指数重试策略。
使用默认重试策略时，请确认您已与多个节点建立了连接。您可以使用 Amazon Keyspaces 中的以下查询执行该操作。
```
SELECT * FROM system.peers;
```
如果此查询的响应为空，则表示您正在使用 Amazon Keyspaces 的单个节点。如果您使用的是默认重试策略，则不会重试，因为默认重试始终发生在不同的节点上。要了解有关通过 VPC 端点建立连接的更多信息，请参阅[如何在 Amazon Keyspaces 中通过 VPC 端点配置连接](connections.md#connections.VPCendpoints)。
有关演示如何使用 Datastax 4.x Cassandra 驱动程序与亚马逊密钥空间建立连接的 step-by-step教程，请参阅。[Step-by-step 使用适用于 Apache Cassandra 的 4.x DataStax Java 驱动程序和 Sigv4 身份验证插件连接亚马逊密钥空间的教程](using_java_driver.md#java_tutorial.SigV4)
# Amazon Keyspaces 中的连接错误故障排除
连接时遇到问题？ 以下介绍一些常见问题以及如何解决这些问题。
## 连接到 Amazon Keyspaces 端点时出错
连接失败和连接错误会导致不同的错误信息。以下部分涵盖了最常见的场景。
**Topics**
+ [我无法使用 cqlsh 连接到 Amazon Keyspaces](#troubleshooting.connection.cqlsh)
+ [我无法使用 Cassandra 客户端驱动程序连接 Amazon Keyspaces](#troubleshooting.connection.driver)
### 我无法使用 cqlsh 连接到 Amazon Keyspaces
**您尝试使用 cqlsh 连接到 Amazon Keyspaces 端点，但连接失败并显示 `Connection error`。**
如果您尝试连接到 Amazon Keyspaces 表，但 cqlsh 配置不正确，连接将失败。以下部分举例说明了在使用 cqlsh 尝试建立连接时导致连接错误的最常见配置问题。
**注意**
如果您尝试从 VPC 连接到 Amazon Keyspaces，需要额外的权限。要使用 VPC 端点成功配置连接，请按照[教程：使用接口 VPC 终端节点连接到 Amazon Keyspaces](vpc-endpoints-tutorial.md) 中的步骤操作。
**您尝试使用 cqlsh 连接到 Amazon Keyspaces，但出现连接 `timed out` 错误。**
如果您没有提供正确的端口，则可能会出现这种情况，从而导致以下错误。
```
# cqlsh cassandra.us-east-1.amazonaws.com 9140 -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.199': error(None, "Tried connecting to [('3.234.248.199', 9140)]. Last error: timed out")})
```
要解决此问题，请确认使用端口 9142 进行连接。
**您尝试使用 cqlsh 连接到 Amazon Keyspaces，但出现 `Name or service not known` 错误。**
如果您使用的端点拼写错误或不存在，则可能出现这种情况。在以下示例中，端点名称存在拼写错误。
```
# cqlsh cassandra.us-east-1.amazon.com 9142 -u "USERNAME" -p "PASSWORD" --ssl
Traceback (most recent call last):
File "/usr/bin/cqlsh.py", line 2458, in >module>
main(*read_options(sys.argv[1:], os.environ))
File "/usr/bin/cqlsh.py", line 2436, in main
encoding=options.encoding)
File "/usr/bin/cqlsh.py", line 484, in __init__
load_balancing_policy=WhiteListRoundRobinPolicy([self.hostname]),
File "/usr/share/cassandra/lib/cassandra-driver-internal-only-3.11.0-bb96859b.zip/cassandra-driver-3.11.0-bb96859b/cassandra/policies.py", line 417, in __init__
socket.gaierror: [Errno -2] Name or service not known
```
要在使用公共端点连接时解决此问题，请从 [Amazon Keyspaces 的服务端点](programmatic.endpoints.md)中选择一个可用的端点，并确认该端点的名称没有任何错误。如果使用 VPC 端点进行连接，请验证 cqlsh 配置中的 VPC 端点信息是否正确。
**您尝试使用 cqlsh 连接 Amazon Keyspaces，但收到 `OperationTimedOut` 错误。**
Amazon Keyspaces 要求为连接启用 SSL，以确保强大的安全性。如果您收到以下错误，则可能是缺少 SSL 参数。
```
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD"
Connection error: ('Unable to connect to any servers', {'3.234.248.192': OperationTimedOut('errors=Timed out creating connection (5 seconds), last_host=None',)})
#
```
要解决此问题，请将以下标志添加到 cqlsh 连接命令。
```
--ssl
```
**您尝试使用 cqlsh 连接 Amazon Keyspaces，但收到 `SSL transport factory requires a valid certfile to be specified` 错误。**
在这种情况下， SSL/TLS 证书的路径丢失，这会导致以下错误。
```
# cat .cassandra/cqlshrc
[connection]
port = 9142
factory = cqlshlib.ssl.ssl_transport_factory
#
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD" --ssl
Validation is enabled; SSL transport factory requires a valid certfile to be specified. Please provide path to the certfile in [ssl] section as 'certfile' option in /root/.cassandra/cqlshrc (or use [certfiles] section) or set SSL_CERTFILE environment variable.
#
```
要解决此问题，请添加证书文件在计算机上的路径。有关更多信息，请参阅 [如何为 TLS 手动配置 `cqlsh` 连接](programmatic.cqlsh.md#encrypt_using_tls)。
```
certfile = path_to_file/keyspaces-bundle.pem
```
**您尝试使用 cqlsh 连接 Amazon Keyspaces，但收到 `No such file or directory` 错误。**
如果计算机上证书文件的路径错误，可能出现这种情况，从而导致以下错误。
```
# cat .cassandra/cqlshrc
[connection]
port = 9142
factory = cqlshlib.ssl.ssl_transport_factory
[ssl]
validate = true
certfile = /root/wrong_path/keyspaces-bundle.pem
#
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.192': IOError(2, 'No such file or directory')})
#
```
要解决此问题，请验证计算机上的证书文件路径是否正确。有关更多信息，请参阅 [如何为 TLS 手动配置 `cqlsh` 连接](programmatic.cqlsh.md#encrypt_using_tls)。
**您尝试使用 cqlsh 连接 Amazon Keyspaces，但收到 `[X509] PEM lib` 错误。**
如果 SSL/TLS 证书`pem`文件无效，则可能出现这种情况，从而导致以下错误。
```
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.241': error(185090057, u"Tried connecting to [('3.234.248.241', 9142)]. Last error: [X509] PEM lib (_ssl.c:3063)")})
#
```
要解决此问题，请确保您已下载所需的数字证书。有关更多信息，请参阅 [如何为 TLS 手动配置 `cqlsh` 连接](programmatic.cqlsh.md#encrypt_using_tls)。
**您尝试使用 cqlsh 连接 Amazon Keyspaces，但收到 `unknown` SSL 错误。**
如果 SSL/TLS 证书`pem`文件为空，则可能出现这种情况，从而导致以下错误。
```
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.220': error(0, u"Tried connecting to [('3.234.248.220', 9142)]. Last error: unknown error (_ssl.c:3063)")})
#
```
要解决此问题，请确保您已下载所需的数字证书。您可以使用以下主题中的步骤进行确认[如何为 TLS 手动配置 `cqlsh` 连接](programmatic.cqlsh.md#encrypt_using_tls)。
**您尝试使用 cqlsh 连接 Amazon Keyspaces，但收到 `SSL: CERTIFICATE_VERIFY_FAILED` 错误。**
如果无法验证 SSL/TLS 证书文件，则可能出现这种情况，从而导致以下错误。
```
Connection error: ('Unable to connect to any servers', {'3.234.248.223': error(1, u"Tried connecting to [('3.234.248.223', 9142)]. Last error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:727)")})
```
要解决此问题，请确保您已下载所需的数字证书。您可以使用以下主题中的步骤进行确认[如何为 TLS 手动配置 `cqlsh` 连接](programmatic.cqlsh.md#encrypt_using_tls)。
**您尝试使用 cqlsh 连接到 Amazon Keyspaces，但收到了 `Last error: timed out` 错误。**
如果您没有在 Amazon EC2 安全组中为 Amazon Keyspaces 配置出站规则，则可能会出现这种情况，从而导致以下错误。
```
# cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.206': error(None, "Tried connecting to [('3.234.248.206', 9142)]. Last error: timed out")})
#
```
要确认此问题是由于 Amazon EC2 实例的配置造成的`cqlsh`，而不是由 Amazon EC2 实例的配置引起的，您可以尝试使用连接您的密钥空间 AWS CLI，例如使用以下命令。
```
aws keyspaces list-tables --keyspace-name 'my_keyspace'
```
如果此命令也超时，则表示 Amazon EC2 实例的配置不正确。
要确认您是否有足够的权限访问 Amazon Keyspaces，您可以使用 AWS CloudShell 进行连接。`cqlsh`如果连接已建立，则需要配置 Amazon EC2 实例。
要解决此问题，请确认 Amazon EC2 实例具有允许流量流入 Amazon Keyspaces 的出站规则。如果情况并非如此，则需要为 EC2 实例创建一个新的安全组，并添加一条允许向 Amazon Keyspaces 资源发送出站流量的规则。要更新出站规则以允许流量流入 Amazon Keyspaces，请从**类型**下拉菜单中选择 **CQLSH/CASSANDRA**。
创建具有出站流量规则的新安全组后，您需要将其添加到实例中。选择实例，依次选择**操作**、**安全**和**更改安全组**。添加带有出站规则的新安全组，但要确保默认组仍然可用。
有关如何查看和编辑 EC2 出站规则的更多信息，请参阅《Amazon EC2 用户指南》中的[向安全组添加规则](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/working-with-security-groups.html#adding-security-group-rule)。
**您尝试使用 cqlsh 连接 Amazon Keyspaces，但收到 `Unauthorized` 错误。**
如果您在 IAM 用户策略中缺少 Amazon Keyspaces 权限，则可能会出现这种情况，从而导致以下错误。
```
# cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "testuser-at-12345678910" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.241': AuthenticationFailed('Failed to authenticate to 3.234.248.241: Error from server: code=2100 [Unauthorized] message="User arn:aws:iam::12345678910:user/testuser has no permissions."',)})
#
```
要解决此问题，请确保 IAM 用户 `testuser-at-12345678910` 有权访问 Amazon Keyspaces。有关授予 Amazon Keyspaces 访问权限的 IAM 策略的示例，请参阅 [Amazon Keyspaces 基于身份的策略示例](security_iam_id-based-policy-examples.md)。
有关专门针对 IAM 访问的故障排除指南，请参阅[Amazon Keyspaces 身份和访问问题排查](security_iam_troubleshoot.md)。
**您尝试使用 cqlsh 连接 Amazon Keyspaces，但收到 `Bad credentials` 错误。**
如果用户名或密码错误，则可能出现这种情况，从而导致以下错误。
```
# cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.248': AuthenticationFailed('Failed to authenticate to 3.234.248.248: Error from server: code=0100 [Bad credentials] message="Provided username USERNAME and/or password are incorrect"',)})
#
```
要解决此问题，请验证代码*PASSWORD*中的*USERNAME*和是否与生成[服务专用凭证](programmatic.credentials.ssc.md)时获得的用户名和密码相匹配。
**重要**
如果您在尝试使用 cqlsh 连接时仍然看到错误，请使用 `--debug` 选项重新运行命令，并在联系 支持时提供详细的输出。
### 我无法使用 Cassandra 客户端驱动程序连接 Amazon Keyspaces
以下各节显示了使用 Cassandra 客户端驱动程序进行连接时最常见的错误。
**您正在尝试使用 DataStax Java 驱动程序连接到 Amazon Keyspaces 表，但收到错误`NodeUnavailableException`消息。**
如果尝试请求的连接中断，则会导致以下错误。
```
[com.datastax.oss.driver.api.core.NodeUnavailableException: No connection was available to Node(endPoint=vpce-22ff22f2f22222fff-aa1bb234.cassandra.us-west-2.vpce.amazonaws.com/11.1.1111.222:9142, hostId=1a23456b-c77d-8888-9d99-146cb22d6ef6, hashCode=123ca4567)]
```
要解决此问题，请找到检测信号值，如果检测信号值较高，则将其降低到 30 秒。
```
advanced.heartbeat.interval = 30 seconds
```
然后查找相关的超时时间，并确保将该值设置为至少 5 秒。
```
advanced.connection.init-query-timeout = 5 seconds
```
**您尝试使用驱动程序和 SigV4 插件连接 Amazon Keyspaces，但收到 `AttributeError` 错误。**
如果证书配置不正确，则会导致以下错误。
```
cassandra.cluster.NoHostAvailable: (‘Unable to connect to any servers’,
{‘44.234.22.154:9142’: AttributeError(“‘NoneType’ object has no attribute ‘access_key’“)})
```
要解决此问题，请验证您在使用 Sigv4 插件时传递了与 IAM 用户或角色关联的证书。SigV4 插件需要以下凭证。
+ `AWS_ACCESS_KEY_ID`— 指定与 IAM 用户或角色关联的 AWS 访问密钥。
+ `AWS_SECRET_ACCESS_KEY` - 指定与访问密钥关联的秘密密钥。这基本上是访问密钥的“密码”。
要了解有关访问密钥和 SigV4 插件的更多信息，请参阅[为 Amazon Keyspaces 创建和配置 AWS 证书](access.credentials.md)。
**您尝试使用驱动程序连接 Amazon Keyspaces 表，但收到 `PartialCredentialsError` 错误。**
如果缺少 `AWS_SECRET_ACCESS_KEY`，可能会导致以下错误。
```
cassandra.cluster.NoHostAvailable: (‘Unable to connect to any servers’, {‘44.234.22.153:9142’:
PartialCredentialsError(‘Partial credentials found in config-file, missing: aws_secret_access_key’)})
```
要解决此问题，请验证您在使用 SigV4 插件时传递了 `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY`。要了解有关访问密钥和 SigV4 插件的更多信息，请参阅[为 Amazon Keyspaces 创建和配置 AWS 证书](access.credentials.md)。
**您尝试使用驱动程序连接 Amazon Keyspaces 表，但收到 `Invalid signature` 错误。**
如果会话中签名所需的任何组件错误或定义不正确，则可能出现这种情况。
+ `AWS_ACCESS_KEY_ID`
+ `AWS_SECRET_ACCESS_KEY`
+ `AWS_DEFAULT_REGION`
以下错误是无效访问密钥的示例。
```
cassandra.cluster.NoHostAvailable: (‘Unable to connect to any servers’, {‘11.234.11.234:9142’:
AuthenticationFailed(‘Failed to authenticate to 11.234.11.234:9142: Error from server: code=0100
[Bad credentials] message=“Authentication failure: Invalid signature”’)})
```
要解决此问题，请验证访问密钥和 sigV4 插件的配置 AWS 区域 是否正确，以访问 Amazon Keyspaces。要了解有关访问密钥和 SigV4 插件的更多信息，请参阅[为 Amazon Keyspaces 创建和配置 AWS 证书](access.credentials.md)。
#### 我的 VPC 端点连接无法正常工作
**您尝试使用 VPC 端点连接 Amazon Keyspaces，但收到了令牌映射错误或吞吐量低的问题。**
如果 VPC 端点连接配置不正确，则可能出现这种情况。
要解决这些问题，请验证以下配置详细信息。要按照 step-by-step教程学习如何通过接口 VPC 终端节点为 Amazon Keyspaces 配置连接，请参阅。[教程：使用接口 VPC 终端节点连接到 Amazon Keyspaces](vpc-endpoints-tutorial.md)
1. 确认用于连接到 Amazon Keyspaces 的 IAM 实体拥有 read/write 用户表的访问权限和对系统表的读取权限，如以下示例所示。
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"cassandra:Select",
"cassandra:Modify"
],
"Resource":[
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/mykeyspace/table/mytable",
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/system*"
]
}
]
}
```
1. 确认用于连接 Amazon Keyspaces 的 IAM 实体具有访问 Amazon EC2 实例上 VPC 端点信息所需的读取权限，如以下示例所示。
```
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"ListVPCEndpoints",
"Effect":"Allow",
"Action":[
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeVpcEndpoints"
],
"Resource":"*"
}
]
}
```
**注意**
托管式策略 `AmazonKeyspacesReadOnlyAccess_v2` 和 `AmazonKeyspacesFullAccess` 包含允许 Amazon Keyspaces 访问 Amazon EC2 实例以读取可用接口 VPC 端点信息所需的权限。
有关接口 VPC 端点的更多信息，请参阅[将接口 VPC 端点用于 Amazon Keyspaces](vpc-endpoints.md#using-interface-vpc-endpoints)
1. 确认 Java 驱动程序的 SSL 配置将主机名验证设置为 false，如本示例所示。
```
hostname-validation = false
```
有关驱动程序配置的更多信息，请参阅[步骤 2：配置驱动程序](using_java_driver.md#java_tutorial.driverconfiguration)。
1. 要确认 VPC 端点的配置是否正确，可以在 VPC *内*运行以下语句。
**注意**
您不能使用本地开发人员环境或 Amazon Keyspaces CQL 编辑器来确认此配置，因为它们使用的是公共端点。
```
SELECT peer FROM system.peers;
```
输出应与本示例类似，从 IPv4 网络连接时返回 2 到 6 个带有私有 IPv4 地址的节点，具体取决于您的 VPC 设置和 AWS 区域。
```
peer
---------------
192.0.2.0.15
192.0.2.0.24
192.0.2.0.13
192.0.2.0.7
192.0.2.0.8
(5 rows)
```
#### 我无法使用 `cassandra-stress` 进行连接
**您尝试使用 `cassandra-stress` 命令连接 Amazon Keyspaces，但收到 `SSL context` 错误。**
如果您尝试连接 Amazon Keyspaces 但未正确设置 trustStore，则会发生这种情况。Amazon Keyspaces 要求使用传输层安全性协议 (TLS) 来帮助保护与客户端的连接。
在这种情况下，您看到以下错误。
```
Error creating the initializing the SSL Context
```
要解决此问题，请按照[开始前的准备工作](using_java_driver.md#using_java_driver.BeforeYouBegin)主题中所示的说明设置 trustStore。
设置 trustStore 后，您应该能够使用以下命令进行连接。
```
./cassandra-stress user profile=./profile.yaml n=100 "ops(insert=1,select=1)" cl=LOCAL_QUORUM -node "cassandra.eu-north-1.amazonaws.com" -port native=9142 -transport ssl-alg="PKIX" truststore="./cassandra_truststore.jks" truststore-password="trustStore_pw" -mode native cql3 user="user_name" password="password"
```
#### 我无法使用 IAM 身份进行连接
**您尝试使用 IAM 身份连接 Amazon Keyspaces 表，但收到 `Unauthorized` 错误。**
如果您尝试使用 IAM 身份（例如 IAM 用户）连接 Amazon Keyspaces 表，但没有执行策略并先为用户提供所需的权限，就会发生这种情况。
在这种情况下，您看到以下错误。
```
Connection error: ('Unable to connect to any servers', {'3.234.248.202': AuthenticationFailed('Failed to authenticate to 3.234.248.202:
Error from server: code=2100 [Unauthorized] message="User arn:aws:iam::1234567890123:user/testuser has no permissions."',)})
```
要解决此问题，请验证 IAM 用户的权限。要连接标准驱动程序，用户必须至少具有对系统表的`SELECT`访问权限，因为大多数驱动程序在建立连接 keyspaces/tables 时都会读取系统。
有关授予 Amazon Keyspaces 系统和用户表访问权限的 IAM 策略示例，请参阅[访问 Amazon Keyspaces 表](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-access-one-table)。
要查看专门针对 IAM 的故障排除部分，请参阅[Amazon Keyspaces 身份和访问问题排查](security_iam_troubleshoot.md)。
#### 我尝试使用 cqlsh 导入数据，但与 Amazon Keyspaces 表的连接断开
**您尝试使用 cqlsh 将数据上传到 Amazon Keyspaces，但收到连接错误。**
cqlsh 客户端从服务器连续收到三个任意类型的错误后，与 Amazon Keyspaces 的连接失败。cqlsh 客户端失败时显示以下消息。
```
Failed to import 1 rows: NoHostAvailable - , will retry later, attempt 3 of 100
```
要解决此错误，您需要确保要导入的数据与 Amazon Keyspaces 中的表模式相匹配。查看导入文件中是否存在解析错误。您可以尝试通过 INSERT 语句来使用单行数据，从而隔离错误。
客户端会自动尝试重新建立连接。
# Amazon Keyspaces 中的容量管理错误故障排除
在使用无服务器容量时遇到问题？ 以下介绍一些常见问题以及如何解决这些问题。
## 无服务器容量错误
本节简要介绍如何识别与无服务器容量管理相关的错误以及如何解决这些错误。例如，如果您的应用程序超出了预置的吞吐能力，则可能会发现容量不足事件。
由于 Apache Cassandra 是基于集群的软件，专为在节点队列上运行而设计，因此它没有与无服务器功能（例如吞吐能力）相关的异常消息。大多数驱动程序只能理解 Apache Cassandra 中的错误代码，因此 Amazon Keyspaces 使用相同的错误代码集来保持兼容性。
要将 Cassandra 错误映射到底层容量事件，您可以使用亚马逊 CloudWatch 监控相关的 Amazon Keyspaces 指标。导致客户端出错的容量不足事件可根据引起事件的资源分为三类：
+ **表** - 如果您为表选择**预配置**容量模式，并且您的应用程序超出了预配置的吞吐量，则可能会出现容量不足错误。有关更多信息，请参阅 [在 Amazon Keyspaces 中配置 read/write 容量模式](ReadWriteCapacityMode.md)。
+ **分区** — 如果给定分区的流量超过 3,000 或 1,000 RCUs ，则可能会遇到容量不足事件。 WCUs我们建议最佳做法是在分区之间均匀分配流量。有关更多信息，请参阅 [数据建模最佳实践：设计数据模型的建议](data-modeling.md)。
+ **连接** - 如果超过每个连接每秒最大操作次数的限额，可能会出现吞吐量不足的问题。要提高吞吐量，可以在配置与驱动程序的连接时增加默认连接的数量。
要了解如何为 Amazon Keyspaces 配置连接，请参阅[如何在 Amazon Keyspaces 中配置连接](connections.md#connections.howtoconfigure)。有关通过 VPC 端点优化连接的更多信息，请参阅[如何在 Amazon Keyspaces 中通过 VPC 端点配置连接](connections.md#connections.VPCendpoints)。
要确定是哪个资源导致了返回客户端错误的容量不足事件，可以检查 Amazon Keyspaces 控制台中的控制面板。**默认情况下，控制台在该表的 “容量” 选项卡的 “容量和相关 CloudWatch 指标” 部分中提供最常见**容量和流量相关指标**的汇总视图。**
要使用亚马逊创建自己的控制面板 CloudWatch，请查看以下 Amazon Keyspaces 指标。
+ `PerConnectionRequestRateExceeded` – 向 Amazon Keyspaces 发出的超出了每个连接请求速率的限额。与 Amazon Keyspaces 的每个客户端连接每秒最多可支持 3000 个 CQL 请求。通过创建多个连接，每秒可以执行超过 3000 个请求。
+ `ReadThrottleEvents` – 对 Amazon Keyspaces 的请求超过了表的读取容量。
+ `StoragePartitionThroughputCapacityExceeded` — 对 Amazon Keyspaces 存储分区的请求超过了该分区的吞吐能力。Amazon Keyspaces 存储分区最多可以支持每秒 1000 个， WCU/WRU 每秒 3000 RCU/RRU 个。为了缓解这些异常情况，我们建议您检查您的数据模型，以便将 read/write 流量分配到更多分区。
+ `WriteThrottleEvents` – 对 Amazon Keyspaces 的请求超过了表的写入容量。
要了解更多信息 CloudWatch，请参阅[使用亚马逊监控亚马逊密钥空间 CloudWatch](monitoring-cloudwatch.md)。有关 Amazon Keyspaces 的所有可用 CloudWatch 指标的列表，请参阅。[Amazon Keyspaces 指标与维度](metrics-dimensions.md)
**注意**
[要开始使用显示 Amazon Keyspaces 所有常见指标的自定义控制面板，您可以使用示例存储库 GitHub 中提供的预建 CloudWatch 模板。AWS](https://github.com/aws-samples/amazon-keyspaces-cloudwatch-cloudformation-templates)
**Topics**
+ [客户端错误](#troubleshooting.serverless.clientside)
+ [数据导入期间出现写入超时错误](#troubleshooting.serverless.writetimeout)
+ [键空间或表的存储大小](#troubleshooting.serverless.storagesize)
### 我从客户端驱动程序接收到 `NoHostAvailable` 容量不足的错误
**您看到某个表出现 `Read_Timeout` 或 `Write_Timeout` 异常。**
重复尝试向容量不足的 Amazon Keyspaces 表写入或读取数据，可能会导致特定于驱动程序的客户端错误。
CloudWatch 用于监控您的预配置吞吐量和实际吞吐量指标，以及表的容量不足事件。例如，读取请求如果没有足够的吞吐容量，就会出现 `Read_Timeout` 异常，并发布到 `ReadThrottleEvents` 指标。写入请求如果没有足够的吞吐容量，就会出现 `Write_Timeout` 异常，并发布到 `WriteThrottleEvents` 指标。有关这些指标的更多信息，请参阅 [Amazon Keyspaces 指标与维度](metrics-dimensions.md)。
请考虑使用以下选项之一来解决这些问题：
+ 增加表的*预置吞吐量*，即应用程序可消耗的最大吞吐能力。有关更多信息，请参阅 [读取容量单位和写入容量单位](ReadWriteCapacityMode.Provisioned.md#ReadWriteCapacityMode.Provisioned.Units)。
+ 让该服务通过自动扩展代表您管理吞吐能力。有关更多信息，请参阅 [使用 Amazon Keyspaces 自动扩缩自动管理吞吐能力](autoscaling.md)。
+ 为表选择**按需**容量模式。有关更多信息，请参阅 [配置按需容量模式](ReadWriteCapacityMode.OnDemand.md)。
如果您需要增加账户的默认容量限额，请参阅 [Amazon Keyspaces（Apache Cassandra 兼容）限额](quotas.md)。
**您看到与超出分区容量相关的错误。**
当您看到错误 `StoragePartitionThroughputCapacityExceeded` 时，代表分区容量暂时超过了。这可能会由自适应容量或按需容量自动处理。我们建议您检查您的数据模型，将 read/write 流量分配到更多分区，以缓解这些错误。Amazon Keyspaces 存储分区最多可以支持每秒 1000 个， WCU/WRU 每秒 3000 RCU/RRU 个。要详细了解如何改进数据模型以将 read/write 流量分配到更多分区，请参阅[数据建模最佳实践：设计数据模型的建议](data-modeling.md)。
`Write_Timeout` 异常也可能是由于在同一逻辑分区中包含静态和非静态数据的并发写入操作速率过高造成的。如果预计流量会在同一逻辑分区中运行多个包含静态和非静态数据的并发写入操作，我们建议将静态和非静态数据分别写入。分别写入数据还有助于优化吞吐量成本。
**您看到与超出连接请求速率相关的错误。**
您看到的 `PerConnectionRequestRateExceeded` 是因为以下原因之一而引起。
+ 您可能没有为每个会话配置足够的连接。
+ 由于没有正确配置 VPC 端点权限，获得的连接可能少于可用的对等节点。有关 VPC 端点策略的更多信息，请参阅[将接口 VPC 端点用于 Amazon Keyspaces](vpc-endpoints.md#using-interface-vpc-endpoints)。
+ 如果使用的是 4.x 驱动程序，请检查是否启用了主机名验证。默认情况下，该驱动程序启用 TLS 主机名验证。此配置会导致 Amazon Keyspaces 在驱动程序中显示为单节点集群。我们建议您关闭主机名验证。
我们建议您遵循以下最佳实践，以确保优化连接和吞吐量：
+ **配置 CQL 查询吞吐量调整。**
Amazon Keyspace 支持每个 TCP 连接每秒最多 3,000 次 CQL 查询，但对驱动程序可建立的连接数没有限制。
大多数开源 Cassandra 驱动程序都会建立一个连接到 Cassandra 的连接池，并在该连接池上对查询进行负载均衡。Amazon Keyspaces 向驱动程序公开 9 个对等 IP 地址。大多数驱动程序的默认行为是为每个对等 IP 地址建立一个连接。因此，使用默认设置的驱动程序的最大 CQL 查询吞吐量将是每秒 27,000 次 CQL 查询。
要增大此数字，我们建议增加驱动程序在其连接池中维护的每个 IP 地址的连接数。例如，如果将每个 IP 地址的最大连接数设置为 2，则将使驱动程序的最大吞吐量增加一倍，达到每秒 54,000 次 CQL 查询。
+ **优化您的单节点连接。**
默认情况下，大多数开源 Cassandra 驱动程序在建立会话时会与 `system.peers` 表中公布的每个 IP 地址建立一个或多个连接。但是，某些配置可能会导致驱动程序连接到单个 Amazon Keyspaces IP 地址。如果驱动程序尝试对对等节点（例如 DataStax Java 驱动程序）进行 SSL 主机名验证，或者通过 VPC 终端节点进行连接，则可能会发生这种情况。
要获得与连接到多个 IP 地址的驱动程序相同的可用性和性能，建议您执行以下操作：
+ 根据所需的客户端吞吐量，将每个 IP 的连接数增加到 9 或更高。
+ 创建自定义重试策略，确保针对同一个节点运行重试。有关更多信息，请参阅
[如何在 Amazon Keyspaces 中配置连接的重试策略](connections.md#connections.retry-policies).
+ 如果使用 VPC 端点，请向用于连接 Amazon Keyspaces 的 IAM 实体授予访问权限，以查询您的 VPC 的端点和网络接口信息。这改善了负载平衡并增加了 read/write 吞吐量。有关更多信息，请参阅 [使用接口 VPC 端点信息填充 `system.peers` 表条目](vpc-endpoints.md#system_peers)。
### 我在数据导入期间收到写入超时错误
**使用 `cqlsh` `COPY` 命令上传数据时，您收到超时错误。**
```
Failed to import 1 rows: WriteTimeout - Error from server: code=1100 [Coordinator node timed out waiting for replica nodes' responses]
message="Operation timed out - received only 0 responses." info={'received_responses': 0, 'required_responses': 2, 'write_type': 'SIMPLE', 'consistency':
'LOCAL_QUORUM'}, will retry later, attempt 1 of 100
```
Amazon Keyspaces 使用 `ReadTimeout` 和 `WriteTimeout` 异常指示写入请求何时因吞吐容量不足而失败。为了帮助诊断容量不足异常，Amazon Keyspaces 在亚马逊上发布了以下指标。 CloudWatch
+ `WriteThrottleEvents`
+ `ReadThrottledEvents`
+ `StoragePartitionThroughputCapacityExceeded`
要解决数据加载期间容量不足的错误，请降低每个工作线程的写入速率或总摄取速率，然后重试上传各行。有关更多信息，请参阅 [步骤 4：配置 `cqlsh COPY FROM` 设置](bulk-upload-config.md)。要获得更强大的数据上传选项，可以考虑使用 DSBulk[GitHub 存储库](https://github.com/datastax/dsbulk)中提供的选项。有关 step-by-step说明，请参阅[教程：使用将数据加载到 Amazon Keyspaces DSBulk](dsbulk-upload.md)。
### 我看不到键空间或表的实际存储大小
**您看不到键空间或表的实际存储大小。**
要了解有关表存储容量的更多信息，请参阅[在表级别评估您的成本](CostOptimization_TableLevelCostAnalysis.md)。您还可以通过计算表中的行大小来估算存储大小。有关计算行大小的详细说明，请参阅[估算 Amazon Keyspaces 中的行大小](calculating-row-size.md)。
# Amazon Keyspaces 中的数据定义语言错误故障排除
创建资源时遇到问题？ 以下介绍一些常见问题以及如何解决这些问题。
## 数据定义语言错误
Amazon Keyspaces 异步执行数据定义语言 (DDL) 操作，例如创建和删除键空间和表。如果应用程序在资源准备就绪之前尝试使用该资源，则操作将失败。
您可以在中监控新密钥空间和表的创建状态 AWS 管理控制台，这会指示密钥空间或表何时处于待处理状态或处于活动状态。您还可以通过查询系统架构表，以编程方式监控新的键空间或表的创建状态。当键空间或表准备就绪可供使用时，就会在系统架构中变为可见。
**注意**
要使用优化密钥空间的创建 CloudFormation，您可以使用此实用程序将 CQL 脚本转换为 CloudFormation 模板。该工具可从[GitHub 存储库](https://github.com/aws/amazon-keyspaces-cql-to-cfn-converter)中获得。
**Topics**
+ [键空间创建错误](#troubleshooting.cql.keyspace)
+ [表创建错误](#troubleshooting.cql.table)
+ [我正在尝试使用 Amazon Keyspaces point-in-time 恢复 (PITR) 恢复表，但恢复失败了](#troubleshooting.cql.pitr)
+ [我正在尝试使用 INSERT/UPDATE 编辑自定义 Time to Live (TTL) 设置，但操作失败了](#troubleshooting.cql.ttl)
+ [超出列数](#troubleshooting.cql.upload)
+ [范围删除错误](#troubleshooting.cql.rangedelete)
### 我创建了一个新的键空间，但无法查看或访问它
**您在应用程序尝试访问新的键空间时收到错误。**
如果您尝试访问新创建的 Amazon Keyspaces 键空间，但该键空间仍在异步创建中，则会出现错误。下面是一个错误示例。
```
InvalidRequest: Error from server: code=2200 [Invalid query] message="unconfigured keyspace mykeyspace"
```
要检查新的键空间何时可供使用，推荐的设计模式是轮询 Amazon Keyspaces 系统架构表 (system\$1schema\$1mcs.\$1)。
有关更多信息，请参阅 [在 Amazon Keyspaces 中查看键空间的创建状态](keyspaces-create.md)。
### 我创建了一个新表，但无法查看或访问它
**您在应用程序在尝试访问新表时收到错误。**
如果您尝试访问新创建的 Amazon Keyspaces 表，但该表仍在异步创建中，则会出现错误。例如，尝试查询尚不可用的表会失败并看到 `unconfigured table` 错误。
```
InvalidRequest: Error from server: code=2200 [Invalid query] message="unconfigured table mykeyspace.mytable"
```
尝试使用 `sync_table()` 查看表时出现 `KeyError`。
```
KeyError: 'mytable'
```
要检查新的表何时可供使用，推荐的设计模式是轮询 Amazon Keyspaces 系统架构表 (system\$1schema\$1mcs.\$1)。
这是正在创建的表的输出示例。
```
user-at-123@cqlsh:system_schema_mcs> select table_name,status from system_schema_mcs.tables where keyspace_name='example_keyspace' and table_name='example_table';
table_name | status
------------+----------
example_table | CREATING
(1 rows)
```
这是处于活动状态的表的输出示例。
```
user-at-123@cqlsh:system_schema_mcs> select table_name,status from system_schema_mcs.tables where keyspace_name='example_keyspace' and table_name='example_table';
table_name | status
------------+----------
example_table | ACTIVE
(1 rows)
```
有关更多信息，请参阅 [在 Amazon Keyspaces 中查看表的创建状态](tables-create.md)。
### 我正在尝试使用 Amazon Keyspaces point-in-time 恢复 (PITR) 恢复表，但恢复失败了
如果您正在尝试使用恢复 (PITR) point-in-time 恢复 Amazon Keyspaces 表，但看到还原过程开始但未成功完成，则可能没有为此特定表配置恢复过程所需的所有权限。
除了用户权限外，Amazon Keyspaces 可能还需要权限才能在恢复过程中代表您的主题执行操作。如果表使用客户托管式密钥加密，或者您使用限制传入流量的 IAM 策略，则会出现这种情况。
例如，如果您在 IAM 策略中使用条件密钥将源流量限制为特定端点或 IP 范围，则恢复操作会失败。要允许 Amazon Keyspaces 代表您的主体执行表恢复操作，必须在 IAM 策略中添加 `aws:ViaAWSService` 全局条件键。
有关恢复表所需的权限的更多信息，请参阅[为 Amazon Keyspaces PITR 配置还原表 IAM 权限](howitworks_restore_permissions.md)。
### 我正在尝试使用 INSERT/UPDATE 编辑自定义 Time to Live (TTL) 设置，但操作失败了
如果您试图插入或更新自定义 TTL 值，操作可能会失败，并出现以下错误。
```
TTL is not yet supported.
```
要使用 `INSERT` 或 `UPDATE` 操作为行或列指定自定义 TTL 值，必须先为表启用 TTL。您可以使用 `ttl` 自定义属性为表启用 TTL。
有关为表启用自定义 TTL 设置的更多信息，请参阅[使用自定义生存时间（TTL）更新表](TTL-how-to-enable-custom-alter.md)。
### 我尝试将数据上传到 Amazon Keyspaces 表中，但收到超出列数的错误
**您正在上传数据，但已超过可以同时更新的列数。**
当您的表架构超过 350 KB 的大小上限时，就会发生此错误。有关更多信息，请参阅 [Amazon Keyspaces（Apache Cassandra 兼容）限额](quotas.md)。
### 我尝试删除 Amazon Keyspaces 表中的数据，但删除范围失败了
**您尝试通过分区键删除数据，但收到范围删除错误。**
当您试图在一次删除操作中删除 1,000 多行时，就会发生此错误。
```
Range delete requests are limited by the amount of items that can be deleted in a single range.
```
有关更多信息，请参阅 [范围删除](functional-differences.md#functional-differences.range-delete)。
要删除单个分区中的 1,000 多行，请考虑以下选项。
+ 按分区删除 - 如果大部分分区的行数低于 1,000 行，则可以尝试按分区删除数据。如果分区包含的行数超过 1,000，则改为尝试按聚类列删除。
+ 按聚类列删除 - 如果模型包含多个聚类列，可以使用列层次结构来删除多行。聚类列是一种嵌套结构，通过对顶级列进行操作，可以删除许多行。
+ 按单行删除 - 您可以遍历行，并按其完整主键（分区列和聚类列）删除每行。
+ 最佳做法是考虑在分区之间拆分行 — 在 Amazon Keyspaces 中，我们建议您在表分区之间分配吞吐量。这样可以将数据和访问平均分配给物理资源，从而提供最佳吞吐量。有关更多信息，请参阅 [数据建模最佳实践：设计数据模型的建议](data-modeling.md)。
在为繁重的工作负载计划删除操作时，请考虑以下建议。
+ 使用 Amazon Keyspaces，分区可以包含几乎无限数量的行。这样，您就可以将分区扩展为比传统 Cassandra 指导值 100 MB 更“宽”的范围。随着时间的推移，时间序列或分类账的数据增长超过千兆字节的情况并不少见。
+ 有了 Amazon Keyspaces，当您需要对繁重的工作负载执行删除操作时，就无需考虑压缩策略或墓碑。您可以删除任意数量的数据而不会影响读取性能。