Docs » Splunk Distribution of the OpenTelemetry Collector の利用開始 » Automatic discovery of apps and services » Automatic discovery for Kubernetes » Zero-code instrumentation for back-end applications in Kubernetes

Zero-code instrumentation for back-end applications in Kubernetes 🔗

The Splunk Distribution of the OpenTelemetry Collector uses automatic discovery with zero-code instrumentation to automatically detect back-end applications running in your Kubernetes environment. By deploying the Collector with zero-code instrumentation, you can instrument applications and send data to Splunk Observability Cloud without editing your application’s code or configuring files.

Zero-code instrumentation for Kubernetes can detect and configure the following applications and language runtimes:

  • Java

  • .NET

  • Node.js

How zero-code instrumentation for Kubernetes works 🔗

Zero-code instrumentation for Kubernetes operates as a Kubernetes DaemonSet that you install with Helm. Using Helm, you can specify which language runtimes you want zero-code instrumentation to find. After installation, Helm deploys a set of Kubernetes pods in your cluster, which includes the Splunk Distribution of OpenTelemetry Collector, the Kubernetes operator, and other supporting resources.

Collector と Kubernetes オペレーターは、アプリケーションへのリクエストをリッスンし、アプリケーションのアクティビティを検出するとテレメトリデータを収集します。その後、Collector はこのデータを Splunk Application Performance Monitoring (APM) に送信します。

はじめに 🔗

To install zero-code instrumentation for Kubernetes, complete the following steps:

  1. Kubernetes OperatorでHelmチャートをデプロイする

  2. すべての OpenTelemetry リソースが正常にデプロイされていることを検証します。

  3. Set annotations to instrument applications

  4. Splunk Observability APM で結果を表示する

要件 🔗

You need the following components to use zero-code instrumentation for back-end Kubernetes applications:

使用言語のランタイムに固有のコンポーネントもインストールされていることを確認してください：

Java 8以上と対応ライブラリ。詳細については、Javaエージェントの互換性と要件 。

Kubernetes OperatorでHelmチャートをデプロイする 🔗

Helmチャートをデプロイするには、values.yaml というファイルを作成します。このファイルでは、Helmチャートとともに OpenTelemetry Collector をインストールするときに有効または無効にする設定を定義できます。

values.yamlに以下のフィールドと値を入力します：

clusterName: <your_cluster_name>

# Your Splunk Observability Cloud realm and access token
splunkObservability:
  realm: <splunk_realm>
  accessToken: <splunk_access_token>

# Activates the OpenTelemetry Kubernetes Operator
operator:
  enabled: true

You might need to populate the file with additional values depending on your environment. See 証明書を追加する and デプロイメント環境の設定 for more information.

証明書を追加する 🔗

Operator が動作するには、特定の TLS 証明書が必要です。次のコマンドを使用して、認証マネージャーが利用可能かどうかを確認します：

# Check if cert-manager is already installed, don't deploy a second cert-manager.
kubectl get pods -l app=cert-manager --all-namespaces

クラスターで認証マネージャーが利用できない場合は、certmanager.enabled=true を values.yaml ファイルに追加する必要があります。例えば

clusterName: my-cluster

splunkObservability:
  realm: <splunk_realm>
  accessToken: <splunk_access_token>

certmanager:
  enabled: true
operator:
  enabled: true

デプロイメント環境の設定 🔗

トレーステレメトリデータを適切に取り込むには、エクスポートされたトレースに deployment.environment 属性が設定されている必要があります。次の表は、この属性を設定するさまざまな方法を示しています：

メソッド

スコープ

実装

values.yamlファイル environment 設定を介して

コレクターを介してエクスポートされるすべてのテレメトリデータ (メトリクス、ログ、トレース) に属性を適用します。

チャートは、コレクターによって処理されるすべてのテレメトリデータに deployment.environment=prd を追加する属性プロセッサーを設定します。

Through the values.yaml file and instrumentation.env or instrumentation.{instrumentation_library}.env configuration

すべての自動インストルメンテーションされたアプリケーションを一括して、または自動インストルメンテーション言語ごとに deployment.environment を設定できます。

OTEL_RESOURCE_ATTRIBUTES 環境変数を追加し、その値を deployment.environment=prd に設定します。

