Splunk Observability Cloud に Java アプリケーションをインストルメンテーションする 🔗

Splunk Distribution of OpenTelemetry Java の Java エージェントは、Java クラスにインストルメンテーションを注入することで、Java アプリケーションを自動的にインストルメンテーションできます。開始するには、ガイド付きセットアップを使用するか、手動で指示に従ってください。

注釈

Due to changes in the upstream OpenTelemetry documentation, 「automatic instrumentation」 has been changed to 「zero-code instrumentation」. For more information, see Instrumentation methods for Splunk Observability Cloud.

ガイド付きセットアップを使用してカスタマイズされた指示を生成する 🔗

お使いの環境とアプリケーションの基本的なインストールコマンドをすべて生成するには、Javaガイド付きセットアップを使用します。Javaガイド付きセットアップにアクセスするには、以下の手順に従います：

Splunk Observability Cloud にログインします。
Java ガイド付きセットアップを開きます。オプションで、ガイド付きセットアップに自分で移動することもできます：
1. ナビゲーションメニューで、Data Management を選択します。
2. Go to the Available integrations tab, or select Add Integration in the Deployed integrations tab.
3. インテグレーションフィルターーメニューで、By Product を選択します。
4. APM 製品を選択します。
5. Java タイルを選択し、Javaガイド付きセットアップを開きます。

Splunk Distribution of OpenTelemetry Java を手動でインストールする 🔗

ガイド付きセットアップを使用しない場合は、以下の手順に従って手動で Splunk Distribution of OpenTelemetry Java をインストールしてください：

Javaエージェントのインストールと有効化
Javaエージェントの設定

Javaエージェントのインストールと有効化 🔗

以下の手順に従って、Javaエージェントを使用してアプリケーションを自動的にインストルメンテーションしてください：

条件を満たしているか確認してください。Javaエージェントの互換性と要件を参照してください。

エージェントの最新バージョンのJARファイルをダウンロードします：

curl -L https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent.jar \
-o splunk-otel-javaagent.jar

Invoke-WebRequest -Uri https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent.jar -OutFile splunk-otel-javaagent.jar

環境変数 OTEL_SERVICE_NAME を設定します：

export OTEL_SERVICE_NAME=<yourServiceName>

$env:OTEL_SERVICE_NAME=<yourServiceName>

(オプション) Splunk Distribution of OpenTelemetry Collectorが別のホストで実行されている場合は、エンドポイント URL を設定します：
export OTEL_EXPORTER_OTLP_ENDPOINT=<yourCollectorEndpoint>:<yourCollectorPort>
$env:OTEL_EXPORTER_OTLP_ENDPOINT=<yourCollectorEndpoint>:<yourCollectorPort>

