Jaeger 组件实现各种 API 用于保存或检索跟踪数据。

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

• 稳定 - API 保证向后兼容。如果将来要进行重大更改，它们将导致新的 API 版本，例如 /api/v2 URL 前缀或 IDL 中不同的命名空间。
• 内部 - API 用于 Jaeger 组件之间的内部通信，不建议外部组件使用。
• 已弃用 - 仅出于遗留原因而维护的 API，将在将来逐步淘汰。

从 Jaeger v1.32 开始，jaeger-collector 和 jaeger-query 服务端口提供 gRPC 端点，使能 gRPC 反射  . 遗憾的是，内部使用的 gogo/protobuf 与官方的 golang/protobuf 存在 兼容性问题  ，因此只有 list 反射命令目前正常工作。

跨度报告 API

jaeger-agent 和 jaeger-collector 是 Jaeger 后端可以接收跨度的两个组件。目前，它们支持两组不重叠的 API。

OpenTelemetry 协议 (稳定)

从 v1.35 开始，Jaeger 后端可以从 OpenTelemetry SDK 以其原生 OpenTelemetry 协议 (OTLP)  接收跟踪数据。不再需要使用 Jaeger 导出器配置 OpenTelemetry SDK，也不需要在 OpenTelemetry SDK 和 Jaeger 后端之间部署 OpenTelemetry 收集器。

OTLP 数据以以下格式接受：（1）二进制 gRPC，（2）Protobuf over HTTP，（3）JSON over HTTP。有关 OTLP 接收器的更多详细信息，请参阅 官方文档  。请注意，并非所有配置选项都支持在 jaeger-collector 中（请参阅 --collector.otlp.* CLI 标志 ），并且只接受跟踪数据，因为 Jaeger 不存储其他遥测类型。

Thrift over UDP (稳定)

jaeger-agent 只能通过 UDP 以 Thrift 格式接收跨度。主要 API 是一个 UDP 数据包，其中包含在 jaeger.thrift  IDL 文件中定义的 Thrift 编码的 Batch 结构，位于 jaeger-idl  存储库中。大多数 Jaeger 客户端使用 Thrift 的 compact 编码，但某些客户端库不支持它（特别是 Node.js），并且使用 Thrift 的 binary 编码（发送到不同的 UDP 端口）。jaeger-agent 的 API 由 agent.thrift  IDL 文件定义。

出于遗留原因，jaeger-agent 还通过 UDP 以 Zipkin 格式接受跨度，但是，只有非常旧版本的 Jaeger 客户端才能以该格式发送数据，并且它已被正式弃用。

通过 gRPC 的 Protobuf (稳定)

在典型的 Jaeger 部署中，**jaeger-agent** 从客户端接收跨度并将它们转发到 **jaeger-collector**。从 Jaeger v1.11 开始，**jaeger-agent** 和 **jaeger-collector** 之间官方推荐的协议是 jaeger.api_v2.CollectorService gRPC 端点，该端点定义在 collector.proto  IDL 文件中。同一个端点可用于将跟踪数据从 SDK 直接提交到 **jaeger-collector**。

Thrift over HTTP (稳定)

在某些情况下，在应用程序旁边部署 **jaeger-agent** 是不可行的，例如，当应用程序代码作为无服务器函数运行时。在这些情况下，可以将 SDK 配置为通过 HTTP/HTTPS 将跨度直接提交到 **jaeger-collector**。

相同的 jaeger.thrift  负载可以在 HTTP POST 请求中提交到 /api/traces 端点，例如 https://jaeger-collector:14268/api/traces。Batch 结构需要使用 Thrift 的 binary 编码进行编码，并且 HTTP 请求应指定内容类型标头

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

JSON over HTTP (n/a)

没有 **jaeger-collector** 可以接受的官方 Jaeger JSON 格式。Jaeger 确实接受通过 JSON 的 OpenTelemetry 协议（见 上面 ）。

Zipkin Formats (稳定)

**jaeger-collector** 也可以接受几种 Zipkin 数据格式的跨度，即 JSON v1/v2 和 Thrift。**jaeger-collector** 需要配置为启用 Zipkin HTTP 服务器，例如在 Zipkin 收集器使用的端口 9411 上。服务器启用了两个期望 POST 请求的端点

• /api/v1/spans 用于以 Zipkin JSON v1 或 Zipkin Thrift 格式提交跨度。
• /api/v2/spans 用于以 Zipkin JSON v2 格式提交跨度。

跟踪检索 API

存储中保存的跟踪可以通过调用 **jaeger-query** 服务来检索。

gRPC/Protobuf (稳定)

以编程方式检索跟踪和其他数据的推荐方法是通过 jaeger.api_v2.QueryService gRPC 端点，该端点定义在 query.proto  IDL 文件中。在默认配置中，此端点可从 jaeger-query:16685 访问。

HTTP JSON (内部)

Jaeger UI 通过 JSON API 与 **jaeger-query** 服务通信。例如，可以通过 GET 请求到 https://jaeger-query:16686/api/traces/{trace-id-hex-string} 来检索跟踪。此 JSON API 故意未记录，并且可能会更改。

远程存储 API (稳定)

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

远程采样配置 (稳定)

此 API 支持 Jaeger 的 远程采样 协议，该协议定义在 sampling.proto  IDL 文件中。

**jaeger-agent** 和 **jaeger-collector** 都实现了此 API。有关如何使用采样策略配置收集器的详细信息，请参阅 远程采样。**jaeger-agent** 仅充当 **jaeger-collector** 的代理。

下表列出了可用于查询采样策略的不同端点和格式。官方 HTTP/JSON 端点使用标准 Protobuf-to-JSON 映射  。

示例

在一个终端中运行一体化

$ go run ./cmd/all-in-one \
  --sampling.strategies-file=cmd/all-in-one/sampling_strategies.json

在另一个终端中查询不同的端点

# Collector
$ curl "https://127.0.0.1:14268/api/sampling?service=foo"
{"strategyType":"PROBABILISTIC","probabilisticSampling":{"samplingRate":1}}

# Agent
$ curl "https://127.0.0.1:5778/sampling?service=foo"
{"strategyType":"PROBABILISTIC","probabilisticSampling":{"samplingRate":1}}

# Agent, legacy endpoint / (not recommended)
$ curl "https://127.0.0.1:5778/?service=foo"
{"strategyType":0,"probabilisticSampling":{"samplingRate":1}}

服务依赖关系图 (内部)

可以从 **jaeger-query** 服务的 /api/dependencies 端点检索。GET 请求需要两个参数

• endTs（自纪元以来的毫秒数） - 时间间隔的结束
• lookback（以毫秒为单位） - 时间间隔的长度（即开始时间 + 回溯 = 结束时间）。

返回的 JSON 是一个边缘列表，表示为元组 (调用者, 被调用者, 计数)。

对于对服务图的编程访问，推荐的 API 是上面描述的 gRPC/Protobuf。

服务性能监控 (内部)

请参考 SPM 文档