自动仪表化

如果您正在使用 OpenTelemetry Operator 的自动注入功能，但没有看到任何追踪或指标，请按照以下故障排除步骤了解情况。

故障排除步骤

检查安装状态

安装 Instrumentation 资源后，请运行以下命令确保其已正确安装。

kubectl describe otelinst -n <namespace>

其中 <namespace> 是部署 Instrumentation 资源的命名空间。

您的输出应如下所示

Name:         python-instrumentation
Namespace:    application
Labels:       app.kubernetes.io/managed-by=opentelemetry-operator
Annotations:  instrumentation.opentelemetry.io/default-auto-instrumentation-apache-httpd-image:
               ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-apache-httpd:1.0.3
             instrumentation.opentelemetry.io/default-auto-instrumentation-dotnet-image:
               ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-dotnet:0.7.0
             instrumentation.opentelemetry.io/default-auto-instrumentation-go-image:
               ghcr.io/open-telemetry/opentelemetry-go-instrumentation/autoinstrumentation-go:v0.2.1-alpha
             instrumentation.opentelemetry.io/default-auto-instrumentation-java-image:
               ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:1.26.0
             instrumentation.opentelemetry.io/default-auto-instrumentation-nodejs-image:
               ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-nodejs:0.40.0
             instrumentation.opentelemetry.io/default-auto-instrumentation-python-image:
               ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-python:0.39b0
API Version:  opentelemetry.io/v1alpha1
Kind:         Instrumentation
Metadata:
 Creation Timestamp:  2023-07-28T03:42:12Z
 Generation:          1
 Resource Version:    3385
 UID:                 646661d5-a8fc-4b64-80b7-8587c9865f53
Spec:
...
 Exporter:
   Endpoint:  http://otel-collector-collector.opentelemetry.svc.cluster.local:4318
...
 Propagators:
   tracecontext
   baggage
 Python:
   Image:  ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-python:0.39b0
   Resource Requirements:
     Limits:
       Cpu:     500m
       Memory:  32Mi
     Requests:
       Cpu:     50m
       Memory:  32Mi
 Resource:
 Sampler:
Events:  <none>

检查 OpenTelemetry Operator 日志

运行以下命令检查 OpenTelemetry Operator 日志是否存在错误。

kubectl logs -l app.kubernetes.io/name=opentelemetry-operator --container manager -n opentelemetry-operator-system --follow

日志中不应显示任何与自动注入相关的错误。

检查部署顺序

确保部署顺序正确。Instrumentation 资源必须在部署相应进行自动注入的 Deployment 资源之前进行部署。

请考虑以下自动注入注解代码片段

annotations:
  instrumentation.opentelemetry.io/inject-python: 'true'

当 Pod 启动时，注解会指示 Operator 在 Pod 的命名空间中查找 Instrumentation 资源，并将 Python 自动注入到 Pod 中。它会向应用程序的 Pod 添加一个名为 opentelemetry-auto-instrumentation 的 init-container，然后该 init-container 用于将自动注入注入到应用容器中。

您可以通过运行以下命令看到这一点

kubectl describe pod <your_pod_name> -n <namespace>

其中 <namespace> 是您 Pod 部署的命名空间。结果输出应类似于以下示例，该示例显示了 Pod 规范在自动注入后可能的样子。

Name:             py-otel-server-f89fdbc4f-mtsps
Namespace:        opentelemetry
Priority:         0
Service Account:  default
Node:             otel-target-allocator-talk-control-plane/172.24.0.2
Start Time:       Mon, 15 Jul 2024 17:23:45 -0400
Labels:           app=my-app
                  app.kubernetes.io/name=py-otel-server
                  pod-template-hash=f89fdbc4f
Annotations:      instrumentation.opentelemetry.io/inject-python: true
Status:           Running
IP:               10.244.0.10
IPs:
  IP:           10.244.0.10
Controlled By:  ReplicaSet/py-otel-server-f89fdbc4f
Init Containers:
  opentelemetry-auto-instrumentation-python:
    Container ID:  containerd://20ecf8766247e6043fcad46544dba08c3ef534ee29783ca552d2cf758a5e3868
    Image:         ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-python:0.45b0
    Image ID:      ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-python@sha256:3ed1122e10375d527d84c826728f75322d614dfeed7c3a8d2edd0d391d0e7973
    Port:          <none>
    Host Port:     <none>
    Command:
      cp
      -r
      /autoinstrumentation/.
      /otel-auto-instrumentation-python
    State:          Terminated
      Reason:       Completed
      Exit Code:    0
      Started:      Mon, 15 Jul 2024 17:23:51 -0400
      Finished:     Mon, 15 Jul 2024 17:23:51 -0400
    Ready:          True
    Restart Count:  0
    Limits:
      cpu:     500m
      memory:  32Mi
    Requests:
      cpu:        50m
      memory:     32Mi
    Environment:  <none>
    Mounts:
      /otel-auto-instrumentation-python from opentelemetry-auto-instrumentation-python (rw)
      /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-x2nmj (ro)