(オプション）デプロイ環境とサービスバージョンを設定します：

export OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'

$env:OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'

-javaagent 引数にJavaエージェントのパスを設定します：
```
java -javaagent:./splunk-otel-javaagent.jar -jar <myapp>.jar
```
注釈

アプリケーションがサポートされているJavaサーバー上で動作する場合は、Splunk Observability Cloud 用 Java アプリケーションサーバーのエージェントパスを定義するを参照してください。

APM にデータが表示されない場合は、Splunk Observability Cloud の Java インストルメンテーションのトラブルシューティングを参照してください。

スパンにカスタム属性を追加する必要がある場合、またはスパンを手動で生成したい場合は、Javaアプリケーションまたはサービスを手動でインストルメンテーションしてください。Splunk Observability Cloud 用に Java アプリケーションの手動でインストルメンテーションするを参照してください。

AlwaysOn Profilingの有効化 🔗

AlwaysOn Profilingを有効にするには、次のシステム・プロパティ引数を使用します。環境変数 SPLUNK_PROFILER_ENABLED を使用することもできます。詳細については、Splunk APMのAlwaysOn Profilingの概要を参照してください。

メモリプロファイリングを有効にするには、AlwaysOn Profilingを有効にした後で、splunk.profiler.memory.enabled システム・プロパティまたは SPLUNK_PROFILER_MEMORY_ENABLED 環境変数を true に設定します。

注釈

OpenJDK バージョン15.0から17.0.8はメモリプロファイリングに対応していません。詳細は JDK バグシステムの https://bugs.openjdk.org/browse/JDK-8309862 を参照してください。

次の例は、システムプロパティを使用してプロファイラーを有効にする方法を示しています：

java -javaagent:./splunk-otel-javaagent.jar \
-Dsplunk.profiler.enabled=true \
-Dsplunk.profiler.memory.enabled=true \
-Dotel.exporter.otlp.endpoint=http(s)://collector:4318 \
-Dsplunk.metrics.endpoint=http(s)://collector:4318
-jar <your_application>.jar

詳細は Splunk APMのAlwaysOn Profilingにデータを取り込むを参照してください。その他の設定については、AlwaysOn Profilingの Java 設定を参照してください。

Metrics collection 🔗

Starting from version 2.5.0, the Java agent collects metrics by default when instrumenting an application or service automatically. To migrate metric collection from version 1.x to 2.x, see Migration guide for OpenTelemetry Java 2.x metrics.

If your metrics endpoint is different than the default value, set the OTEL_EXPORTER_OTLP_METRICS_ENDPOINT environment variable. See Splunk Observability Cloud 用の Java エージェントを設定する for more information.

メモリ・プロファイリングを有効にすると、メトリクス収集が自動的に有効になり、無効にすることはできません。

注釈

Metrics ingest might result in increased data ingest costs. To deactivate metrics collection, set the OTEL_METRICS_EXPORTER environment variable or the -Dotel.metrics.exporter property to none.

Logs collection 🔗

By default, the Java agent injects trace and span metadata automatically into logs. The agent then sends the annotated logs to the OpenTelemetry Collector, which exports them to Splunk Observability Cloud. For more information on trace-log correlation, see Splunk Observability Cloud のログと Java トレースデータを接続する.

注釈

Logs ingest might result in increased data ingest costs. To deactivate logs collection, set the OTEL_LOGS_EXPORTER environment variable or the -Dotel.logs.exporter property to none.

特定のエンドポイントを無視する 🔗

デフォルトでは、Javaエージェントはアプリケーションのすべてのエンドポイントからトレースを収集します。特定のエンドポイントを無視するには、rules サンプラーを使用し、drop ルールを定義します。

次の例では、サンプラーは、終点が healtcheck に一致する SERVER スパンをすべてドロップし、残りのスパンはフォールバックサンプラー parentbased_always_on を使って送信します：

export OTEL_TRACES_SAMPLER=rules
export OTEL_TRACES_SAMPLER_ARG=drop=/healthcheck;fallback=parentbased_always_on

$env:OTEL_TRACES_SAMPLER=rules
$env:OTEL_TRACES_SAMPLER_ARG=drop=/healthcheck;fallback=parentbased_always_on

詳しくは Splunk Observability Cloud 用の Java エージェントを設定するを参照してください。

Javaエージェントの設定 🔗

環境変数を使用するか、システム・プロパティを実行時引数として設定することで、エージェントを設定することができます。両方の方法の詳細については、設定方法を参照してください。

トレース伝播フォーマットの変更、トレースとログの相関、カスタムサンプリングの有効化など、JVMエージェントの高度な設定については、Splunk Observability Cloud 用の Java エージェントを設定するを参照してください。

KubernetesにJavaエージェントをデプロイする 🔗

KubernetesにJavaエージェントをデプロイするには、以下の手順に従います：

アプリケーションイメージのDockerfileを編集し、以下のコマンドを追加します：

# Adds the latest version of the Splunk Java agent
ADD https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent.jar .
# Modifies the entry point
ENTRYPOINT ["java","-javaagent:splunk-otel-javaagent.jar","-jar","./<myapp>.jar"]

環境変数をKubernetesリソースに公開するために、Kubernetes Downward APIを設定します。

次の例は、.spec.template.spec.containers.env セクションにエージェント設定を追加して、環境変数を公開するようにデプロイを更新する方法を示しています：

apiVersion: apps/v1
kind: Deployment
spec:
selector:
   matchLabels:
      app: your-application
template:
   spec:
      containers:
      - name: myapp
         env:
            - name: SPLUNK_OTEL_AGENT
            valueFrom:
               fieldRef:
                  fieldPath: status.hostIP
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
            value: "http://$(SPLUNK_OTEL_AGENT):4318"
            - name: OTEL_SERVICE_NAME
            value: "<serviceName>"
            - name: OTEL_RESOURCE_ATTRIBUTES
            value: "deployment.environment=<environmentName>"

注釈

You can also deploy instrumentation using the Kubernetes Operator. See Automatic discovery and configuration for back-end applications in Kubernetes for more information.

Cloudfoundry に Java エージェントをデプロイする 🔗

Cloudfoundry で Java アプリケーションをインストルメンテーションするには、Splunk OpenTelemetry Java Agent buildpack フレームワークを使用します。このフレームワークは、Splunk Observability Cloud にトレースを送信するために、アプリケーションを自動的にインストルメンテーションします。

手順については https://github.com/cloudfoundry/java-buildpack/blob/main/docs/framework-splunk_otel_java_agent.md を参照してください。

Splunk Observability Cloud に直接データを送信する 🔗

デフォルトでは、エージェントはすべてのテレメトリを Splunk Distribution of OpenTelemetry Collector のローカルインスタンスに送信します。

Splunk Observability Cloud に直接データを送信する必要がある場合は、以下の環境変数を設定します：

export SPLUNK_ACCESS_TOKEN=<access_token>
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.<realm>.signalfx.com/v2/trace/otlp
export OTEL_LOGS_EXPORTER=none

$env:SPLUNK_ACCESS_TOKEN=<access_token>
$env:OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
$env:OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.<realm>.signalfx.com/v2/trace/otlp
$env:OTEL_LOGS_EXPORTER=none

アクセストークンを取得するには、Splunk Observability Cloudを使用したユーザー APIアクセストークンの取得と管理を参照してください。

Splunk レルムを見つけるには、レルムに関する注意事項を参照してください。

取り込みAPIエンドポイントの詳細については、APMのトレースの送信を参照してください。

注意

この手順はスパンとトレースに適用されます。AlwaysOn Profiling データを送信するには、OTel Collector を使用する必要があります。

Set the source host 🔗

エージェントが使用するホストを上書きするには、環境変数 OTEL_RESOURCE_ATTRIBUTES を使用して、ホストの名前を希望するソースに設定します：

$env:OTEL_RESOURCE_ATTRIBUTES=host.name=<host_name>

export OTEL_RESOURCE_ATTRIBUTES=host.name=<host_name>

Lambda 関数のインストルメンテーション 🔗

Splunk OpenTelemetry Lambda Layer を使用して AWS Lambda 関数をインストルメンテーションできます。詳細は AWS Lambda 関数を Splunk Observability Cloud にインストルメンテーションするを参照してください。

Splunk Distribution of OpenTelemetry Java をアップグレードする 🔗

Splunk Distribution of OpenTelemetry Java の新しいリリースは、新しいアップストリームリリースの後、または新しい機能や拡張が利用可能になったときに行われます。

Splunk Distribution of OpenTelemetry Java は、新しいバージョンがリリースされるたびにアップグレードしてください。新しいリリースについては、GitHub リポジトリ https://github.com/signalfx/splunk-otel-java/releases を参照してください。

注釈

バージョン番号の詳細については、GitHub のバージョン管理ドキュメントを参照してください。メジャーバージョンには多くの変更が含まれ、本番環境へのリスクが高まる可能性があります。マイナーバージョンの変更は、一般的なリリースを示し、変更点は控えめです。パッチ・リリースは頻度が低く、特定の修正や拡張が含まれます。

アップグレードのベストプラクティス 🔗

アップグレードで問題が発生するリスクを減らすには、以下のようにしてください：

各リリースのリリースノートと変更履歴を見て、使用環境に影響する変更があるかどうかを判断してください。あなたのソフトウェアが使用しているライブラリ、フレームワーク、ツールについての言及に注意してください。
テストされていないコードを本番環境に投入してはなりません。新しいビルドを本番環境に昇格させる前に、ステージング環境やプリプロダクション環境で動作することを確認してください。スナップショットビルドを本番環境で使わないでください。
カナリア・インスタンスを使います。コードを本番環境にリリースする前に、カナリアをコードで動作させます。少なくとも数時間、できれば数日間、カナリアを動作させます。
あるリリースで変更される依存関係（インストルメンテーションを含む）の数を最小にします。複数の依存関係を同時にアップグレードした後に、問題の根本原因を特定することは困難です。
ビルドパイプラインでバージョン番号を固定します。自動化されたプロセスでは、latest URLを使用しないでください。

This page was last updated on 2024年11月14日.

Related Topics