Kubernetesアプリケーションのデプロイメント、デーモンセット、またはポッドの仕様を通して

個々のデプロイメント、デーモンセット、またはポッドのレベルで deployment.environment を設定できます。

環境変数 OTEL_RESOURCE_ATTRIBUTES を使用し、値 deployment.environment=prd を代入します。

以下の例では、それぞれのメソッドを使って属性を設定する方法を示しています：

values.yaml ファイルで environment オプションを設定します。これにより、自動的にインストルメンテーションされたポッドからのデータを含め、Collectorが受信するすべてのテレメトリデータに deployment.environment 属性が追加されます。

  clusterName: my-cluster

  splunkObservability:
    realm: <splunk_realm>
    accessToken: <splunk_access_token>

  environment: prd

  certmanager:
    enabled: true
  operator:
    enabled: true

Helm チャートのデプロイ 🔗

values.yamlを設定したら、次のコマンドを使用してHelmチャートをデプロイします：

helm install splunk-otel-collector -f ./values.yaml splunk-otel-collector-chart/splunk-otel-collector

Collector インスタンスの名前と、Collector をインストールする名前空間を変更できます。

たとえば、Collector インスタンスの名前を otel-collector に変更し、o11y 名前空間にインストールするには、次のコマンドを使用します：

helm install otel-collector -f ./values.yaml splunk-otel-collector-chart/splunk-otel-collector --namespace o11y

すべての OpenTelemetry リソースが正常にデプロイされていることを検証します。 🔗

Resources include the Collector, the Operator, webhook, and instrumentation. Run the following commands to verify the resources are deployed correctly.

The pods running in the collector namespace must include the following:

kubectl get pods
# NAME                                                          READY
# NAMESPACE     NAME                                                            READY   STATUS
# monitoring    splunk-otel-collector-agent-lfthw                               2/2     Running
# monitoring    splunk-otel-collector-cert-manager-6b9fb8b95f-2lmv4             1/1     Running
# monitoring    splunk-otel-collector-cert-manager-cainjector-6d65b6d4c-khcrc   1/1     Running
# monitoring    splunk-otel-collector-cert-manager-webhook-87b7ffffc-xp4sr      1/1     Running
# monitoring    splunk-otel-collector-k8s-cluster-receiver-856f5fbcf9-pqkwg     1/1     Running
# monitoring    splunk-otel-collector-opentelemetry-operator-56c4ddb4db-zcjgh   2/2     Running

The webhooks in the collector namespace must include the following:

kubectl get mutatingwebhookconfiguration.admissionregistration.k8s.io
# NAME                                      WEBHOOKS   AGE
# splunk-otel-collector-cert-manager-webhook              1          14m
# splunk-otel-collector-opentelemetry-operator-mutation   3          14m

The instrumentation in the collector namespace must include the following:

kubectl get otelinst
# NAME                          AGE   ENDPOINT
# splunk-instrumentation        3m   http://$(SPLUNK_OTEL_AGENT):4317

Set annotations to instrument applications 🔗

If the related Kubernetes object (deployment, daemonset, or pod) is not deployed, add the instrumentation.opentelemetry.io/inject-java annotation to the application object YAML.

設定するアノテーションは、使用している言語ランタイムによって異なります。同じ Kubernetes オブジェクトに複数のアノテーションを設定できます。以下の利用可能なアノテーションを参照してください：

Add the instrumentation.opentelemetry.io/inject-java annotation to the application object YAML.

たとえば、次のようなデプロイメントYAMLがあるとします：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-java-app
  namespace: monitoring
spec:
  template:
    spec:
    containers:
    - name: my-java-app
        image: my-java-app:latest

Activate zero-code instrumentation by adding instrumentation.opentelemetry.io/inject-java: "true" to the spec:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-java-app
  namespace: monitoring
spec:
  template:
    metadata:
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"
    spec:
      containers:
      - name: my-java-app
        image: my-java-app:latest

異なる名前空間でのアノテーションの適用 🔗

現在の名前空間が monitoring でない場合は、アノテーションを変更して、OpenTelemetry Collector をインストールした名前空間を指定します。

For example, if the current namespace is <my-namespace> and you installed the Collector in monitoring, set the annotation to "instrumentation.opentelemetry.io/inject-<application_language>": "monitoring/splunk-otel-collector":

