概述

Jaeger 组件实现了各种用于保存或查询trace数据的APIs。
以下标签主要用于描述API的兼容性：

  • stable: API保证向后兼容，如果未来有重大的版本升级，将会创建新的API版本，例如/api/v2等。
  • internal: 用于 Jaeger 组件内部通信的API，不推荐外部系统调用。
  • deprecated: 仅出于历史原因保留的API，未来将会逐步淘汰。

Span上报API

Agent 和 Collector 是 Jaeger 后端可以接收 span 数据的两个组件。
目前它们支持两组不同的 API。

Thrift over UDP(stable)

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

出于遗留原因，agent 也接受 Zipkin 格式的span数据。但是，只有非常旧版本的 Jaeger client才会以该格式发送数据，并且目前已弃用。

Protobuf via gRPC(stable)

在标准的 Jaeger 部署中，Agent从Client接收span数据并将它们转发到collector。
从 Jaeger 1.11 版本开始，agent和collector之间的官方推荐协议是基于 Protobuf 的 gRPC 协议。
其中，Protobuf的格式定义在 collector.proto IDL 文件中。

Thrift over HTTP(stable)

在某些情况下，在应用程序的机器上部署 Jaeger Agent 是不可行的，例如，当应用程序代码作为 AWS Lambda 函数来运行时。
在这些场景中，Jaeger Client 可以配置为通过 HTTP/HTTPS 直接向Collector提交Span。

相同的 jaeger.thrift 数据可以在 HTTP POST 请求中提交到 /api/traces 接口，例如 https://jaeger-collector:14268/api/traces。
Batch struct 需要使用 Thrift 的binary编码进行编码，并且 HTTP 请求应指定内容类型header：

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

Zipkin Formats(stable)

Jaeger Collector 还可以接受多种 Zipkin 数据格式的 Span，包括 JSON v1/v2 和 Thrift。
Collector需要配置开启Zipkin服务器，例如9411端口常常作为Zipkin Collector的端口。
该服务提供了两个url用户接收POST请求：

  • /api/v1/spans 用于以 Zipkin JSON v1 或 Zipkin Thrift 格式提交span数据。
  • /api/v2/spans 用于在 Zipkin JSON v2 中提交span数据。

JSON over HTTP（N/A）

目前没有官方的 Jaeger JSON 格式可以被collector接收。
将来可能会支持 Protobuf 生成的 JSON。

Trace检索API

可以通过调用 Jaeger Query Service 来查询存储在后端存储中的trace数据。

gRPC/Protobuf(stable)

通过程序调用来查询trace数据的方式推荐是使用 gRPC 协议来进行查询，其中协议文件为 query.proto IDL 文件。

HTTP JSON(internal)

Jaeger UI 通过 JSON API 与 Jaeger Query Service 通信。
例如，可以通过对 https://jaeger-query:16686/api/traces/{trace-id-hex-string} 的 GET 请求检索跟踪。
Ps: 这个接口文档刻意没有公开，因为随时有可能根据需求进行调整。

客户端配置（internal）

client 库不仅将完成的 span 提交给 Jaeger 后端，还会定期轮询 Agent 以获取各种配置，例如采样策略。
数据的格式由 sampling.thrift 定义，使用Thrift 的内置JSON 生成功能编码为JSON。

服务依赖图（internal）

服务的调用依赖信息可以通过 Query Service 的 /api/dependencies URL 来查询。
该请求是GET类型的请求，需要传入两个参数：

  • endTs: 结束时间，单位为ms
  • lookback: 时间间隔的长度，单位为ms

返回的数据为JSON格式，包含一组Edges信息，每个 egde 使用元组来表示：(caller, callee, count).

Ps: 如果是在程序中调用来查询服务关系图，还是更加推荐使用 gRPC/Protobuf 的API来查询。