本页面简要介绍了 Spanner 截止期限错误：这些错误是什么、发生的原因以及如何排查和解决这些错误。
访问 Spanner API 时，请求可能会因 DEADLINE_EXCEEDED 错误而失败。此错误表示在配置的超时期限内未收到响应。
发生超时错误的原因可能有很多，例如 Spanner 实例过载、架构未经优化或查询未优化。本页面介绍了发生超时错误的常见场景，并提供了有关如何调查和解决这些问题的指南。
Spanner 的截止期限和重试理念
Spanner 的截止时间和重试理念与许多其他系统不同。在 Spanner 中，您应将超时截止期限指定为响应有用的最长时间。不建议仅为了立即重试同一操作而人为设置一个较短的时限，因为这会导致操作永远无法完成。在这种情况下，不建议采用以下策略和操作；它们会适得其反，并且会击败 Spanner 的内部重试行为：
设置的截止期限过短。这意味着操作无法应对偶发的尾延迟时间增加，并且无法在超时前完成。而应设置截止时间，也就是设置响应有用的最长时间。
设置太长的截止期限，并在超出期限之前取消操作。这会导致重试和每次尝试都浪费工作。总体而言，这可能会为您的实例造成显著的额外负载。
什么是“已超出截止日期”错误？
当您使用其中一个 Spanner 客户端库时，底层 gRPC 层负责通信、编组、解组和时限实施。通过截止期限，您的应用可以指定在请求完成之前，等待多长时间才终止请求并显示“超出期限”错误。
超时配置指南演示了如何在每个受支持的 Spanner 客户端库中指定截止期限（或超时）。Spanner 客户端库使用以下配置文件中定义的默认超时和重试政策设置：
- spanner_grpc_service_config.json
- spanner_admin_instance_grpc_service_config.json
- spanner_admin_database_grpc_service_config.json
如需详细了解 gRPC 时限，请参阅 gRPC 和时限。
如何调查和解决超出截止日期的常见错误
对于以下问题类型，您可能会遇到 DEADLINE_EXCEEDED 错误：
Data Access API 问题
您必须为特定工作负载适当配置 Spanner 实例，以避免数据访问 API 问题。以下各部分介绍了如何调查和解决不同的 Data Access API 问题。
检查 Spanner 实例的 CPU 负载
当 CPU 利用率超过建议的状况良好判断阈值时，请求延迟时间可能会显著增加。您可以在 Google Cloud 控制台提供的监控控制台中查看 Spanner CPU 利用率。您还可以根据实例的 CPU 利用率创建提醒。
解决方法
如需了解降低实例 CPU 利用率的步骤，请参阅降低 CPU 利用率。
查看请求的端到端延迟时间细分
当请求从客户端传输到 Spanner 服务器并返回时，需要创建多个网络跃点：从客户端库到 Google Front End (GFE)；从 GFE 到 Spanner API 前端；最后从 Spanner API 前端到 Spanner 数据库。如果在这些阶段中的任何阶段出现网络问题，您可能会看到超出截止时间的错误。
您可以捕获每个阶段的延迟时间。如需了解详情，请参阅 Spanner 请求中的延迟时间点。如需了解 Spanner 中发生延迟的位置，请参阅确定 Spanner 中发生延迟的位置。
解决方法
获得延迟时间细分数据后，您可以使用指标诊断延迟时间，了解发生延迟的原因，并找到解决方案。
Data API 问题
Spanner Data API 的某些非最佳使用模式可能会导致超出截止时间的错误。本部分将介绍如何检查是否存在这些非最佳使用模式。
检查是否存在开销高昂的查询
如果尝试运行未在客户端库中配置的超时期限内执行的开销大的查询，则可能导致“超出期限”错误。高开销查询的一些示例包括但不限于：对大型表进行完整扫描、对多个大型表进行交叉联接，或使用谓词对非键列执行查询（同样是全表扫描）。
您可以使用查询统计信息表和事务统计信息表来检查开销非常大的查询。这些表显示了运行缓慢的查询和事务的相关信息，例如平均读取行数、读取的平均字节数、扫描的平均行数等。此外，您还可以生成查询执行计划，以进一步检查查询的执行方式。
解决方法
如需优化查询，请参阅 SQL 查询最佳实践指南。 您还可以使用通过前面提到的统计信息表和执行计划获得的数据来优化查询并对数据库进行架构更改。这些最佳实践有助于缩短语句的执行时间，可能有助于消除“超出期限”错误。
检查锁争用
Spanner 事务需要获取锁才能提交。以高吞吐量运行的应用可能会导致事务争用相同的资源，导致获取锁的等待时间增加，并影响整体性能。这可能会导致任何读取或写入请求的截止时间超出期限。
您可以使用锁定统计信息表并参阅以下博文，找出发生长延迟时间读写事务的根本原因。在锁定统计信息表格中，您可以找到锁定等待时间最长的行键。
本锁定冲突问题排查指南介绍了如何查找正在访问锁定冲突所涉及的列的事务。您还可以使用事务代码问题排查指南来发现发生锁定冲突的事务。
解决方法
应用这些最佳实践来减少锁争用。此外，对于普通读取用例，请使用只读事务，以避免与写入发生锁冲突。读写事务应预留用于写入或混合读写工作流。遵循这些步骤应该可以缩短事务执行时间的总体延迟时间，并减少超出期限的错误。
检查是否存在未经优化的架构
在为 Spanner 数据库设计最佳数据库架构之前，您应该考虑将在数据库中执行的查询种类。在运行某些查询时，次优架构可能会导致性能问题。这些性能问题可能会导致请求无法在配置的时限内完成。
解决方法
最佳架构设计取决于对数据库进行的读取和写入。无论架构具体如何，都应遵循架构设计最佳实践和 SQL 最佳实践指南。遵循这些指南可以避免最常见的架构设计问题。导致性能不佳的一些其他根本原因在于您的主键选择、表布局（请参阅使用交错表加快访问）、架构设计（请参阅优化架构以提高性能）以及在 Spanner 实例中配置的节点的性能（请参阅 Spanner 性能概览）。
检查热点
由于 Spanner 是一个分布式数据库，因此架构设计需要考虑如何防止出现热点。例如，创建单调递增的列会限制 Spanner 可用于均匀分配工作负载的拆分数量。这些瓶颈可能会导致超时。此外，您还可以使用 Key Visualizer 来排查由热点导致的性能问题。
解决方法
要解决此问题，请先参阅上一部分检查是否存在未优化的架构部分确定的解决方法。重新设计数据库架构并使用交错索引，以避免可能引起热点的索引。如果按照上述步骤操作后，问题仍未解决，请参阅“选择主键以防止出现热点”指南。最后，避免不理想的流量模式（例如大范围读取），以免发生基于负载的拆分。
检查是否存在配置错误的超时
客户端库为 Spanner 中的所有请求提供合理的超时默认值。但是，您可能需要针对特定工作负载调整这些默认配置。有必要观察查询的开销，并根据您的具体使用场景调整截止时间。
解决方法
超时的默认设置适用于大多数用例。用户可以替换这些配置（请参阅自定义超时和重试指南），但不建议使用比默认超时更激进的超时。如果您决定更改超时时间，请将其设置为应用愿意等待结果的实际时长。您可以尝试配置更长的超时，但设置的超时时间不能短于应用愿意等待的实际时间，否则会导致操作的重试频率更高。
Admin API 问题
与 Data API 请求相比，Admin API 请求是成本高昂的操作。
CreateInstance、CreateDatabase 或 CreateBackups 等管理员请求可能需要几秒钟才能返回响应。Spanner 客户端库为实例和数据库管理员请求设置了 60 分钟的时限。这是为了确保服务器有机会在客户端重试或失败之前完成请求。
解决方法
如果您使用 Google Spanner 客户端库访问管理员 API，请确保该客户端库已更新并且使用的是最新版本。如果您是通过您创建的客户端库直接访问 Spanner API，请确保您对实例和数据库管理员请求的截止期限设置没有比默认设置（60 分钟）更激进。
Google Cloud 控制台问题
从 Google Cloud 控制台 Spanner Studio 页面发出的查询不能超过五分钟。如果您创建一个运行时间超过五分钟且成本高昂的查询，则会看到以下错误消息：
后端将取消失败的查询，事务可能会在必要时回滚。
解决方法
您可以使用 SQL 查询最佳实践指南重写查询。
Dataflow 问题
在 Apache Beam 中，读取操作的默认超时配置为 2 小时，提交操作的默认超时配置为 15 秒。与独立客户端库的截止时间超时相比，这些配置允许执行更长的操作。但是，当工作项太大时，仍然可能收到超时和截止时间已过错误。如有必要，您可以自定义 Apache Beam 提交超时配置。
解决方法
如果 ReadFromSpanner / Execute
query / Read from Spanner / Read from Partitions 步骤中发生超出截止期限的错误，请查看查询统计信息表，找出哪个查询扫描了大量行。然后，修改此类查询以尝试减少执行时间。
以下异常消息中显示了另一个 Dataflow 截止时间已过错误示例：
exception:
org.apache.beam.sdk.util.UserCodeException:
com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED:
io.grpc.StatusRuntimeException: DEADLINE_EXCEEDED: deadline exceeded after
3599.999905380s.
[remote_addr=batch-spanner.googleapis.com/172.217.5.234:443] at
org.apache.beam.runners.dataflow.worker.GroupAlsoByWindowsParDoFn$1.output(GroupAlsoByWindowsParDoFn.java:184)
导致此超时的原因是工作项过大。在前面的示例中，以下两条建议可能会有所帮助。首先，您可以尝试启用 shuffle 服务（如果尚未启用）。其次，您可以尝试调整数据库读取中的配置，例如 maxPartitions 和 partitionSizeBytes。如需了解详情，请参阅 PartitionOptions 以尝试减小工作项大小。如需查看如何执行此操作的示例，请参阅此 Dataflow 模板。
超出期限的额外问题排查资源
如果您在完成问题排查步骤后仍然看到 DEADLINE_EXCEEDED 错误，请在遇到以下场景时创建支持请求：
- Google Front End 延迟较高，但 Spanner API 请求延迟较低
- Spanner API 请求延迟时间较长，但查询延迟时间较短
您还可以参阅以下问题排查资源：