Docs » Splunk Distribution of the OpenTelemetry Collector の利用開始 » Discover telemetry sources automatically » Automatic discovery and configuration for Kubernetes » Automatic discovery and configuration for back-end applications in Kubernetes

Automatic discovery and configuration for back-end applications in Kubernetes 🔗

When using automatic discovery and configuration, the Splunk Distribution of OpenTelemetry Collector automatically detects back-end applications running in your Kubernetes environment.

By deploying the Collector with automatic discovery, you can instrument applications and send data to Splunk Observability Cloud without editing your application’s code or configuring files.

Automatic discovery for Kubernetes can detect and configure the following applications and language runtimes:

  • Java

  • .NET

  • Node.js

How automatic discovery for Kubernetes works 🔗

Automatic discovery for Kubernetes operates as a Kubernetes DaemonSet that you install with Helm. Using Helm, you can specify which language runtimes you want automatic discovery 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.

The Collector and Kubernetes operator listen for requests to your application and gather telemetry data upon detecting activity in your application. The Collector then sends this data to Splunk Application Performance Monitoring (APM).

はじめに 🔗

To install automatic discovery 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 automatic discovery for back-end Kubernetes applications:

Make sure you’ve also installed the components specific to your language runtime:

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 を追加する属性プロセッサーを設定します。

values.yamlファイルと operator.instrumentation.spec.env または operator.instrumentation.spec.{instrumentation_library}.env 設定を介して

すべての自動インストルメンテーションされたアプリケーションを一括して、または自動インストルメンテーション言語ごとに 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.

The annotation you set depends on the language runtime you’re using. You can set multiple annotations in the same Kubernetes object. See the following available annotations:

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 automatic discovery 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"}}}}}'

Replace <application_language> with the language of the application you want to discover.

Instrument applications in multi-container pods 🔗

By default, automatic discovery 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"

You can also instrument multiple containers with specific languages. To do so, specify which languages and containers to instrument by using the instrumentation.opentelemetry.io/<language>-container-names annotation. The following example instruments Java applications in myapp and myapp2, and Node.js applications in 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 automatic discovery 🔗

To deactivate automatic discovery, remove the annotation. The following command removes the annotation for automatic discovery, deactivating it:

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 discovery.

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

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

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 operator.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 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 troubleshooting guides:

さらに詳しく 🔗

This page was last updated on 2024年06月25日.