遥测（Telemetry）

指标（Metrics）

指标通过 Micrometer 发布；它们可以从 Polaris 的管理接口（默认端口为 8182）的 /q/metrics 路径下获取。例如，如果服务器运行在 localhost 上，则可以通过 http://localhost:8181/q/metrics 访问这些指标。

指标可以由 Prometheus 或任何兼容的指标抓取服务器抓取。详情请参阅：Prometheus。

可以通过设置 polaris.metrics.tags.* 属性为指标添加附加标签。每个标签都是一个键值对，其中键为标签名称，值为标签内容。例如，要为所有指标添加标签 environment=prod，请设置 polaris.metrics.tags.environment=prod。可以添加多个标签，示例如下：

polaris.metrics.tags.service=polaris
polaris.metrics.tags.environment=prod
polaris.metrics.tags.region=us-west-2

请注意，默认情况下 Polaris 会添加一个标签：application=Polaris。您可以通过设置 polaris.metrics.tags.application=<new-value> 属性来覆盖此标签。

Realm ID 标签

Polaris 可以将 realm ID 作为标签添加到所有 API 和 HTTP 请求指标中。默认情况下该功能处于禁用状态，以避免出现高基数问题，但可以通过设置以下属性来启用：

polaris.metrics.realm-id-tag.enable-in-api-metrics=true
polaris.metrics.realm-id-tag.enable-in-http-metrics=true

在 HTTP 请求指标中启用 realm ID 标签时应格外小心，因为这些指标的基数通常远高于 API 请求指标。

为防止标签数量无限增长，从而引发性能问题或导致服务器崩溃，HTTP 请求指标中唯一 realm ID 的数量默认限制为 100。如果唯一 realm ID 的数量超过此值，系统将记录一条警告日志，并且不再记录任何 HTTP 请求指标。可以通过设置 polaris.metrics.realm-id-tag.http-metrics-max-cardinality 属性来更改此阈值。

HTTP 请求直方图桶

默认情况下，HTTP 服务器请求耗时计时器仅导出计数、总和和最大值序列。这些数据可以支持平均延迟和最差情况延迟的计算，但无法用于跨实例计算可聚合的百分位数（例如 p95、p99）。

要发布 HTTP 服务器请求耗时的直方图桶，需要配置要发布的服务等级目标（SLO）边界：

polaris.metrics.http-server-requests.histogram-slos=10ms,50ms,100ms,1s,5s

这些分桶可供 Prometheus 的 histogram_quantile 用于估算 p95/p99；其精度取决于所配置的分桶边界。

Traces（链路追踪）

链路追踪通过 OpenTelemetry 发布。

默认情况下，Polaris 中的 OpenTelemetry 是禁用的，因为对于所有场景而言，并不存在一个合理的收集器端点默认值。

要启用 OpenTelemetry 并为 Polaris 发布链路追踪，请将 quarkus.otel.sdk.disabled 设为 false，并通过服务端属性 quarkus.otel.exporter.otlp.traces.endpoint 配置一个有效的收集器端点 URL（需以 http:// 或 https:// 开头）。

如果未设置这些属性，服务器将不会发布链路追踪。

收集器必须使用 OpenTelemetry 协议（OTLP）通信，并且端口必须是其 gRPC 端口（默认为 4317），例如 http://otlp-collector:4317。

默认情况下，Polaris 会在 OpenTelemetry 资源（Resource）中添加若干属性以标识服务器，其中主要包括：

service.name：设置为 Apache Polaris Server；
service.version：设置为 Polaris 的版本号。

你可以通过设置 quarkus.otel.resource.attributes 属性来覆盖默认的资源属性，或添加额外的属性。

该属性需要一个以逗号分隔的键值对列表，其中键为属性名，值为属性值。例如，要将服务名称改为 Polaris 并添加属性 deployment.environment=dev，请设置如下属性：

quarkus.otel.resource.attributes=service.name=Polaris,deployment.environment=dev

也可以使用下面的替代语法：

quarkus.otel.resource.attributes[0]=service.name=Polaris
quarkus.otel.resource.attributes[1]=deployment.environment=dev

最后，所有请求父级 span 都会添加两个额外的 span 属性：

polaris.request.id：请求的唯一标识符，如果调用方通过 X-Request-ID 请求头设置了该值。
polaris.realm：realm 的唯一标识符。始终会被设置（除非请求因 realm 解析错误而失败）。

排查 Trace 问题

如果服务器无法发布 trace，请先检查是否存在类似如下的日志警告信息：

SEVERE [io.ope.exp.int.grp.OkHttpGrpcExporter] (OkHttp http://localhost:4317/...) Failed to export spans.
The request could not be executed. Full error message: Failed to connect to localhost/0:0:0:0:0:0:0:1:4317

这意味着服务器无法连接到采集器。请检查采集器是否正在运行，以及 URL 是否正确。

日志

Polaris 依赖 Quarkus 进行日志记录。

默认情况下，日志会写入控制台以及 ./logs 目录下的文件。日志文件每天轮转一次并进行压缩。日志文件的最大大小为 10MB，备份文件的最大数量为 14。

可以通过将 quarkus.log.console.json.enabled 和 quarkus.log.file.json.enabled 属性设置为 true 来启用 JSON 日志。默认情况下，JSON 日志是禁用的。

日志级别可以针对整个应用程序或特定的包进行设置。默认日志级别为 INFO。要为整个应用程序设置日志级别，请使用 quarkus.log.level 属性。

要为特定的包设置日志级别，请使用 quarkus.log.category."package-name".level，其中 package-name 是包的名称。例如，包 io.smallrye.config 提供了一个有用的记录器，可帮助调试配置问题；但它需要被设置为 DEBUG 级别。这可以通过设置以下属性来完成：

quarkus.log.category."io.smallrye.config".level=DEBUG

控制台与文件输出的日志消息格式均可高度自定义。默认格式如下：

%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] [%X{requestId},%X{realmId}] [%X{traceId},%X{parentId},%X{spanId},%X{sampled}] (%t) %s%e%n

有关占位符以及如何自定义日志消息格式的更多信息，请参阅日志格式指南。

MDC 日志

Polaris 使用映射诊断上下文（Mapped Diagnostic Context，MDC）为日志消息附加额外的上下文信息。可用的 MDC 键如下：

requestId：请求的唯一标识符（若调用方通过 X-Request-ID 头部进行了设置）。
realmId：realm 的唯一标识符。始终存在。
traceId：链路追踪的唯一标识符。当启用链路追踪且消息来源于被追踪的上下文时存在。
parentId：父 span 的唯一标识符。当启用链路追踪且消息来源于被追踪的上下文时存在。
spanId：span 的唯一标识符。当启用链路追踪且消息来源于被追踪的上下文时存在。
sampled：该链路追踪是否已被采样。当启用链路追踪且消息来源于被追踪的上下文时存在。

可以通过设置 polaris.log.mdc.* 属性来添加其他 MDC 键。每个属性均为一个键值对，其中键为 MDC 键名，值为该 MDC 键对应的值。例如，要为所有日志消息添加 MDC 键 environment=prod 和 region=us-west-2，请设置以下属性：

polaris.log.mdc.environment=prod
polaris.log.mdc.region=us-west-2

MDC 上下文会在各线程之间传播，包括 TaskExecutor 线程中。

链接

请访问配合遥测工具使用 Polaris，查看包含 Prometheus 和 Jaeger 的 Polaris 示例配置。

遥测