Kubernetes でのバックエンドアプリケーションのゼロコードインストルメンテーション 🔗
Splunk Distribution of the OpenTelemetry Collector では、ゼロコードインストルメンテーションによるオートディスカバリーを使用して、Kubernetes 環境で実行されているバックエンドアプリケーションを自動的に検出します。ゼロコードインストルメンテーションで Collector をデプロイすることで、アプリケーションのコードを編集したり、ファイルを設定したりすることなく、アプリケーションをインストルメンテーションし、Splunk Observability Cloud にデータを送信することができます。
Kubernetes のゼロコードインストルメンテーションは、以下のアプリケーションと言語ランタイムを検出し、設定することができます:
Java
.NET
Node.js
Kubernetesのゼロコードインストルメンテーションの仕組み 🔗
Kubernetes のゼロコードインストルメンテーションは、Helm でインストールする Kubernetes DaemonSet として動作します。Helm を使用すると、ゼロコードインストルメンテーションさせる言語ランタイムを指定できます。インストール後、Helm はクラスターに Kubernetes ポッドのセットを展開し、これには Splunk Distribution of OpenTelemetry Collector、Kubernetes Operator、その他のサポートリソースが含まれます。
Collector と Kubernetes オペレーターは、アプリケーションへのリクエストをリッスンし、アプリケーションのアクティビティを検出するとテレメトリデータを収集します。その後、Collector はこのデータを Splunk Application Performance Monitoring (APM) に送信します。
はじめに 🔗
Kubernetes のゼロコードインストルメンテーションをインストールするには、以下の手順を実行します:
要件 🔗
バックエンドの Kubernetes アプリケーションにゼロコードインストルメンテーションを使用するには、以下のコンポーネントが必要です:
Helm バージョン 3 以上。
Kubernetesクラスターへの管理者アクセスおよびKubernetesの設定に精通していること。
Splunk Observability Cloud レルムと、インジェストスコープを持つアクセストークン。詳細については、Splunk Observability Cloudを使用した組織のアクセストークンの作成および管理 を参照してください。
使用言語のランタイムに固有のコンポーネントもインストールされていることを確認してください:
Java 8以上と対応ライブラリ。詳細については、Javaエージェントの互換性と要件 。
.NET version 6.0 or higher and supported .NET application libraries.
x86またはAMD64(x86-64)アーキテクチャー。ARMアーキテクチャーはサポートされていません。
Node.jsのバージョン14以上とサポートされているライブラリ。詳しくは Splunk OTel JS の互換性と要件 を参照してください。
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
# Installs the Custom Resource Definitions (CRDs) required by the operator
# Must be set unless CRDs are pre-installed manually
operatorcrds:
install: true
You might need to populate the file with additional values depending on your environment. See Add OpenTelemetry CRDs and デプロイメント環境の設定 for more information.
Add OpenTelemetry CRDs 🔗
The Operator for Kubernetes requires you to install OpenTelemetry Custom Resource Definitions (CRDs). To do this, add operatorcrds.install=true
to your values.yaml file:
clusterName: my-cluster
splunkObservability:
realm: <splunk_realm>
accessToken: <splunk_access_token>
operator:
enabled: true
operatorcrds:
install: true
デプロイメント環境の設定 🔗
トレーステレメトリデータを適切に取り込むには、エクスポートされたトレースに deployment.environment
属性が設定されている必要があります。次の表は、この属性を設定するさまざまな方法を示しています:
メソッド |
スコープ |
実装 |
---|---|---|
values.yamlファイル |
コレクターを介してエクスポートされるすべてのテレメトリデータ (メトリクス、ログ、トレース) に属性を適用します。 |
チャートは、コレクターによって処理されるすべてのテレメトリデータに |
values.yamlファイルと |
すべての自動インストルメンテーションされたアプリケーションを一括して、または自動インストルメンテーション言語ごとに |
|
Through your Kubernetes application deployment, DaemonSet, or pod specification |
Allows you to set |
環境変数 |
以下の例では、それぞれのメソッドを使って属性を設定する方法を示しています:
values.yaml ファイルで environment
オプションを設定します。これにより、自動的にインストルメンテーションされたポッドからのデータを含め、Collectorが受信するすべてのテレメトリデータに deployment.environment
属性が追加されます。
clusterName: my-cluster
splunkObservability:
realm: <splunk_realm>
accessToken: <splunk_access_token>
environment: prd
certmanager:
enabled: true
operatorcrds:
install: true
operator:
enabled: true
次のコード例に示すように、values.yaml instrumentation spec に環境変数を追加します。このメソッドは、自動インストルメンテーションされたポッドからのすべてのテレメトリデータに deployment.environment
属性を追加します。
operatorcrds:
install: true
operator:
enabled: true
instrumentation:
env:
- name: OTEL_RESOURCE_ATTRIBUTES
value: "deployment.environment=prd"
java:
env:
- name: OTEL_RESOURCE_ATTRIBUTES
value: "deployment.environment=prd-canary-java"
アプリケーションのデプロイメント YAML ファイルを更新します。このメソッドは、指定した環境変数を含むポッドからのすべてのテレメトリデータに deployment.environment
属性を追加します。
apiVersion: apps/v1 kind: Deployment metadata: name: my-java-app spec: template: spec: containers: - name: my-java-app image: my-java-app:latest env: - name: OTEL_RESOURCE_ATTRIBUTES value: "deployment.environment=prd"
kubectl set env
を使って環境変数 OTEL_RESOURCE_ATTRIBUTES
を更新します。例:
kubectl set env deployment/<my-deployment> OTEL_RESOURCE_ATTRIBUTES=environment=prd
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 リソースが正常にデプロイされていることを検証します。 🔗
リソースには、Collector、Operator、Webhook、およびインストルメンテーションが含まれます。以下のコマンドを実行して、リソースが正しく配置されていることを確認します。
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-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-opentelemetry-operator-mutation 3 14m
コレクター名前空間のインストルメンテーションには、以下を含める必要があります:
kubectl get otelinst
# NAME AGE ENDPOINT
# splunk-instrumentation 3m http://$(SPLUNK_OTEL_AGENT):4317
インストルメンテーションアプリケーションに注釈を設定する 🔗
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 オブジェクトに複数のアノテーションを設定できます。以下の利用可能なアノテーションを参照してください:
アプリケーションオブジェクトのYAMLに instrumentation.opentelemetry.io/inject-java
アノテーションを追加します。
たとえば、次のようなデプロイメント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
instrumentation.opentelemetry.io/inject-java: "true"
に 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
アプリケーションオブジェクトのYAMLに instrumentation.opentelemetry.io/inject-dotnet
アノテーションを追加します。
使用環境とランタイム識別子(RID)に応じて、別のアノテーションを追加する必要があります。RIDを見つける方法については、.NETアプリケーションのランタイム識別子を見つける を参照してください。
詳細は以下の表を参照:
RID |
アノテーション |
備考 |
---|---|---|
|
|
これはデフォルト値であり、省略することもできます。 |
|
|
このアノテーションは、 |
linux-x64
ランタイム環境に次のようなデプロイメントYAMLがあるとします:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-dotnet-app
namespace: monitoring
spec:
template:
spec:
containers:
- name: my-dotnet-app
image: my-dotnet-app:latest
instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-x64"
に instrumentation.opentelemetry.io/inject-dotnet: "monitoring/splunk-otel-collector"
と spec
を追加してゼロコードインストルメンテーションを有効化します:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-dotnet-app
namespace: monitoring
spec:
template:
metadata:
annotations:
instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-x64"
instrumentation.opentelemetry.io/inject-dotnet: "monitoring/splunk-otel-collector"
spec:
containers:
- name: my-dotnet-app
image: my-dotnet-app:latest
linux-musl-x64
ランタイム環境に次のようなデプロイメントYAMLがあるとします:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-dotnet-app
namespace: monitoring
spec:
template:
spec:
containers:
- name: my-dotnet-app
image: my-dotnet-app:latest
instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-musl-x64"
に instrumentation.opentelemetry.io/inject-dotnet: "monitoring/splunk-otel-collector"
と spec
を追加してゼロコードインストルメンテーションを有効化します:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-dotnet-app
namespace: monitoring
spec:
template:
metadata:
annotations:
instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-musl-x64"
instrumentation.opentelemetry.io/inject-dotnet: "monitoring/splunk-otel-collector"
spec:
containers:
- name: my-dotnet-app
image: my-dotnet-app:latest
アプリケーションオブジェクトのYAMLに instrumentation.opentelemetry.io/inject-nodejs
アノテーションを追加します。
たとえば、次のようなデプロイメントYAMLがあるとします:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nodejs-app
namespace: monitoring
spec:
template:
spec:
containers:
- name: my-nodejs-app
image: my-nodejs-app:latest
instrumentation.opentelemetry.io/inject-nodejs: "true"
に spec
を追加してゼロコードインストルメンテーションを有効化します:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nodejs-app
namespace: monitoring
spec:
template:
metadata:
annotations:
instrumentation.opentelemetry.io/inject-nodejs: "true"
spec:
containers:
- name: my-nodejs-app
image: my-nodejs-app:latest
異なる名前空間でのアノテーションの適用 🔗
現在の名前空間が monitoring
でない場合は、アノテーションを変更して、OpenTelemetry Collector をインストールした名前空間を指定します。
たとえば、現在の名前空間が <my-namespace>
で、Collectorを monitoring
にインストールした場合は、アノテーションを "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>
を検出するアプリケーションの言語に置き換えます。
マルチコンテナポッドでのインストルメンテーションアプリケーション 🔗
デフォルトでは、ゼロコードインストルメンテーションはKubernetes ポッド仕様の最初のコンテナをインストルメンテーションします。アノテーションを追加することで、インストルメンテーションする複数のコンテナを指定できます。
以下の例では、myapp
および myapp2
コンテナで動作するJavaアプリケーションをインストルメンテーションします:
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"
ゼロコードインストルメンテーションを無効にする 🔗
ゼロコードインストルメンテーションを無効にするには、以下のコマンドを使用してアノテーションを削除します:
kubectl patch deployment <my-deployment> -n <my-namespace> --type=json -p='[{"op": "remove", "path": "/spec/template/metadata/annotations/instrumentation.opentelemetry.io~1inject-<application_language>"}]'
<application_language>
をインストルメンテーションを無効にするアプリケーションの言語に置き換えます。
インストルメンテーションの検証 🔗
インストルメンテーションが成功したことを確認するには、個々のポッドで次のコマンドを実行します:
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ダッシュボード に入力されます。
(オプション)インストルメンテーションの設定 🔗
Splunk Distribution of OpenTelemetry Collectorは、インストルメンテーションのニーズに合わせて設定することができます。ほとんどの場合、基本設定を変更するだけで十分です。
環境変数やシステムプロパティを使って、カスタムサンプリングの有効化や、レポートされるスパンにカスタムデータを含めるといった高度な設定を追加することができます。そのためには、values.yamlファイルと instrumentation.sampler
設定を使用します。詳細については、GitHub の ドキュメントと、GitHub のの例 を参照してください。
また、デプロイメント環境の設定 環境変数やその他の環境変数を使用してインストルメンテーションを設定するには、OTEL_RESOURCE_ATTRIBUTES
で示した方法を使用できます。例えば、すべてのスパンにキーと値のペア build.id=feb2023_v2
を含めたい場合、OTEL_RESOURCE_ATTRIBUTES
環境変数 を設定します:
kubectl set env deployment/<my-deployment> OTEL_RESOURCE_ATTRIBUTES=build.id=feb2023_v2
詳細は Advanced customization for automatic discovery and instrumentation in Kubernetes を参照してください。
トラブルシューティング 🔗
自動ディスカバリーの設定に問題がある場合は、以下のトラブルシューティングガイドラインを参照してください。
失敗のログをチェックする 🔗
ログを調査し、オペレーターと証明書マネージャーが機能していることを確認します。
アプリケーション |
kubectlコマンド |
---|---|
オペレーター |
|
証明書マネージャー |
|
証明書を検証する 🔗
証明書が使用可能であることを確認します。以下のコマンドを使用して、証明書を検索します:
kubectl get certificates
# NAME READY SECRET AGE
# splunk-otel-collector-operator-serving-cert True splunk-otel-collector-operator-controller-manager-service-cert 5m
アプリケーションのインストルメンテーション時に発生する一般的なエラーのトラブルシューティングについては、以下ガイドを参照してください:
さらに詳しく 🔗
Splunk Observability Cloud でのゼロコードインストルメンテーションの仕組みについては、GitHub のより詳細なドキュメント を参照してください。
詳しくは Kubernetesドキュメント のoperatorパターン を参照してください。