OpenTelemetry Java 中为 Spanner 指标添加自定义维度的实践指南

背景介绍

在使用 OpenTelemetry Java SDK 监控 Google Cloud Spanner 应用时，开发者常常需要为系统提供的默认指标添加自定义维度。这些维度可以帮助我们更好地理解指标数据，例如区分不同服务版本或不同环境的监控数据。

问题分析

在 OpenTelemetry Java 生态中，PrometheusHttpServer 是一个常用的指标收集器。当我们尝试通过 Resource 对象为 Spanner 指标添加自定义维度时，可能会发现这些维度并没有如预期那样出现在导出的指标中。

解决方案

1. 创建 Resource 对象

首先，我们需要创建一个包含自定义维度的 Resource 对象：

Resource resource = Resource.getDefault().merge(Resource.create(Attributes.of(
    SERVICE_NAME, "my-service-name",
    SERVICE_VERSION, "1.0.0"
)));

2. 配置 SdkMeterProvider

然后，将这个 Resource 对象设置到 SdkMeterProvider 中：

SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
    .setResource(resource)
    .registerMetricReader(PROMETHEUS_SERVER)
    .build();

3. 关键配置：设置资源属性过滤器

这里有一个关键步骤容易被忽略 - 需要为 PrometheusHttpServer 配置资源属性过滤器：

PrometheusHttpServer.builder()
    .setPort(portNumber)
    .setAllowedResourceAttributesFilter(attrKey -> true) // 允许所有资源属性
    .build();

如果不设置这个过滤器，Prometheus 导出器默认不会包含任何资源属性到指标中。

实现效果

配置完成后，我们可以在导出的指标中看到类似如下的输出：

spanner_max_allowed_sessions_ratio{service_name="my-service-name",service_version="1.0.0",client_id="client-1",database="test-db"} 401.0

最佳实践建议

1. 选择性暴露属性：在生产环境中，建议不要简单地允许所有资源属性，而是有选择地暴露需要的属性：

.setAllowedResourceAttributesFilter(attrKey -> 
    attrKey.getKey().equals("service.name") || 
    attrKey.getKey().equals("service.version"))

2. 性能考虑：添加过多维度可能会影响监控系统的性能，建议只添加必要的业务维度。

3. 命名规范：遵循 OpenTelemetry 的语义约定来命名资源属性，确保一致性。

总结

通过正确配置 PrometheusHttpServer 的资源属性过滤器，我们可以成功地为 Spanner 指标添加自定义维度。这一功能对于实现细粒度的监控和告警策略非常有价值，特别是在微服务架构中，能够帮助我们更好地追踪和分析跨服务的性能问题。

在实际应用中，建议结合业务需求合理设计维度，既满足监控需求，又避免因维度爆炸导致的系统负担。