Containers:
  py-otel-server:
    Container ID:   containerd://95fb6d06b08ead768f380be2539a93955251be6191fa74fa2e6e5616036a8f25
    Image:          otel-target-allocator-talk:0.1.0-py-otel-server
    Image ID:       docker.io/library/import-2024-07-15@sha256:a2ed39e9a39ca090fedbcbd474c43bac4f8c854336a8500e874bd5b577e37c25
    Port:           8082/TCP
    Host Port:      0/TCP
    State:          Running
      Started:      Mon, 15 Jul 2024 17:23:52 -0400
    Ready:          True
    Restart Count:  0
    Environment:
      OTEL_NODE_IP:                                       (v1:status.hostIP)
      OTEL_POD_IP:                                        (v1:status.podIP)
      OTEL_METRICS_EXPORTER:                             console,otlp_proto_http
      OTEL_LOGS_EXPORTER:                                otlp_proto_http
      OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED:  true
      PYTHONPATH:                                        /otel-auto-instrumentation-python/opentelemetry/instrumentation/auto_instrumentation:/otel-auto-instrumentation-python
      OTEL_TRACES_EXPORTER:                              otlp
      OTEL_EXPORTER_OTLP_TRACES_PROTOCOL:                http/protobuf
      OTEL_EXPORTER_OTLP_METRICS_PROTOCOL:               http/protobuf
      OTEL_SERVICE_NAME:                                 py-otel-server
      OTEL_EXPORTER_OTLP_ENDPOINT:                       http://otelcol-collector.opentelemetry.svc.cluster.local:4318
      OTEL_RESOURCE_ATTRIBUTES_POD_NAME:                 py-otel-server-f89fdbc4f-mtsps (v1:metadata.name)
      OTEL_RESOURCE_ATTRIBUTES_NODE_NAME:                 (v1:spec.nodeName)
      OTEL_PROPAGATORS:                                  tracecontext,baggage
      OTEL_RESOURCE_ATTRIBUTES:                          service.name=py-otel-server,service.version=0.1.0,k8s.container.name=py-otel-server,k8s.deployment.name=py-otel-server,k8s.namespace.name=opentelemetry,k8s.node.name=$(OTEL_RESOURCE_ATTRIBUTES_NODE_NAME),k8s.pod.name=$(OTEL_RESOURCE_ATTRIBUTES_POD_NAME),k8s.replicaset.name=py-otel-server-f89fdbc4f,service.instance.id=opentelemetry.$(OTEL_RESOURCE_ATTRIBUTES_POD_NAME).py-otel-server
    Mounts:
      /otel-auto-instrumentation-python from opentelemetry-auto-instrumentation-python (rw)
      /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-x2nmj (ro)
Conditions:
  Type              Status
  Initialized       True
  Ready             True
  ContainersReady   True
  PodScheduled      True
