Instrumentation 选项

Instrumentation 自定义资源提供了多种配置选项，用于控制如何对您的应用程序进行自动化埋点。这些选项允许您自定义埋点行为、指定资源需求以及配置特定语言的设置。

WARNING

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

基础埋点配置

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

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 接收遥测数据的导出端点。默认协议为 gRPC，端口为 4317。
上下文传播格式。支持的值包括 tracecontext、baggage、b3、b3multi、jaeger、ottrace 和 none。
采样器配置，用于控制追踪数据的采样量。parentbased_traceidratio 类型，参数为 0.25 表示采样 25% 的新根追踪。
Python 自动埋点默认使用 otlp/http，端点必须指向 Collector 的 HTTP 端口 4318。
.NET 自动埋点默认使用 otlp/http，端点必须指向 Collector 的 HTTP 端口 4318。
Go 自动埋点默认使用 otlp/http，端点必须指向 Collector 的 HTTP 端口 4318。

Instrumentation CR 参数

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

参数	描述	可选值
`env`	所有埋点类型共享的通用环境变量。
`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 或命名空间上添加相应注解：

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 向 Pod 注入 SDK 环境变量。

TIP

inject-sdk 注解适用于您希望注入 SDK 环境变量，但不启用语言特定自动埋点的场景。特别适合已经包含 OpenTelemetry SDK 依赖但需要集中配置管理的应用。

注入注解支持的值

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

命名空间级别埋点

您可以通过注解命名空间本身，为该命名空间内的所有 Pod 应用埋点：

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

TIP

命名空间级注解为您提供了一种便捷方式，无需修改单个 Pod 规格即可为环境中的所有应用启用埋点。

资源配置

您可以为埋点 init 容器指定资源请求和限制：

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"

这允许您在同一命名空间内为不同应用使用不同的埋点配置。

#Instrumentation 选项

#目录

#基础埋点配置

#Instrumentation CR 参数

#默认自动埋点协议

#基于注解的注入

#语言特定注入

#SDK 变量注入

#注入注解支持的值

#命名空间级别埋点

#资源配置

#环境变量注入

#选择性埋点

#Instrumentation 引用