このドキュメントでは、OpenTelemetry のゼロコード計測を使用して、Google Kubernetes Engine（GKE）で実行されている Java アプリケーションを自動的に計測する方法について説明します。ゼロコード インストルメンテーションを使用すると、最小限の手作業で Java ワークロードの包括的なオブザーバビリティを実現できます。
このチュートリアルでは、GKE への Java アプリケーションのデプロイ、OpenTelemetry を使用したアプリケーションの自動計測、Google Cloud Observability を使用した生成されたテレメトリー シグナルの可視化を行う手順について詳しく説明します。
このチュートリアルでは、GKE で実行されている Java ワークロードの自動計測について説明しますが、これらの手順は他のサポートされている言語にも適用できます。
ゼロコード インストルメンテーションを使用する理由
OpenTelemetry のゼロコード計測（自動計測とも呼ばれます）は、アプリケーション デベロッパーが追加のコードを記述したり、既存のコードを変更したりすることなく、構成可能なオブザーバビリティをコードに追加できる強力なツールです。ゼロコード インストルメンテーションは、アクティブにデプロイされたアプリケーション ライブラリにインストルメンテーションを自動的に追加することで機能します。これにより、ゴールデン シグナルを発行して、アプリケーションのパフォーマンスに関する信頼性の高い分析情報を取得できます。このため、ゼロコード インストルメンテーションは、アプリケーションのオブザーバビリティの旅の優れた出発点となります。
Java のゼロコード インストルメンテーションは、言語のエコシステムで広く使用されている一般的なライブラリをインストルメント化することで、指標とトレース スパンを出力します。Java の場合、指標には次のものが含まれます。
- Java Platform によって出力される JVM ランタイム指標
- Java の Http クライアント ライブラリや Google の Http クライアント ライブラリなどのライブラリから出力される HttpClient 指標と HttpClient スパン。
- JDBC や Lettuce などのライブラリから出力されるデータベース クライアント指標とデータベース クライアント スパン。
出力される指標のセットは、計測対象のアプリケーションと、アプリケーションで使用されるライブラリによって異なります。Java ゼロコード インストルメンテーション エージェントで計測できるライブラリとフレームワークの完全なリストについては、サポートされているライブラリとフレームワークをご覧ください。
自動計測を使用すると、次のようなことができます。
- コードを変更せずにゴールデン シグナルのモニタリングを取得します。
- すべての RPC 呼び出しにまたがる個々のユーザー トレースに高い p99.9 レイテンシを関連付けます。
- さまざまな一般的なライブラリやフレームワークから、指標、ログ、トレースにわたって一貫したテレメトリーを取得します。
ゼロコード インストルメンテーションの詳細については、OpenTelemetry のゼロコードをご覧ください。
概要
GKE で実行されている Java ワークロードにオブザーバビリティを追加するには、次のコンポーネントをデプロイする必要があります。
- アプリケーションからテレメトリーを生成する OpenTelemetry ゼロコード インストルメンテーション。
- OpenTelemetry Collector。アプリケーションによって生成されたテレメトリーを収集し、重要なメタデータとコンテキストで拡充して、使用するために Google Cloud に転送します。
このチュートリアルでは、指標とトレースを Google Cloudに出力する計測済みの Java アプリケーションを GKE にデプロイします。これらのテレメトリー シグナルは、Metrics Explorer、Logs Explorer、Trace Explorer などの Google Cloudのオブザーバビリティ サービスを使用して表示できます。生成されたテレメトリーを表示して使用する方法については、テレメトリーを表示するをご覧ください。
このチュートリアルでは、次の課金対象サービスを使用してシグナルを書き込みます。
- Cloud Monitoring の Prometheus 向けマネージド サービス
- Cloud Logging
- Cloud Trace
- Google Kubernetes Engine
- Cloud Build
- Artifact Registry
料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。
始める前に
このセクションでは、アプリをデプロイして計測し、実行するための環境を設定する方法について説明します。
Google Cloud プロジェクトを選択または作成する
このチュートリアルで使用する Google Cloud プロジェクトを選択します。 Google Cloud プロジェクトが存在しない場合は作成します。
- Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、 アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
コマンドライン ツールをインストールする
このドキュメントでは、次のコマンドライン ツールを使用します。
gcloudkubectl
gcloud ツールと kubectl ツールは Google Cloud CLI に含まれています。インストールの詳細については、Google Cloud CLI コンポーネントの管理をご覧ください。インストールされている gcloud CLI コンポーネントを確認するには、次のコマンドを実行します。
gcloud components list
環境変数を設定する
頻繁に使用する値の入力を減らし、入力エラーを防ぎ、このドキュメントのコマンドを実行可能にするには、次の環境変数を設定します。
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export CLUSTER_NAME=CLUSTER_NAME
export CLUSTER_REGION=us-east1
export ARTIFACT_REGISTRY=opentelemetry-autoinstrument-registry
export REGISTRY_LOCATION=us-east4
コマンドを実行する前に、次の変数を置き換えるか、デフォルトを使用します。
- PROJECT_ID: プロジェクトの ID。
- CLUSTER_NAME: クラスタの名前。これは、新規または既存のクラスタを指す場合があります。
- us-east1: クラスタのリージョン。既存のクラスタを使用している場合は、そのクラスタのリージョンを使用します。
- opentelemetry-autoinstrument-registry: Artifact Registry リポジトリの名前。これは、新しいリポジトリまたは既存のリポジトリを指す場合があります。
- us-east4: Artifact Registry リポジトリのリージョン。既存のリポジトリを使用している場合は、そのリポジトリのリージョンを使用します。
このドキュメントのコマンドを実行するときにエラーが発生した場合は、これらの変数がターミナル環境で正しく設定されていることを確認してください。
API を有効にする
このドキュメントのサービスを使用するには、 Google Cloud プロジェクトで次の API を有効にする必要があります。
- Artifact Registry API:
artifactregistry.googleapis.com - Cloud Build API:
cloudbuild.googleapis.com - Google Kubernetes Engine:
container.googleapis.com - Identity and Access Management API:
iam.googleapis.com - Cloud Logging API:
logging.googleapis.com - Cloud Monitoring API:
monitoring.googleapis.com - Telemetry API:
telemetry.googleapis.com
これらの API は、Telemetry API を除き、 Google Cloud プロジェクトで有効になっている可能性があります。次のコマンドを実行して、有効になっている API を一覧表示します。
gcloud services list
有効になっていない API を有効にします。テレメトリー API（telemetry.googleapis.com）に特に注意してください。この API を初めて使用する可能性があります。
まだ有効になっていない API を有効にするには、対応する API のコマンドを実行します。
gcloud services enable artifactregistry.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable container.googleapis.com
gcloud services enable iam.googleapis.com
gcloud services enable logging.googleapis.com
gcloud services enable monitoring.googleapis.com
gcloud services enable telemetry.googleapis.com
クラスタを設定する
サンプル アプリケーションとコレクタ用に GKE クラスタを設定します。
次のコマンドを実行して Google Cloud にログインします。
gcloud auth login gcloud config set project PROJECT_IDGKE クラスタがまだない場合は、次のコマンドを実行して Autopilot クラスタを作成します。
gcloud container clusters create-auto --region us-east1 CLUSTER_NAME --project PROJECT_IDクラスタを操作するには、次のコマンドを実行してローカルの
kubectlユーティリティを接続します。gcloud container clusters get-credentials CLUSTER_NAME --region us-east1 --project PROJECT_ID
Java アプリケーションをデプロイする
このセクションの手順では、計測されていないサンプル Java アプリケーションである OpenTelemetry Spring Boot インストルメンテーションの例をクラスタにデプロイします。このセクションでは、Cloud Build と Artifact Registry を使用してアプリケーション イメージを作成し、保存します。
Artifact Registry リポジトリがまだない場合は、次のコマンドを実行してリポジトリを作成します。
gcloud artifacts repositories create opentelemetry-autoinstrument-registry --repository-format=docker --location=us-east4 --description="GKE Autoinstrumentation sample app"次のコマンドを実行して、サンプル アプリケーションのクローンを作成します。
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java.git次の環境変数を設定します。
export GOOGLE_CLOUD_PROJECT=PROJECT_ID export ARTIFACT_REGISTRY=opentelemetry-autoinstrument-registry export REGISTRY_LOCATION=us-east4次のコマンドを実行して、アプリケーション イメージをビルドし、Artifact Registry リポジトリに push します。
pushd opentelemetry-operations-java/examples/instrumentation-quickstart && \ gcloud builds submit --config <(envsubst < cloudbuild-uninstrumented-app.yaml) . && \ popdアプリケーションの Kubernetes Deployment 構成ファイルを作成します。次の構成をコピーして、
deployment.yamlという名前のファイルに保存します。apiVersion: v1 kind: Service metadata: name: quickstart-app labels: app: quickstart-app app.kubernetes.io/part-of: gke-autoinstrument-guide spec: ports: - port: 8080 targetPort: 8080 name: quickstart-app selector: app: quickstart-app --- apiVersion: apps/v1 kind: Deployment metadata: name: quickstart-app labels: app: quickstart-app app.kubernetes.io/part-of: gke-autoinstrument-guide spec: replicas: 2 selector: matchLabels: app: quickstart-app template: metadata: labels: app: quickstart-app spec: containers: - name: quickstart-app image: us-east4-docker.pkg.dev/PROJECT_ID/opentelemetry-autoinstrument-registry/java-quickstart:latest ports: - containerPort: 8080 name: quickstart-app次のコマンドを実行して、アプリケーションの名前空間を作成します。
kubectl create namespace APPLICATION_NAMESPACE次のコマンドを実行して、Deployment 構成をクラスタに適用します。
kubectl apply -f deployment.yaml -n APPLICATION_NAMESPACEデプロイを作成した後、Pod が作成されて実行を開始するまでに時間がかかることがあります。Pod のステータスを確認するには、次のコマンドを実行します。
kubectl get po -n APPLICATION_NAMESPACE -wPod のステータスの監視を停止するには、Ctrl+C キーを押してコマンドを停止します。
OpenTelemetry Collector インスタンスを設定する
このセクションでは、GKE クラスタで Google が構築した OpenTelemetry Collector インスタンスを実行する別のデプロイを作成します。コレクタは、次のエクスポータを使用してデータをエクスポートするように構成されています。
- OTLP HTTP エクスポータを使用した指標
- OTLP HTTP エクスポータを使用したトレース
- Google Cloud Exporter を使用したログ
このドキュメントの手順に沿って OpenTelemetry Collector を手動でデプロイする代わりに、マネージド環境で Google が構築した OpenTelemetry Collector を使用する GKE 用マネージド OpenTelemetry を使用することもできます。
次のコマンドを実行して、OpenTelemetry Collector のデプロイ用に Kubernetes サービス アカウントを承認します。
export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)") gcloud projects add-iam-policy-binding projects/PROJECT_ID \ --role=roles/logging.logWriter \ --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \ --condition=None gcloud projects add-iam-policy-binding projects/PROJECT_ID \ --role=roles/monitoring.metricWriter \ --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \ --condition=None gcloud projects add-iam-policy-binding projects/PROJECT_ID \ --role=roles/telemetry.tracesWriter \ --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \ --condition=None
次のコマンドを実行して、推奨されるデフォルト構成で Google 構築の OpenTelemetry Collector インスタンスを GKE クラスタにデプロイします。
kubectl kustomize https://github.com/GoogleCloudPlatform/otlp-k8s-ingest//k8s/base?ref=otlpmetric | envsubst | kubectl apply -f -この構成により、コレクタが
opentelemetryNamespace にデプロイされます。デプロイを作成した後、Pod が作成されて実行を開始するまでに時間がかかることがあります。Pod のステータスを確認するには、次のコマンドを実行します。
kubectl get po -n opentelemetry -wPod のステータスの監視を停止するには、Ctrl+C キーを押してコマンドを停止します。
OpenTelemetry ゼロコード インストルメンテーションを構成する
GKE にデプロイされたアプリケーションの OpenTelemetry ゼロコード計測を構成するには、GKE クラスタに OpenTelemetry Operator をインストールします。OpenTelemetry Operator は、クラスタ内で実行されている Kubernetes リソースに自動計測を挿入するために使用される Kubernetes カスタム リソース定義（CRD）である計測リソースへのアクセスを提供します。
計測リソースは、特別なアノテーションを使用して特定のワークロードに「挿入」または「適用」されます。OpenTelemetry Operator は、クラスタ内で実行されているリソースのこれらのアノテーションを監視し、これらのリソースで管理されているアプリケーションに適切な計測を挿入します。
Helm CLI がまだインストールされていない場合は、次のコマンドを実行して Helm をインストールします。
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 chmod 700 get_helm.sh ./get_helm.shクラスタに
cert-managerがインストールされていない場合は、次のコマンドを実行してインストールします。helm repo add jetstack https://charts.jetstack.io helm repo update helm install \ --create-namespace \ --namespace cert-manager \ --set installCRDs=true \ --set global.leaderElection.namespace=cert-manager \ --set extraArgs={--issuer-ambient-credentials=true} \ cert-manager jetstack/cert-manager次のコマンドを実行し、バージョン 0.140.0 以降を使用して OpenTelemetry Operator をインストールします。
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/download/v0.140.0/opentelemetry-operator.yaml次の内容の
instrumentation.yamlという名前のファイルを作成して、計測カスタム リソースの構成ファイルを作成します。apiVersion: opentelemetry.io/v1alpha1 kind: Instrumentation metadata: name: sample-java-auto-instrumentation spec: exporter: endpoint: http://opentelemetry-collector.opentelemetry.svc.cluster.local:4317 sampler: type: parentbased_traceidratio # Adjust the sampling rate to control cost argument: "0.01" java: env: - name: OTEL_EXPORTER_OTLP_PROTOCOL value: grpc - name: OTEL_LOGS_EXPORTER value: noneOperator の Namespace を作成します。アプリケーション Namespace に使用した値（APPLICATION_NAMESPACE）と同じ値を使用できます。
kubectl create namespace INSTRUMENTATION_NAMESPACE次のコマンドを実行して、クラスタに Instrumentation カスタム リソースを作成し、
instrumentation.yamlファイルを適用します。kubectl apply -f instrumentation.yaml -n INSTRUMENTATION_NAMESPACE以前にデプロイした Java アプリケーションの例に自動計測アノテーションを適用します。次のコマンドを実行して、アノテーションを使用して元のデプロイをパッチ適用します。
kubectl patch deployment.apps/quickstart-app -n APPLICATION_NAMESPACE -p '{"spec":{"template":{"metadata":{"annotations":{"instrumentation.opentelemetry.io/inject-java": "'"INSTRUMENTATION_NAMESPACE"'/sample-java-auto-instrumentation"}}}}}'デプロイにパッチを適用すると、アプリケーションのデプロイが再起動します。次のコマンドを実行して、アプリケーション内の Pod のステータスを確認できます。
kubectl get po -n APPLICATION_NAMESPACE -wPod のステータスの監視を停止するには、Ctrl+C キーを押してコマンドを停止します。
GKE クラスタにデプロイされた Java アプリケーションが自動計測されるようになりました。
デプロイされたアプリケーションからテレメトリーを生成する
自動計測されたアプリケーションからテレメトリーを生成するには、ユーザー アクティビティをシミュレートするリクエストをアプリケーションに送信する必要があります。トラフィック シミュレータを実行すると、安定したトラフィック ストリームを生成できます。このセクションでは、シミュレータをダウンロードし、Cloud Build を使用してビルドし、Artifact Registry にイメージを保存して、シミュレータをデプロイする方法について説明します。
次のコマンドを実行して、トラフィック シミュレータ アプリケーションをダウンロードします。
mkdir traffic-simulator && pushd traffic-simulator && \ curl -O https://raw.githubusercontent.com/GoogleCloudPlatform/opentelemetry-operator-sample/refs/heads/main/recipes/self-managed-otlp-ingest/traffic/hey.Dockerfile && \ curl -O https://raw.githubusercontent.com/GoogleCloudPlatform/opentelemetry-operator-sample/refs/heads/main/recipes/self-managed-otlp-ingest/traffic/cloudbuild-hey.yaml && \ popd上記のコマンドは、次の処理を行います。
- トラフィック シミュレータ アプリケーションをビルドするための別のディレクトリを作成します。
- アプリケーションの Dockerfile をダウンロードします。
- アプリケーション イメージをビルドする Cloud Build 構成をダウンロードします。
次のコマンドを実行して、Cloud Build でアプリケーション イメージを作成し、Artifact Registry に push します。
pushd traffic-simulator && \ gcloud builds submit --config <(envsubst < cloudbuild-hey.yaml) . && \ popd次の内容を
traffic-simulatorディレクトリのquickstart-traffic.yamlという名前のファイルにコピーして、シミュレータのデプロイ構成ファイルを作成します。apiVersion: apps/v1 kind: Deployment metadata: name: traffic-simulator labels: app.kubernetes.io/part-of: gke-autoinstrument-guide spec: replicas: 1 selector: matchLabels: app: traffic-simulator template: metadata: labels: app: traffic-simulator spec: containers: - name: traffic-simulator image: us-east4-docker.pkg.dev/PROJECT_ID/opentelemetry-autoinstrument-registry/hey:latest args: - -c=2 - -q=1 - -z=1h - http://quickstart-app:8080/multi次のコマンドを実行して、トラフィック シミュレータをデプロイします。
pushd traffic-simulator && \ kubectl apply -f quickstart-traffic.yaml -n APPLICATION_NAMESPACE && \ popdデプロイを作成した後、Pod が作成されて実行を開始するまでに時間がかかることがあります。Pod のステータスを確認するには、次のコマンドを実行します。
kubectl get po -n APPLICATION_NAMESPACE -wPod のステータスの監視を停止するには、Ctrl+C キーを押してコマンドを停止します。
テレメトリーを表示する
トラフィック シミュレータがアプリケーションへのリクエストの送信を開始すると、デプロイされた Java アプリケーションがテレメトリーを生成します。指標とトレースが Google Cloudに表示されるまでに数分かかることがあります。
OpenTelemetry Operator によって挿入される計測は、OpenTelemetry Java エージェントに依存します。OpenTelemetry Java Agent には、指標を出力する多くの一般的な Java ライブラリとフレームワークの組み込み計測が含まれています。
挿入された計測は、サンプル アプリケーションによって公開されたエンドポイントに対する呼び出しのトレースも自動的にキャプチャします。トラフィック シミュレータは、Java アプリケーションによって公開された
/multiエンドポイントに一定のレートでリクエストを継続的に送信します。/multiエンドポイントは、最終的なレスポンスを生成するために/singleエンドポイントにリクエストを送信します。これらのインタラクションは、Trace エクスプローラで表示できるトレースとして記録されます。
指標を表示する
自動計測された指標は、Cloud Monitoring の Metrics Explorer で確認できます。このセクションでは、PromQL で記述されたクエリの例を示します。
Google Cloud コンソールで leaderboard Metrics explorer のページに移動します。
検索バーを使用してこのページを検索する場合は、小見出しが [Monitoring] である結果を選択します。
サンプル アプリケーションで表示できる指標には、次のようなものがあります。
JVM ランタイム指標: OpenTelemetry Java Agent は、基盤となる JVM に関する指標を出力します。これらの指標は、JVM メモリ、ガベージ コレクション、クラス、スレッド、その他の関連するコンセプトに関する情報を公開します。サポートされている JVM 指標の完全なリストについては、JVM ランタイム指標のセマンティック規約のページをご覧ください。
JVM メモリ使用量: 次の PromQL クエリを Metrics Explorer に貼り付けます。
sum(avg_over_time({"process.runtime.jvm.memory.usage"}[${__interval}]))JVM CPU 使用率: 次の PromQL クエリを Metrics Explorer に貼り付けます。
sum(avg_over_time({"process.runtime.jvm.cpu.utilization"}[${__interval}]))次のグラフは、JVM CPU 使用率の指標を示しています。
Spring Boot 指標: サンプル アプリケーションは Spring Boot フレームワークを使用します。このフレームワークは、Java 用の OpenTelemetry ゼロコード インストルメンテーションでもサポートされています。
HTTP クライアントの平均所要時間: 次の PromQL クエリを Metrics Explorer に貼り付けます。
sum(rate({"http.client.duration_sum"}[${__interval}])) by (cluster, job) / sum(rate({"http.client.duration_count"}[${__interval}])) by (cluster, job)HTTP サーバーの平均所要時間: 次の PromQL クエリを Metrics Explorer に貼り付けます。
sum(rate({"http.server.duration_sum"}[${__interval}])) by (cluster, job) / sum(rate({"http.server.duration_count"}[${__interval}])) by (cluster, job)次のグラフは、Spring Boot の HTTP サーバーの平均所要時間指標を示しています。
Metrics Explorer の使用方法の詳細については、Metrics Explorer 使用時に指標を選択するをご覧ください。
トレースを表示
自動計測されたトレースは、Cloud Trace の Trace エクスプローラで確認できます。これらのトレースを Trace Explorer でフィルタするには、[サービス名] でフィルタし、サービス名を quickstart-app に設定します。
Google Cloud コンソールで、
[Trace エクスプローラ] ページに移動します。
このページは、検索バーを使用して見つけることもできます。
次のスクリーンショットは、OpenTelemetry quickstart-app デプロイによって生成されたトレースを示しています。
Trace エクスプローラの使用方法について詳しくは、トレースを検索して調査するをご覧ください。
クリーンアップ
新しい Google Cloud プロジェクトを作成して、それが不要になった場合は、次のコマンドを実行して削除できます。
gcloud projects delete PROJECT_ID
既存のプロジェクトを使用した場合は、このチュートリアルで作成したリソースを削除して費用を節約できます。
次のコマンドを実行して、GKE クラスタを削除します。
gcloud container clusters delete CLUSTER_NAME --location=us-east1次のコマンドを実行して、Artifact Registry リポジトリを削除します。
gcloud artifacts repositories delete opentelemetry-autoinstrument-registry --location=us-east4