Instrumentation 选项

Instrumentation 自定义资源提供了多种配置选项，用于控制如何将自动埋点应用到你的应用。通过这些选项，你可以自定义埋点行为、指定资源需求，并配置特定语言的设置。

WARNING

Alauda 构建版本的 OpenTelemetry v2 Operator 提供了用于 Instrumentation 的自动注入机制，但不包含预构建的埋点库或容器镜像。你需要自行构建埋点镜像，或使用社区提供的镜像。

基本 Instrumentation 配置

Instrumentation 自定义资源（CR）定义了如何从你的应用中收集遥测数据。它提供了 exporter 端点、上下文传播、采样以及特定语言埋点的设置。

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: my-instrumentation
spec:
  env:
    - name: OTEL_EXPORTER_OTLP_TIMEOUT
      value: "20"
  exporter:
    endpoint: 'http://otel-collector.otel-collector.svc:4317'
  propagators:
    - tracecontext
    - baggage
    - b3multi
  sampler:
    type: parentbased_traceidratio
    argument: "0.25"
  python:
    env:
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: 'http://otel-collector.otel-collector.svc:4318'
  dotnet:
    env:
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: 'http://otel-collector.otel-collector.svc:4318'
  go:
    env:
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: 'http://otel-collector.otel-collector.svc:4318'

Collector 接收遥测数据的 exporter 端点。默认协议是在端口 4317 上使用 gRPC。
上下文传播格式。支持的值包括 tracecontext、baggage、b3、b3multi、jaeger、ottrace 和 none。
用于控制 trace 数据量的 sampler 配置。类型为 parentbased_traceidratio 且参数为 0.25 表示会对 25% 的新根 trace 进行采样。
Python 自动埋点默认使用 otlp/http。端点必须指向 Collector 的 HTTP 端口 4318。
.NET 自动埋点默认使用 otlp/http。端点必须指向 Collector 的 HTTP 端口 4318。
Go 自动埋点默认使用 otlp/http。端点必须指向 Collector 的 HTTP 端口 4318。

Instrumentation CR 参数

下表描述了可以在 Instrumentation 自定义资源中配置的参数。

参数	描述	值
`env`	各类埋点共享的通用环境变量。
`exporter`	用于传递遥测数据的 exporter 配置。
`propagators`	进程间上下文传播配置。	`tracecontext`、`baggage`、`b3`、`b3multi`、`jaeger`、`ottrace`、`none`
`resource`	用于遥测标识的资源属性配置。
`sampler`	用于控制遥测数据量的采样配置。
`apacheHttpd`	Apache HTTP Server 埋点设置。
`dotnet`	.NET 埋点设置。
`go`	Go 埋点设置。
`java`	Java 埋点设置。
`nodejs`	Node.js 埋点设置。
`python`	Python 埋点设置。

默认自动埋点协议

每种自动埋点语言都会使用默认协议将遥测数据导出到 Collector。下表列出了默认协议。

自动埋点	默认协议
Java 1.x	`otlp/grpc`
Java 2.x	`otlp/http`
Python	`otlp/http`
.NET	`otlp/http`
Go	`otlp/http`
Apache HTTP Server	`otlp/grpc`

NOTE

你可以在 Instrumentation CR 上配置环境变量。但是，在 Operator 将这些环境变量注入应用容器之后，不能仅通过更新或删除 Instrumentation CR 来移除它们。要移除已注入的环境变量，必须重启或重新部署受影响的 pod。

基于注解的注入

要为你的应用启用自动埋点，请向 pod 或 namespace 添加相应的注解：

apiVersion: v1
kind: Pod
metadata:
  name: myapp
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
spec:
  containers:
  - name: app
    image: myapp:latest

特定语言注入

注解格式为 instrumentation.opentelemetry.io/inject-<language>，其中 <language> 可以是：

apache-httpd - 适用于 Apache HTTP Server
dotnet - 适用于 .NET 应用
go - 适用于 Go 应用
java - 适用于 Java 应用
nodejs - 适用于 Node.js 应用
python - 适用于 Python 应用

SDK 变量注入

你可以使用 instrumentation.opentelemetry.io/inject-sdk 注解，指示 OpenTelemetry Operator 将 SDK 环境变量注入到你的 pod 中。

TIP

当你希望注入 SDK 环境变量，但不启用特定语言的自动埋点时，inject-sdk 注解非常有用。对于已经包含 OpenTelemetry SDK 依赖，但仍需要集中式配置管理的应用，这尤其适合。

注入注解支持的值

值	描述
`"true"`	从当前 namespace 注入默认名称的 `Instrumentation` 资源
`"false"`	不注入任何 `Instrumentation` 资源
`"<instrumentation_name>"`	指定要从当前 namespace 注入的 `Instrumentation` 资源名称
`"<namespace>/<instrumentation_name>"`	指定要从其他 namespace 注入的 `Instrumentation` 资源名称

Namespace 级别的 Instrumentation

你可以通过为 namespace 本身添加注解，将埋点应用到该 namespace 中的所有 pod：

apiVersion: v1
kind: Namespace
metadata:
  name: production
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"

TIP

Namespace 级别的注解提供了一种便捷方式，可以在不修改单个 pod 规范的情况下，为环境中的所有应用启用埋点。

资源配置

你可以为埋点 init container 指定 resource requests 和 limits：

spec:
  resource:
    limits:
      cpu: 500m
      memory: 128Mi
    requests:
      cpu: 100m
      memory: 64Mi

环境变量注入

Instrumentation CR 允许你向已埋点的容器注入额外的环境变量：

spec:
  env:
    - name: OTEL_TRACES_EXPORTER
      value: otlp
    - name: OTEL_METRICS_EXPORTER
      value: otlp
    - name: OTEL_LOGS_EXPORTER
      value: otlp

当注入埋点时，这些环境变量会自动添加到应用容器中。

选择性埋点

你可以通过使用容器特定的注解，控制多容器 pod 中哪些容器接收埋点：

metadata:
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
    instrumentation.opentelemetry.io/container-names: "app,sidecar"

该注解可确保仅对指定容器进行埋点，而其他容器保持不变。

NOTE

如果未指定 container-names 注解，则默认会将埋点应用到 pod 中的第一个容器。

Instrumentation 引用

要引用特定的 Instrumentation CR，你可以在注解中使用完整引用格式：

metadata:
  annotations:
    instrumentation.opentelemetry.io/inject-java: "namespace/instrumentation-name"

这样你就可以在同一个 namespace 中为不同的应用使用不同的埋点配置。

#Instrumentation 选项

#目录

#基本 Instrumentation 配置

#Instrumentation CR 参数

#默认自动埋点协议

#基于注解的注入

#特定语言注入

#SDK 变量注入

#注入注解支持的值

#Namespace 级别的 Instrumentation

#资源配置

#环境变量注入

#选择性埋点

#Instrumentation 引用