OpenTelemetry 配置

欢迎回到第 9 章的学习。在上一节，我们添加了 OpenTelemetry 依赖。现在我们要配置 OpenTelemetry，让它能够正常工作和发送数据。

本节将学习：application.properties 配置、服务名称配置、Collector 端点配置、以及采样率配置。

application.properties 配置

OpenTelemetry 配置在哪里？ 在

src/main/resources/application.properties

application.yml

基本配置结构是什么？

• 服务名称：

  otel.service.name=order-service

  ，用于标识服务。
• Collector 端点：

  otel.exporter.otlp.endpoint=http://localhost:4317

  ，OTLP gRPC 端点地址。
• Exporter 类型：

  otel.traces.exporter=otlp

  ，指定导出器类型。

初始配置文件：

文件路径：

src/main/resources/application.properties

# App configuration
spring.application.name=order-service
server.port=8080

# Actuator provisioning
management.endpoints.web.exposure.include=health,info,metrics

# OpenTelemetry provisioning
# Service name (required)）
otel.service.name=order-service

# Collector Endpoint (required)）
otel.exporter.otlp.endpoint=http://localhost:4317

# Exporter Type (required）
otel.traces.exporter=otlp
otel.metrics.exporter=otlp
otel.logs.exporter=otlp

配置文件用于配置应用参数。

服务名称配置

服务名称的作用是什么？ 标识服务，在 Trace 和 Metrics 中显示，用于服务区分和筛选。

命名原则是什么？

• 唯一性： 每个服务应该有唯一的名称。
• 描述性： 名称应该清楚描述服务的功能。
• 格式： 使用小写字母和连字符（如

  order-service

  ）。
• 避免： 避免使用空格、大写字母、特殊字符。

配置代码：

# Service name configuration
# Required: Service name (unique identifier)）
otel.service.name=order-service

# Optional: Namespace
otel.service.namespace=shoebub

# Optional: Service version
otel.service.version=1.0.0

命名示例：

• ✅ 正确：

  order-service

  、

  user-service

  、

  payment-service

• ❌ 错误：

  Order Service

  、

  orderService

  、

  order_service

服务名称很重要，用于服务识别和管理。

Collector 端点配置

Collector 端点配置是什么？

协议： OTLP gRPC（默认端口 4317），OTLP HTTP（默认端口 4318）。

配置项：

otel.exporter.otlp.endpoint

otel.exporter.otlp.protocol

配置代码（gRPC，推荐）：

# Collector Endpoint Configurations（gRPC，recommends）
otel.exporter.otlp.endpoint=http://localhost:4317
otel.exporter.otlp.protocol=grpc

配置代码（HTTP，备选）：

# Collector Endpoint Configurations（HTTP，Alternate）
otel.exporter.otlp.endpoint=http://localhost:4318
otel.exporter.otlp.protocol=http/protobuf

协议对比：

协议选择： gRPC 性能更好，推荐生产环境使用，HTTP 兼容性更好，适合调试。

端点配置决定数据发送到哪里，很重要。

采样率配置

采样率的作用是什么？ 控制 Trace 数据的收集量，降低存储和处理成本，保持数据完整性。

采样策略有哪些呢？

• always_on： 100% 采样，开发环境使用。
• always_off： 0% 采样，测试用。
• traceidratio： 概率采样，生产环境推荐。
• parentbased： 继承父级采样决策。

配置代码（开发环境，100%采样）：

# Sampling rate configuration (development environment)）
otel.traces.sampler=always_on

配置代码（生产环境，10%采样）：

# Sampling rate configuration (production environment)）
otel.traces.sampler=parentbased_traceidratio
otel.traces.sampler.arg=0.1

配置代码（高流量环境，1%采样）：

# Sampling rate configuration (high traffic environment）
otel.traces.sampler=parentbased_traceidratio
otel.traces.sampler.arg=0.01

采样率选择建议：

选择合适的采样率： 开发环境 1.0（100%），生产环境 0.1（10%），高流量环境 0.01（1%）。

采样率很重要，需要在成本和完整性之间平衡。

本节小结

在本节中，我们学习了 OpenTelemetry 配置：

第一个是 application.properties 配置。 OpenTelemetry 配置文件位置，基本配置结构。

第二个是服务名称配置。 唯一且描述性的服务标识，命名原则，命名空间和版本（可选）。

第三个是 Collector 端点配置。 gRPC（推荐，性能更好）或 HTTP（备选，兼容性更好），协议选择。

第四个是采样率配置。 根据环境选择合适的采样策略，开发环境 100%，生产环境 10%。

配置流程： 打开配置文件 → 配置服务名称 → 配置 Collector 端点 → 配置采样率 → 保存配置 → 重启应用。

这就是 OpenTelemetry 配置。配置完成后，应用就可以发送 Trace、Metrics、Logs 数据了。

在下一节，我们将学习自动插桩：HTTP 请求追踪。学习 Spring MVC 自动追踪和 Span 属性。