kubectl patch deployment <my-deployment> -n <my-namespace> -p '{"spec":{"template":{"metadata":{"annotations":{"instrumentation.opentelemetry.io/inject-<application_language>":"monitoring/splunk-otel-collector"}}}}}'

<application_language> を検出するアプリケーションの言語に置き換えます。

Instrument applications in multi-container pods 🔗

By default, zero-code instrumentation instruments the first container in the Kubernetes pod spec. You can specify multiple containers to instrument by adding an annotation.

The following example instruments Java applications running in the myapp and myapp2 containers:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment-with-multiple-containers
spec:
  selector:
    matchLabels:
      app: my-pod-with-multiple-containers
  replicas: 1
  template:
    metadata:
      labels:
        app: my-pod-with-multiple-containers
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"
        instrumentation.opentelemetry.io/container-names: "myapp,myapp2"

特定の言語で複数のコンテナをインストルメンテーションすることもできます。そのためには、instrumentation.opentelemetry.io/<language>-container-names アノテーションを使用して、インストルメンテーションする言語とコンテナを指定します。以下の例では、Java アプリケーションを myapp と myapp2 に、Node.js アプリケーションを myapp3 にインストルメンテーションしています：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment-with-multi-containers-multi-instrumentations
spec:
  selector:
    matchLabels:
      app: my-pod-with-multi-containers-multi-instrumentations
  replicas: 1
  template:
    metadata:
      labels:
        app: my-pod-with-multi-containers-multi-instrumentations
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"
        instrumentation.opentelemetry.io/java-container-names: "myapp,myapp2"
        instrumentation.opentelemetry.io/inject-nodejs: "true"
        instrumentation.opentelemetry.io/python-container-names: "myapp3"

Deactivate zero-code instrumentation 🔗

To deactivate zero-code instrumentation remove the annotation using the following command:

kubectl patch deployment <my-deployment> -n <my-namespace> --type=json -p='[{"op": "remove", "path": "/spec/template/metadata/annotations/instrumentation.opentelemetry.io~1inject-<application_language>"}]'

Replace <application_language> with the language of the application for which you want to deactivate instrumentation.

インストルメンテーションの検証 🔗

インストルメンテーションが成功したことを確認するには、個々のポッドで次のコマンドを実行します：

kubectl describe pod <application_pod_name> -n <namespace>

インストルメンテーションされたポッドには、opentelemetry-auto-instrumentation という名前の initContainer が含まれ、ターゲットアプリケーションコンテナには、以下のデモ出力にあるような OTEL_* 環境変数がいくつかあるはずです：

# Name:             opentelemetry-demo-frontend-57488c7b9c-4qbfb
# Namespace:        otel-demo
# Annotations:      instrumentation.opentelemetry.io/inject-java: true
# Status:           Running
# Init Containers:
#   opentelemetry-auto-instrumentation:
#     Command:
#       cp
#       -a
#       /autoinstrumentation/.
#       /otel-auto-instrumentation/
#     State:          Terminated
#       Reason:       Completed
#       Exit Code:    0
# Containers:
#   frontend:
#     State:          Running
#     Ready:          True
#     Environment:
#       FRONTEND_PORT:                              8080
#       FRONTEND_ADDR:                              :8080
#       AD_SERVICE_ADDR:                            opentelemetry-demo-adservice:8080
#       CART_SERVICE_ADDR:                          opentelemetry-demo-cartservice:8080
#       CHECKOUT_SERVICE_ADDR:                      opentelemetry-demo-checkoutservice:8080
#       CURRENCY_SERVICE_ADDR:                      opentelemetry-demo-currencyservice:8080
#       PRODUCT_CATALOG_SERVICE_ADDR:               opentelemetry-demo-productcatalogservice:8080
#       RECOMMENDATION_SERVICE_ADDR:                opentelemetry-demo-recommendationservice:8080
#       SHIPPING_SERVICE_ADDR:                      opentelemetry-demo-shippingservice:8080
#       WEB_OTEL_SERVICE_NAME:                      frontend-web
#       PUBLIC_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:  http://localhost:8080/otlp-http/v1/traces
#       NODE_OPTIONS:                                --require /otel-auto-instrumentation/autoinstrumentation.java
#       SPLUNK_OTEL_AGENT:                           (v1:status.hostIP)
#       OTEL_SERVICE_NAME:                          opentelemetry-demo-frontend
#       OTEL_EXPORTER_OTLP_ENDPOINT:                http://$(SPLUNK_OTEL_AGENT):4317
#       OTEL_RESOURCE_ATTRIBUTES_POD_NAME:          opentelemetry-demo-frontend-57488c7b9c-4qbfb (v1:metadata.name)
#       OTEL_RESOURCE_ATTRIBUTES_NODE_NAME:          (v1:spec.nodeName)
#       OTEL_PROPAGATORS:                           tracecontext,baggage,b3
#       OTEL_RESOURCE_ATTRIBUTES:                   splunk.zc.method=autoinstrumentation-java:0.41.1,k8s.container.name=frontend,k8s.deployment.name=opentelemetry-demo-frontend,k8s.namespace.name=otel-demo,k8s.node.name=$(OTEL_RESOURCE_ATTRIBUTES_NODE_NAME),k8s.pod.name=$(OTEL_RESOURCE_ATTRIBUTES_POD_NAME),k8s.replicaset.name=opentelemetry-demo-frontend-57488c7b9c,service.version=1.5.0-frontend
#     Mounts:
#       /otel-auto-instrumentation from opentelemetry-auto-instrumentation (rw)
# Volumes:
#   opentelemetry-auto-instrumentation:
#     Type:        EmptyDir (a temporary directory that shares a pod's lifetime)

