Jaeger 支持各种 API 来保存或检索跟踪数据。

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

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

默认端口

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

写入 API

读取 API

远程采样 API

跟踪接收 API

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

OpenTelemetry 协议

状态: 稳定

Jaeger 可以从 OpenTelemetry SDKs 接收其原生 OpenTelemetry 协议 (OTLP)  的跟踪数据。OTLP 数据以以下格式接受：

• 通过 gRPC 的 Protobuf 
• 通过 HTTP 的 Protobuf 
• 通过 HTTP 的 JSON 

只接受跟踪数据，因为 Jaeger 不存储其他遥测类型。有关 OTLP 接收器的更多详细信息，请参阅官方文档 。

通过 gRPC 的传统 Protobuf

状态: 稳定，已弃用

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

通过 HTTP 的传统 Thrift

状态: 稳定，已弃用

Jaeger 的传统 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

通过 UDP 的传统 Thrift

状态: 稳定，已弃用

此 API 仅为与传统 Jaeger 客户端的向后兼容性而保留。

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

Zipkin 格式

状态: 稳定

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

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

跟踪检索 API

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

通过 gRPC 查询 Protobuf

状态: 稳定

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

通过 HTTP 查询 JSON

状态: 稳定

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

内部 HTTP JSON

状态: 内部

Jaeger UI 通过 JSON API 与 **jaeger-query** 服务通信。例如，可以通过向 `https://jaeger-query:16686/api/traces/{trace-id-hex-string}` 发送 GET 请求来检索跟踪。此 JSON API 是有意未文档化的，并可能发生变化。

远程存储 API

状态: 稳定

当使用 `grpc` 存储类型（又称远程存储）时，只要自定义存储后端实现了 gRPC 远程存储 API，Jaeger 就可以使用它们。

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

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

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

远程采样配置

状态: 稳定

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

服务依赖图

状态: 内部

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

• endTs（自 Epoch 以来的毫秒数）- 时间间隔的结束时间
• lookback（毫秒）- 时间间隔的长度（即 start-time + lookback = end-time）。

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

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

服务性能监控

状态: 内部

请参阅 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