ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.1.0

Kubernetes 的 OpenTelemetry Operator

OpenTelemetry Operator 是 Kubernetes Operator 的一种实现。

该 Operator 管理：

• https://github.com/open-telemetry/opentelemetry-collector%EF%BC%88OpenTelemetry 收集器）
• 使用 OpenTelemetry instrumentation 库对工作负载进行自动 instrumentation

文档

• 兼容性与支持文档
• API 文档
• 官方 OpenTelemetry Operator 页面

Helm 图表

您可以通过 opentelemetry-helm-charts 仓库中的 https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator 安装 OpenTelemetry Operator。更多信息可在 https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator 获取。

为初始化容器（Init Containers）插桩

可通过在 container-names 注解中包含初始化容器的名称来为其插桩。当目标初始化容器被指定进行插桩时，Operator 会在 Pod 的初始化容器序列中，自动将插桩初始化容器插入到目标初始化容器之前。这样可以确保目标初始化容器运行时，插桩代理文件已准备就绪。

支持为初始化容器进行插桩的类型：

• Java
• Python
• Node.js
• .NET
• SDK-only injection（仅 SDK 注入）

不支持为初始化容器进行插桩的类型：

• Go（不支持多容器 Pod）
• Apache HTTPD
• Nginx

[!NOTE] Kubernetes 保证在 Pod 规范的 initContainers 和 containers 列表中，容器名称是唯一的。这使得 Operator 能够明确识别容器名称是指初始化容器还是常规容器。

同时对初始化容器和常规容器进行插桩的示例：

apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment-with-init-container
spec:
selector:
matchLabels:
app: my-app
replicas: 1
template:
metadata:
labels:
app: my-app
annotations:
instrumentation.opentelemetry.io/inject-python: "true"
instrumentation.opentelemetry.io/container-names: "my-init-job,myapp"
spec:
initContainers:
- name: my-init-job
image: my-python-init-image
containers:
- name: myapp
image: my-python-app-image

在此示例中，my-init-job（初始化容器）和 myapp（常规容器）都将使用 Python 自动插桩进行插桩。

仅注入 OpenTelemetry SDK 环境变量

对于当前无法自动插桩的应用程序，你可以通过使用 inject-sdk 替代 inject-python 或 inject-java 来配置 OpenTelemetry SDK。这将注入环境变量，如 OTEL_RESOURCE_ATTRIBUTES、OTEL_TRACES_SAMPLER 和 OTEL_EXPORTER_OTLP_ENDPOINT，你可以在 Instrumentation 中配置这些变量，但不会实际提供 SDK。

instrumentation.opentelemetry.io/inject-sdk: "true"

控制插桩功能

操作员允许通过标志指定 Instrumentation 资源可以插桩的语言。如果某种语言默认启用，则仅在禁用该语言时需要提供其开关。通过传递值为 false 的标志可以禁用语言支持。

OpenTelemetry Operator 允许使用多种特定语言的插桩工具为多个容器进行插桩。可通过 enable-multi-instrumentation 标志启用这些功能。该标志默认值为 false。

有关多插桩功能的更多信息，请参见 多容器 Pod 与多插桩。

目标分配器

OpenTelemetry Operator 附带一个可选组件：目标分配器（TA）。创建 OpenTelemetryCollector 自定义资源（CR）并将 TA 设置为启用状态时，操作员将创建新的部署和服务，为该 CR 中的每个 Collector pod 提供特定的 http_sd_config 指令。它还会重写 CR 中的 Prometheus 接收器配置，以使用已部署的目标分配器。以下示例展示了如何开始使用目标分配器：

kubectl apply -f - <<EOF
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
name: collector-with-ta
spec:
mode: statefulset
targetAllocator:
enabled: true
config:
receivers:
prometheus:
config:
scrape_configs:
- job_name: 'otel-collector'
scrape_interval: 10s
static_configs:
- targets: [ '0.0.0.0:8888' ]
metric_relabel_configs:
- action: labeldrop
regex: (id|name)
- action: labelmap
regex: label_(.+)
replacement: $1

exporters:
debug: {}

service:
pipelines:
metrics:
receivers: [prometheus]
exporters: [debug]
EOF