Splunk Observability APM で結果を表示する 🔗

Operatorに作業を行わせます。OperatorはKubernetes APIリクエストをインターセプトして変更し、アノテートされたPodを作成および更新し、内部Podアプリケーションコンテナがインストルメンテーションされ、トレースとメトリクスデータが APMダッシュボード に入力されます。

(オプション）インストルメンテーションの設定 🔗

You can configure the Splunk Distribution of OpenTelemetry Collector to suit your instrumentation needs. In most cases, modifying the basic configuration is enough to get started.

You can add advanced configuration like activating custom sampling and including custom data in the reported spans with environment variables and system properties. To do so, use the values.yaml file and instrumentation.sampler configuration. For more information, see the documentation in GitHub and example in GitHub .

You can also use the methods shown in デプロイメント環境の設定 to configure your instrumentation with the OTEL_RESOURCE_ATTRIBUTES environment variable and other environment variables. For example, if you want every span to include the key-value pair build.id=feb2023_v2, set the OTEL_RESOURCE_ATTRIBUTES environment variable:

kubectl set env deployment/<my-deployment> OTEL_RESOURCE_ATTRIBUTES=build.id=feb2023_v2

See Advanced customization for automatic discovery and instrumtenation in Kubernetes for more information.

トラブルシューティング 🔗

If you’re having trouble setting up automatic discovery, see the following troubleshooting guidelines.

失敗のログをチェックする 🔗

ログを調査し、オペレーターと証明書マネージャーが機能していることを確認します。

アプリケーション

kubectlコマンド

オペレーター

kubectl logs -l app.kubernetes.io/name=operator

証明書マネージャー

  • kubectl logs -l app=certmanager

  • kubectl logs -l app=cainjector

  • kubectl logs -l app=webhook

証明書マネージャーの問題を解決する 🔗

オペレーターがハングする場合は、証明書マネージャーに問題がある可能性があります。

  • cert-managerポッドのログを確認します。

  • cert-managerポッドを再起動します。

  • クラスターにcert-managerのインスタンスが1つしかないことを確認してください。これには certmanager、certmanager-cainjector、および certmanager-webhook が含まれます。

詳細については、公式の証明書マネージャートラブルシューティングガイドを参照してください： https://cert-manager.io/docs/troubleshooting/。

証明書を検証する 🔗

証明書が使用可能であることを確認します。以下のコマンドを使用して、証明書を検索します：

kubectl get certificates
# NAME                                          READY   SECRET                                                           AGE
# splunk-otel-collector-operator-serving-cert   True    splunk-otel-collector-operator-controller-manager-service-cert   5m

To troubleshoot common errors that occur when instrumenting applications, see the following guides:

さらに詳しく 🔗

このページは 2024年12月09日 に最終更新されました。