了解和排除 Flight 响应故障
了解如何处理响应以及排除在使用 Flight+gRPC 和 Arrow Flight 客户端查询 InfluxDB Clustered 时遇到的错误。
InfluxDB Flight 响应
InfluxDB Clustered 提供了 InfluxDB 特定的 Arrow Flight 远程过程调用 (RPC) 和 Flight SQL 服务，该服务使用高性能 RPC 框架 gRPC 以 Arrow 格式传输数据。Flight 定义了一组服务器和客户端可以用来交换信息的 RPC 方法。Flight SQL 使用 Flight RPC 并定义了其他方法来查询数据库元数据、执行查询和操作预处理语句。要了解更多关于 Flight SQL 的信息，请参阅 Introducing Apache Arrow Flight SQL: Accelerating Database Access。
要查询数据或检索关于存储在 InfluxDB Clustered 中的数据的信息，请使用 Flight 客户端向 InfluxDB Flight RPC 或 Flight SQL 服务方法发送调用。例如，如果您使用 influxdb3-python Python 客户端库 并调用 InfluxDBClient3.query() 方法，客户端会转而调用 pyarrow.flight.FlightClient.do_get() 方法，并将包含您的凭据和查询的 Flight ticket 传递给 InfluxDB 的 Flight DoGet(FlightCallOptions, Ticket) 方法。
InfluxDB 会以下列之一进行响应
流
InfluxDB 提供了 Flight RPC 方法并实现了服务器端流，供客户端检索和下载数据。在 gRPC 服务器端流场景中，客户端在请求中向服务器发送 RPC 调用。由于服务器可以向客户端返回多个响应的流，因此客户端请求包含一个标识符，客户端和服务器使用该标识符来跟踪请求和关联的响应。当服务器发送响应时，它们会与客户端的相应流关联。
Arrow Flight 服务（例如 InfluxDB）以 Arrow IPC 流格式 发送流，该格式定义了流的结构以及流中每个响应或消息的结构。
Flight 客户端库（例如 pyarrow.flight 和 Go Arrow Flight 包）实现了 Arrow 接口，用于从流中检索数据、模式和元数据。
在 InfluxDB Clustered 成功处理查询后，它会发送一个包含以下内容的流
- 应用于流中所有 record batch 的模式
- 包含查询结果数据的 RecordBatch 消息
- 请求状态 (
OK) - 可选：尾部元数据
模式
InfluxDB Flight 响应流包含一个 Flight 模式，该模式描述了数据集列的数据类型和 InfluxDB 数据元素类型（时间戳、标签或字段）。同一流中的所有数据块或 record batch 都具有相同的模式。数据转换工具可以在将 Arrow 数据转换为其他格式以及转换回 Arrow 时使用该模式。
示例
给定以下查询
SELECT co, delete, hum, room, temp, time
FROM home
WHERE time >= now() - INTERVAL '90 days'
ORDER BY time
Python 客户端库输出以下模式表示
Schema:
co: int64
-- field metadata --
iox::column::type: 'iox::column_type::field::integer'
delete: string
-- field metadata --
iox::column::type: 'iox::column_type::tag'
hum: double
-- field metadata --
iox::column::type: 'iox::column_type::field::float'
room: string
-- field metadata --
iox::column::type: 'iox::column_type::tag'
temp: double
-- field metadata --
iox::column::type: 'iox::column_type::field::float'
time: timestamp[ns] not null
-- field metadata --
iox::column::type: 'iox::column_type::timestamp'
使用 PyArrow，您可以通过 FlightStreamReader.schema 属性访问模式。请参阅 InfluxDBClient3.query() 示例 以了解如何检索模式。
RecordBatch
InfluxDB Clustered 响应流中的 RecordBatch 消息 包含 Arrow 格式的查询结果数据。当 Flight 客户端收到流时，它会从流中读取每个 record batch，直到没有更多消息可读取。当客户端收到所有消息时，它认为请求已完成。
Flight 客户端和 InfluxDB 3 客户端库提供了从流中读取 record batch 或“数据块”的方法。InfluxDB 3 Python 客户端库使用 pyarrow.flight.FlightStreamReader 类并提供以下读取器方法
all：将所有 record batch 读取到pyarrow.Table中。pandas：将所有 record batch 读取到pandas.DataFrame中。chunk：读取下一个 batch 和元数据（如果可用）。reader：将FlightStreamReader实例转换为RecordBatchReader。
Flight 客户端实现了 Flight 接口，但是客户端库的类、方法和实现可能因每种语言和库而异。
InfluxDB 状态和错误代码
在 gRPC 中，每个调用都会返回一个状态对象，其中包含整数代码和字符串消息。在请求期间，gRPC 客户端和服务器都可能返回状态 - 例如
- 服务器未能处理查询；响应状态
internal error和 gRPC 状态13。 - 请求缺少数据库令牌；服务器响应状态
unauthenticated和 gRPC 状态16。 - 服务器响应流，但客户端由于网络故障而丢失连接，并返回状态
unavailable。
gRPC 定义了服务器和客户端的整数 状态代码 和定义，而 Arrow Flight 定义了 FlightStatusDetail 类和 Flight RPC 服务可能实现的 错误代码。
虽然 Flight 定义了服务器可用的状态代码，但服务器可以选择为 RPC 调用返回哪个状态。在错误响应中，状态 details 字段包含一个错误代码，客户端可以使用该代码来确定是否应向用户显示错误（例如，客户端是否应重试请求）。
错误排查
内部错误：收到 RST_STREAM
示例:
Flight returned internal error, with message: Received RST_STREAM with error code 2. gRPC client debug context: UNKNOWN:Error received from peer ipv4:34.196.233.7:443 {grpc_message:"Received RST_STREAM with error code 2"}
潜在原因:
- 与服务器的连接意外重置。
- 客户端和服务器之间的网络问题。
- 服务器可能由于内部错误而关闭了连接。
- 客户端超出了服务器的最大并发流数。
内部错误：流被 RST_STREAM 终止，且没有错误
示例:
pyarrow._flight.FlightInternalError: Flight returned internal error, with message: stream terminated by RST_STREAM with error code: NO_ERROR. gRPC client debug context: UNKNOWN:Error received from peer ipv4:3.123.149.45:443 {created_time:"2023-07-26T14:12:44.992317+02:00", grpc_status:13, grpc_message:"stream terminated by RST_STREAM with error code: NO_ERROR"}. Client context: OK
潜在原因:
- 服务器终止了流，但没有任何与之相关的特定错误。
- 可能的网络中断，即使是暂时的。
- 服务器可能已达到其最大容量或其他内部限制。
无效参数：无效的 ticket
示例:
pyarrow.lib.ArrowInvalid: Flight returned invalid argument error, with message: Invalid ticket. Error: Invalid ticket. gRPC client debug context: UNKNOWN:Error received from peer ipv4:54.158.68.83:443 {created_time:"2023-08-31T17:56:42.909129-05:00", grpc_status:3, grpc_message:"Invalid ticket. Error: Invalid ticket"}. Client context: IOError: Server never sent a data message. Detail: Internal
潜在原因:
- 请求缺少数据库名称或某些其他必需的元数据值。
- 请求包含错误的查询语法。
未认证：未认证
示例:
Flight returned unauthenticated error, with message: unauthenticated. gRPC client debug context: UNKNOWN:Error received from peer ipv4:34.196.233.7:443 {grpc_message:"unauthenticated", grpc_status:16, created_time:"2023-08-28T15:38:33.380633-05:00"}. Client context: IOError: Server never sent a data message. Detail: Internal
潜在原因:
- 请求中缺少令牌。
- 指定的令牌对于指定的组织不存在。
未授权：权限被拒绝
示例:
pyarrow._flight.FlightUnauthorizedError: Flight returned unauthorized error, with message: Permission denied. gRPC client debug context: UNKNOWN:Error received from peer ipv4:54.158.68.83:443 {grpc_message:"Permission denied", grpc_status:7, created_time:"2023-08-31T17:51:08.271009-05:00"}. Client context: IOError: Server never sent a data message. Detail: Internal
潜在原因:
- 指定的令牌没有对指定数据库的读取权限。
FlightUnavailableError：无法获取默认的 pem 根证书
示例:
如果无法为 gRPC+TLS 找到根证书，Flight 客户端将返回类似于以下的错误
UNKNOWN:Failed to load file... filename:"/usr/share/grpc/roots.pem",
children:[UNKNOWN:No such file or directory
...
Could not get default pem root certs...
pyarrow._flight.FlightUnavailableError: Flight returned unavailable error,
with message: empty address list: . gRPC client debug context:
UNKNOWN:empty address list
...
潜在原因:
不符合 POSIX 标准的系统（例如 Windows）需要在 gRPC 客户端的 SslCredentialsOptions 中指定根证书，因为默认值仅为 POSIX 文件系统配置。为 Flight gRPC 客户端指定根证书路径。
有关 gRPC SSL/TLS 客户端-服务器身份验证的更多信息，请参阅 gRPC.io 身份验证指南中的 使用客户端 SSL/TLS。
此页是否对您有帮助？
感谢您的反馈！
支持和反馈
感谢您成为我们社区的一份子！我们欢迎并鼓励您提供关于 InfluxDB Clustered 和本文档的反馈和错误报告。要寻求支持，请使用以下资源
拥有年度或支持合同的客户可以联系 InfluxData 支持。