Volumes:
  kube-api-access-x2nmj:
    Type:                    Projected (a volume that contains injected data from multiple sources)
    TokenExpirationSeconds:  3607
    ConfigMapName:           kube-root-ca.crt
    ConfigMapOptional:       <nil>
    DownwardAPI:             true
  opentelemetry-auto-instrumentation-python:
    Type:        EmptyDir (a temporary directory that shares a pod's lifetime)
    Medium:
    SizeLimit:   200Mi
QoS Class:       Burstable
Node-Selectors:  <none>
Tolerations:     node.kubernetes.io/not-ready:NoExecute op=Exists for 300s
                 node.kubernetes.io/unreachable:NoExecute op=Exists for 300s
Events:
  Type    Reason     Age   From               Message
  ----    ------     ----  ----               -------
  Normal  Scheduled  99s   default-scheduler  Successfully assigned opentelemetry/py-otel-server-f89fdbc4f-mtsps to otel-target-allocator-talk-control-plane
  Normal  Pulling    99s   kubelet            Pulling image "ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-python:0.45b0"
  Normal  Pulled     93s   kubelet            Successfully pulled image "ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-python:0.45b0" in 288.756166ms (5.603779501s including waiting)
  Normal  Created    93s   kubelet            Created container opentelemetry-auto-instrumentation-python
  Normal  Started    93s   kubelet            Started container opentelemetry-auto-instrumentation-python
  Normal  Pulled     92s   kubelet            Container image "otel-target-allocator-talk:0.1.0-py-otel-server" already present on machine
  Normal  Created    92s   kubelet            Created container py-otel-server
  Normal  Started    92s   kubelet            Started container py-otel-server

如果 Deployment 部署时 Instrumentation 资源尚不存在，则无法创建 init-container。这意味着，如果 Deployment 资源在您部署 Instrumentation 资源之前部署，自动注入将无法初始化。

通过运行以下命令，检查 opentelemetry-auto-instrumentation init-container 是否已正确启动（或是否已启动）。

kubectl get events -n <namespace>

其中 <namespace> 是您 Pod 部署的命名空间。结果输出应类似于以下示例。

53s         Normal   Created             pod/py-otel-server-7f54bf4cbc-p8wmj    Created container opentelemetry-auto-instrumentation
53s         Normal   Started             pod/py-otel-server-7f54bf4cbc-p8wmj    Started container opentelemetry-auto-instrumentation

如果输出中缺少 opentelemetry-auto-instrumentation 的 Created 或 Started 条目，则可能存在自动注入配置问题。这可能是以下任何原因造成的：

Instrumentation 资源未安装或未正确安装。
Instrumentation 资源在应用程序部署后安装。
自动注入注解存在错误，或者注解位置不正确。请参见下一节。

您还可以检查 events 命令的输出是否存在任何错误，这些错误可能有助于指出问题所在。

检查自动注入注解

请考虑以下自动注入注解代码片段

annotations:
  instrumentation.opentelemetry.io/inject-python: 'true'

如果您的 Deployment 资源部署在名为 application 的命名空间中，并且您有一个名为 my-instrumentation 的 Instrumentation 资源部署在名为 opentelemetry 的命名空间中，那么上述注解将不起作用。

相反，注解应为

annotations:
  instrumentation.opentelemetry.io/inject-python: 'opentelemetry/my-instrumentation'

其中 opentelemetry 是 Instrumentation 资源的命名空间，my-instrumentation 是 Instrumentation 资源的名称。

注解的可能值是:

“true” - 从命名空间注入 OpenTelemetryCollector 资源。
“sidecar-for-my-app” - 当前命名空间中 OpenTelemetryCollector CR 实例的名称。
“my-other-namespace/my-instrumentation” - 另一个命名空间中 OpenTelemetryCollector CR 实例的名称和命名空间。
“false” - 不注入

检查自动注入配置

自动注入注解可能未正确添加。请检查以下几点：

您是为正确的语言进行自动注入吗？例如，您是否尝试通过添加 JavaScript 自动注入注解来自动注入 Python 应用程序？
您是否将自动注入注解放在了正确的位置？在定义 Deployment 资源时，您可以在两个位置添加注解：spec.metadata.annotations 和 spec.template.metadata.annotations。自动注入注解需要添加到 spec.template.metadata.annotations，否则将不起作用。

检查自动注入端点配置

Instrumentation 资源中的 spec.exporter.endpoint 配置允许您定义遥测数据的目的地。如果省略，则默认为 https://:4317，这会导致数据丢失。

如果您正在将遥测数据发送到 Collector，则 spec.exporter.endpoint 的值必须引用您的 Collector Service 的名称。

例如：http://otel-collector.opentelemetry.svc.cluster.local:4318。

其中 otel-collector 是 OTel Collector Kubernetes Service 的名称。

此外，如果 Collector 运行在不同的命名空间中，则必须将 opentelemetry.svc.cluster.local 追加到 Collector 的服务名称中，其中 opentelemetry 是 Collector 所在的命名空间。它可以是您选择的任何命名空间。

最后，请确保您使用的是正确的 Collector 端口。通常，您可以选择 4317 (gRPC) 或 4318 (HTTP)；但是，对于 Python 自动注入，只能使用 4318。

检查配置来源

自动注入目前会覆盖 Java 的 JAVA_TOOL_OPTIONS、Python 的 PYTHONPATH 以及 Node.js 的 NODE_OPTIONS（当在 Docker 镜像中设置或在 ConfigMap 中定义时）。这是一个已知问题，因此，在问题解决之前，应避免使用这些设置这些环境变量的方法。

请参阅 Java、Python 和 Node.js 的相关问题。

Feedback

这个页面有用吗？

谢谢。您的反馈受到赞赏！

请让我们知道我们如何改进此页面。您的反馈受到赞赏！

最后修改于 2025 年 2 月 6 日： [IA] Link normalization step of (#6232) (99a39c5e)