Instrumentation 选项

Instrumentation 自定义资源提供了多种配置选项，用于控制如何将自动插桩应用到你的应用程序。这些选项允许你自定义插桩行为、指定资源需求，并配置语言特定设置。

WARNING

Alauda build of OpenTelemetry v2 Operator 提供了 instrumentation 的自动注入机制，但不包含预构建的 instrumentation 库或容器镜像。你需要自行构建 instrumentation 镜像，或使用 Community 提供的镜像。

基本 Instrumentation 配置 Instrumentation CR 参数默认 Auto-Instrumentation 协议基于注解的注入语言特定注入 SDK 变量注入注入注解支持的值 Namespace 级别 Instrumentation 资源配置安全上下文配置环境变量注入选择性 Instrumentation Instrumentation 引用

基本 Instrumentation 配置

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

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 数据量的采样器配置。parentbased_traceidratio 类型配合 0.25 参数表示对 25% 的新根 trace 进行采样。
Python auto-instrumentation 默认使用 otlp/http。端点必须指向 Collector 的 HTTP 端口 4318。
.NET auto-instrumentation 默认使用 otlp/http。端点必须指向 Collector 的 HTTP 端口 4318。
Go auto-instrumentation 默认使用 otlp/http。端点必须指向 Collector 的 HTTP 端口 4318。

Instrumentation CR 参数

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

Parameter	Description	Values
`env`	所有 instrumentation 类型共享的通用环境变量。
`exporter`	用于传递遥测数据的 exporter 配置。
`propagators`	进程间上下文传播配置。	`tracecontext`、`baggage`、`b3`、`b3multi`、`jaeger`、`ottrace`、`none`
`resource`	用于遥测标识的资源属性配置。
`sampler`	用于控制遥测数据量的采样配置。
`initContainerSecurityContext`	应用于自动插桩 init container 的安全上下文。
`apacheHttpd`	Apache HTTP Server instrumentation 设置。
`dotnet`	.NET instrumentation 设置。
`go`	Go instrumentation 设置。
`java`	Java instrumentation 设置。
`nodejs`	Node.js instrumentation 设置。
`python`	Python instrumentation 设置。

默认 Auto-Instrumentation 协议

每种 auto-instrumentation 语言都会使用默认协议将遥测数据导出到 Collector。下表列出了默认协议。

Auto-instrumentation	默认协议
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 applications
go - 适用于 Go applications
java - 适用于 Java applications
nodejs - 适用于 Node.js applications
python - 适用于 Python applications

SDK 变量注入

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

TIP

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

注入注解支持的值

Value	Description
`"true"`	使用当前 namespace 中默认名称的 `Instrumentation` 资源进行注入
`"false"`	不注入任何 `Instrumentation` 资源
`"<instrumentation_name>"`	指定要从当前 namespace 注入的 `Instrumentation` 资源名称
`"<namespace>/<instrumentation_name>"`	指定要从其他 namespace 注入的 `Instrumentation` 资源名称

Namespace 级别 Instrumentation

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

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

TIP

Namespace 级别注解提供了一种便捷方式，无需修改单个 pod 规格即可为环境中的所有应用启用 instrumentation。

资源配置

你可以为 instrumentation init container 指定资源请求和限制：

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

安全上下文配置

默认情况下，自动插桩 init container 会继承其所插桩的第一个应用容器的安全上下文，而 Go sidecar 会保留 eBPF 所需的设置（privileged: true 和 runAsUser: 0）。在实施受限 Pod Security Admission 的集群中，继承上下文并不总是足够的——你可能需要显式声明 capabilities。

使用 spec.initContainerSecurityContext 为注入到 Java、Node.js、Python、.NET、Apache HTTP Server 和 Nginx 的 init container 设置安全上下文：

spec:
  initContainerSecurityContext:
    allowPrivilegeEscalation: false
    runAsNonRoot: true
    runAsUser: 1000
    capabilities:
      drop:
        - ALL
    seccompProfile:
      type: RuntimeDefault

适用于每个语言的 init container。未设置时，每个 init container 都会继承其所插桩的应用容器的安全上下文。

使用 spec.go.securityContext 覆盖 Go instrumentation sidecar 的默认值：

spec:
  go:
    securityContext:
      privileged: true
      runAsUser: 0

覆盖 Go sidecar 的默认值。Go auto-instrumentation 依赖 eBPF，因此移除这里显示的提升权限通常会阻止其附加到应用进程。

WARNING

仅当你确认最终得到的上下文仍满足 Go instrumentation 的 eBPF 要求时，才覆盖 spec.go.securityContext。保持该字段未设置会保留 Go sidecar 附加到应用进程所需的默认值。

环境变量注入

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

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

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

选择性 Instrumentation

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

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

该注解可确保只有指定的容器会被插桩，而其他容器保持不变。

NOTE

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

Instrumentation 引用

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

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

这使你能够为同一 namespace 中的不同应用使用不同的 instrumentation 配置。

#Instrumentation 选项

#目录

#基本 Instrumentation 配置

#Instrumentation CR 参数

#默认 Auto-Instrumentation 协议

#基于注解的注入

#语言特定注入

#SDK 变量注入

#注入注解支持的值

#Namespace 级别 Instrumentation

#资源配置

#安全上下文配置

#环境变量注入

#选择性 Instrumentation

#Instrumentation 引用