上述示例中替换键中 `# Kubernetes 的 OpenTelemetry Operator

OpenTelemetry Operator 是 Kubernetes Operator 的一种实现。

该 Operator 管理：

• https://github.com/open-telemetry/opentelemetry-collector%EF%BC%88OpenTelemetry 收集器）
• 使用 OpenTelemetry instrumentation 库对工作负载进行自动 instrumentation

文档

• 兼容性与支持文档
• API 文档
• 官方 OpenTelemetry Operator 页面

Helm 图表

您可以通过 opentelemetry-helm-charts 仓库中的 https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator 安装 OpenTelemetry Operator。更多信息可在 https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator 获取。

为初始化容器（Init Containers）插桩

可通过在 container-names 注解中包含初始化容器的名称来为其插桩。当目标初始化容器被指定进行插桩时，Operator 会在 Pod 的初始化容器序列中，自动将插桩初始化容器插入到目标初始化容器之前。这样可以确保目标初始化容器运行时，插桩代理文件已准备就绪。

支持为初始化容器进行插桩的类型：

• Java
• Python
• Node.js
• .NET
• SDK-only injection（仅 SDK 注入）

不支持为初始化容器进行插桩的类型：

• Go（不支持多容器 Pod）
• Apache HTTPD
• Nginx

[!NOTE] Kubernetes 保证在 Pod 规范的 initContainers 和 containers 列表中，容器名称是唯一的。这使得 Operator 能够明确识别容器名称是指初始化容器还是常规容器。

同时对初始化容器和常规容器进行插桩的示例：

apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment-with-init-container
spec:
selector:
matchLabels:
app: my-app
replicas: 1
template:
metadata:
labels:
app: my-app
annotations:
instrumentation.opentelemetry.io/inject-python: "true"
instrumentation.opentelemetry.io/container-names: "my-init-job,myapp"
spec:
initContainers:
- name: my-init-job
image: my-python-init-image
containers:
- name: myapp
image: my-python-app-image

在此示例中，my-init-job（初始化容器）和 myapp（常规容器）都将使用 Python 自动插桩进行插桩。

仅注入 OpenTelemetry SDK 环境变量

对于当前无法自动插桩的应用程序，你可以通过使用 inject-sdk 替代 inject-python 或 inject-java 来配置 OpenTelemetry SDK。这将注入环境变量，如 OTEL_RESOURCE_ATTRIBUTES、OTEL_TRACES_SAMPLER 和 OTEL_EXPORTER_OTLP_ENDPOINT，你可以在 Instrumentation 中配置这些变量，但不会实际提供 SDK。

instrumentation.opentelemetry.io/inject-sdk: "true"

控制插桩功能

操作员允许通过标志指定 Instrumentation 资源可以插桩的语言。如果某种语言默认启用，则仅在禁用该语言时需要提供其开关。通过传递值为 false 的标志可以禁用语言支持。

OpenTelemetry Operator 允许使用多种特定语言的插桩工具为多个容器进行插桩。可通过 enable-multi-instrumentation 标志启用这些功能。该标志默认值为 false。

有关多插桩功能的更多信息，请参见 多容器 Pod 与多插桩。

目标分配器

OpenTelemetry Operator 附带一个可选组件：目标分配器（TA）。创建 OpenTelemetryCollector 自定义资源（CR）并将 TA 设置为启用状态时，操作员将创建新的部署和服务，为该 CR 中的每个 Collector pod 提供特定的 http_sd_config 指令。它还会重写 CR 中的 Prometheus 接收器配置，以使用已部署的目标分配器。以下示例展示了如何开始使用目标分配器：

kubectl apply -f - <<EOF
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
name: collector-with-ta
spec:
mode: statefulset
targetAllocator:
enabled: true
config:
receivers:
prometheus:
config:
scrape_configs:
- job_name: 'otel-collector'
scrape_interval: 10s
static_configs:
- targets: [ '0.0.0.0:8888' ]
metric_relabel_configs:
- action: labeldrop
regex: (id|name)
- action: labelmap
regex: label_(.+)
replacement: $1

exporters:
debug: {}

service:
pipelines:
metrics:
receivers: [prometheus]
exporters: [debug]
EOF

上述示例中替换键中 的使用基于 Prometheus 接收器 https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/prometheusreceiver/README.md 文档提供的信息，该文档指出：
注意：由于收集器配置支持环境变量替换，因此 Prometheus 配置中的 $ 字符会被解释为环境变量。如果要在 Prometheus 配置中使用 $ 字符，必须使用 $ 进行转义。

在幕后，OpenTelemetry Operator 会在协调后将收集器的配置转换为以下内容：

receivers:
prometheus:
target_allocator:
endpoint: http://collector-with-ta-targetallocator:80
interval: 30s
collector_id: $POD_NAME

exporters:
debug:

service:
pipelines:
metrics:
receivers: [prometheus]
exporters: [debug]

OpenTelemetry Operator 还会在协调后将目标分配器的 Prometheus 配置转换为以下内容：

config:
scrape_configs:
- job_name: otel-collector
scrape_interval: 10s
static_configs:
- targets: ["0.0.0.0:8888"]
metric_relabel_configs:
- action: labeldrop
regex: (id|name)
- action: labelmap
regex: label_(.+)
replacement: $1

请注意，在这种情况下，操作员会将替换键中的 "$$" 替换为单个 "$"。这是因为收集器支持环境变量替换，而 TA（目标分配器）不支持。因此，为确保兼容性，TA 配置应仅包含单个 "$" 符号。

有关 TargetAllocator 的更多信息，请参见 此处。

使用 Prometheus 自定义资源进行服务发现

目标分配器可以使用 prometheus-operator 生态系统中的自定义资源（如 ServiceMonitor 和 PodMonitor）进行服务发现，执行与 prometheus-operator 本身类似的功能。这可通过 Collector CR 中的 prometheusCR 部分启用。

以下是一个最小示例：

kubectl apply -f - <<EOF
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
name: collector-with-ta-prometheus-cr
spec:
mode: statefulset
targetAllocator:
enabled: true
serviceAccount: everything-prometheus-operator-needs
prometheusCR:
enabled: true
serviceMonitorSelector: {}
podMonitorSelector: {}
scrapeClasses: []
config:
receivers:
prometheus:
config: {}

exporters:
debug: {}

service:
pipelines:
metrics:
receivers: [prometheus]
exporters: [debug]
EOF

scrapeClasses 属性引用 Prometheus Operator 的 ScrapeClass 功能。有关抓取类的更多信息，请参阅 [***]

设置资源属性的优先级

设置资源属性的优先级如下（最先找到的值生效）：

1. 通过 OTEL_RESOURCE_ATTRIBUTES 和 OTEL_SERVICE_NAME 环境变量设置的资源属性
2. 通过注解（带有 resource.opentelemetry.io/ 前缀）设置的资源属性
3. 通过标签（例如 app.kubernetes.io/name）设置的资源属性（前提是 Instrumentation CR 的 defaults.useLabelsForResourceAttributes=true，见上文）
4. 从 Pod 的元数据计算得出的资源属性（例如 k8s.pod.name）
5. 通过 Instrumentation CR（在 spec.resource.resourceAttributes 部分）设置的资源属性

此优先级针对每个资源属性单独应用，因此可以通过注解设置某些属性，同时通过标签设置其他属性。

如何从 Pod 的元数据计算资源属性

以下资源属性是从 Pod 的元数据计算得出的。

如何计算 service.name

选择第一个找到的值：

• pod.annotation[resource.opentelemetry.io/service.name]
• if (config[useLabelsForResourceAttributes]) pod.label[app.kubernetes.io/name]
• k8s.deployment.name
• k8s.replicaset.name
• k8s.statefulset.name
• k8s.daemonset.name
• k8s.cronjob.name
• k8s.job.name
• k8s.pod.name
• k8s.container.name

如何计算 service.version

选择第一个找到的值：

• pod.annotation[resource.opentelemetry.io/service.version]
• if (cfg[useLabelsForResourceAttributes]) pod.label[app.kubernetes.io/version]
• if (contains(container docker image tag, '/') == false) container docker image tag

如何计算 service.instance.id

选择第一个找到的值：

• pod.annotation[resource.opentelemetry.io/service.instance.id]
• concat([k8s.namespace.name, k8s.pod.name, k8s.container.name], '.')

如何计算 service.namespace

选择第一个找到的值：

• pod.annotation[resource.opentelemetry.io/service.namespace]
• k8s.namespace.name