API

Jaeger 支持多种用于保存或检索追踪数据的 API。

以下标签用于描述 API 的兼容性保证。

• stable - 该 API 保证向后兼容。如果将来需要进行破坏性更改，将会产生新的 API 版本，例如 /api/v2 URL 前缀或 IDL 中的不同命名空间。
• internal - 这些 API 用于 Jaeger 组件之间的内部通信，不建议外部组件使用。
• deprecated - 这些 API 仅出于兼容遗留系统的目的而维护，将来会被逐步淘汰。

默认端口

以下表格列出了 Jaeger 组件使用的默认端口。用户可以通过配置进行覆盖。

写入 API

端口	协议	端点	格式
4317	gRPC	ExportTraceServiceRequest	OTLP Protobuf
4318	HTTP	/v1/traces	OTLP Protobuf 或 OTLP JSON
6831	UDP	原始端口	Legacy Thrift，使用 compact Thrift 协议
6832	UDP	原始端口	Legacy Thrift，使用 binary Thrift 协议
9411	HTTP	/api/v1/spans	Zipkin v1 JSON 或 Thrift
	HTTP	/api/v2/spans	Zipkin v2 JSON 或 Protobuf
14250	gRPC	jaeger.api_v2.CollectorService	Legacy Protobuf
14268	HTTP	/api/traces	Legacy Thrift

读取 API

端口	协议	端点	格式
16685	gRPC	jaeger.api_v3.QueryService	基于 OTLP 的 Protobuf
	gRPC	jaeger.api_v2.QueryService	Legacy Protobuf
16686	HTTP	/api/v3/*	基于 OTLP 的 JSON over HTTP
	HTTP	/api/*	内部（非官方）JSON API

远程采样 API

端口	协议	端点	格式
5778	HTTP	/sampling	sampling.proto 通过 Protobuf 到 JSON 的映射
5779	gRPC	jaeger.api_v2.SamplingManager	Protobuf

追踪数据接收 API

Jaeger 可以在不同端口上以多种格式接收追踪数据。

OpenTelemetry Protocol

状态：Stable

Jaeger 可以通过原生的 OpenTelemetry Protocol (OTLP) 从 OpenTelemetry SDK 接收追踪数据。OTLP 数据支持以下格式：

• Protobuf via gRPC
• Protobuf over HTTP
• JSON over HTTP

仅接受追踪数据，因为 Jaeger 不存储其他类型的遥测数据。有关 OTLP receiver 的更多详情，请参阅官方文档。

Legacy Protobuf via gRPC

状态：Stable，Deprecated

Jaeger 的 legacy Protobuf 格式定义在 collector.proto IDL 文件中。OpenTelemetry SDK 已移除对此格式的支持，仅为向后兼容而维护。

Legacy Thrift over HTTP

状态：Stable，Deprecated

Jaeger 的 legacy Thrift 格式定义在 jaeger.thrift IDL 文件中，仅为向后兼容而维护。Thrift 有效载荷可以通过 HTTP POST 请求提交到 /api/traces 端点，例如 https://jaeger-collector:14268/api/traces。Batch 结构体需要使用 Thrift 的 binary 编码进行编码，并且 HTTP 请求应指定内容类型头：

Content-Type: application/vnd.apache.thrift.binary

Legacy Thrift over UDP

状态：Stable，Deprecated

此 API 为与旧版 Jaeger 客户端的向后兼容而保留。

主要 API 是一个包含 Thrift 编码的 Batch 结构体的 UDP 数据包，该结构体定义在 [jaeger-idl] 仓库的 jaeger.thrift IDL 文件中。大多数 Jaeger 客户端使用 Thrift 的 compact 编码，但某些客户端库不支持此编码（特别是 Node.js），而使用 Thrift 的 binary 编码（发送到不同的 UDP 端口）。

Zipkin 格式

状态：Stable

Jaeger 可以接收多种 Zipkin 数据格式的 span，包括 JSON v1/v2 和 Thrift。需要配置 jaeger-collector 以启用 Zipkin HTTP 服务器，例如在 Zipkin collector 使用的 9411 端口上。服务器启用两个接受 POST 请求的端点：

• /api/v1/spans 用于提交 Zipkin v1 JSON 或 Thrift 格式的 span。
• /api/v2/spans 用于提交 Zipkin v2 JSON 或 Protobuf 格式的 span。

追踪数据检索 API

存储在后端的追踪数据可以通过调用 jaeger-query 服务来检索。

Query Protobuf via gRPC

状态：Stable

以编程方式检索追踪数据和其他数据的推荐方法是通过 jaeger.api_v3.QueryService gRPC 端点，该端点定义在 api_v3/query_service.proto IDL 文件中。在默认配置中，此端点可在 :16685 端口访问。同时也支持 legacy api_v2。

Query JSON over HTTP

状态：Stable

这是 api_v3/query_service.proto 的 JSON/HTTP 版本（参见 Swagger 文件）。

内部 HTTP JSON

状态：Internal

Jaeger UI 通过 JSON API 与 jaeger-query 服务通信。例如，可以通过向 https://jaeger-query:16686/api/traces/{trace-id-hex-string} 发送 GET 请求来检索追踪数据。此 JSON API 是有意不公开文档的，并且可能会发生变更。

远程存储 API

状态：Stable

当使用 grpc 存储类型（即远程存储）时，
Jaeger 可以使用自定义存储后端，只要这些后端实现了
gRPC 远程存储 API。

要使用远程存储后端，您必须部署一个实现以下服务的 gRPC 服务器：

• TraceReader
  使 Jaeger 能够从存储后端读取追踪数据。
• DependencyReader
  用于从存储中加载服务依赖关系图。
• TraceService
  允许将追踪数据推送到存储。如果需要，此服务可以在单独的端口上运行。

有关更多信息，请参阅
jaeger/internal/storage/v2/grpc。

远程采样配置

状态：Stable

此 API 支持 Jaeger 的远程采样协议，定义在 sampling.proto IDL 文件中。有关如何使用采样策略配置 Jaeger 的详细信息，请参阅远程采样。

服务依赖关系图

状态：Internal

可以从 /api/dependencies 端点检索。GET 请求需要两个参数：

• endTs（自纪元以来的毫秒数）- 时间区间的结束时间
• lookback（毫秒）- 时间区间的长度（即开始时间 + lookback = 结束时间）。

返回的 JSON 是以元组 (caller, callee, count) 表示的边的列表。

对于以编程方式访问服务图，推荐使用上述的 gRPC/Protobuf API。

服务性能监控

状态：Internal

请参阅 SPM 文档

gRPC 服务器自省

提供 gRPC 端点的服务端口启用了 gRPC 反射。不幸的是，内部使用的 gogo/protobuf 与官方的 golang/protobuf 存在兼容性问题，因此目前只有 list 反射命令能正常工作，例如：

grpc_cli ls localhost:16685
  grpc.health.v1.Health
  grpc.reflection.v1.ServerReflection
  grpc.reflection.v1alpha.ServerReflection
  jaeger.api_v2.QueryService
  jaeger.api_v2.metrics.MetricsQueryService
  jaeger.api_v3.QueryService