OpenTelemetry

KubernetesにOBIをデプロイする

Tue, 09 Jun 2026 11:37:14 -0400

注記

このドキュメントでは、必要なエンティティをすべて自分で設定して、KubernetesにOBIを手動でデプロイする方法について説明します。

Kubernetesメタデータデコレーションを構成する

OBIは、次のKubernetesラベルでトレースをデコレートできます。

k8s.namespace.name
k8s.deployment.name
k8s.statefulset.name
k8s.replicaset.name
k8s.daemonset.name
k8s.node.name
k8s.pod.name
k8s.container.name
k8s.pod.uid
k8s.pod.start_time
k8s.cluster.name

メタデータデコレーションを有効化するには、次のことが必要です。

ServiceAccountを作成し、PodとReplicaSetの両方に対してlistとwatchの権限を付与するClusterRoleをバインドします。以下の例のファイルをデプロイすることで実行できます。

apiVersion: v1
kind: ServiceAccount
metadata:
 name: obi
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
 name: obi
rules:
 - apiGroups: ['apps']
 resources: ['replicasets']
 verbs: ['list', 'watch']
 - apiGroups: ['']
 resources: ['pods', 'services', 'nodes']
 verbs: ['list', 'watch']
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
 name: obi
subjects:
 - kind: ServiceAccount
 name: obi
 namespace: default
roleRef:
 apiGroup: rbac.authorization.k8s.io
 kind: ClusterRole
 name: obi

(OBIを別の名前空間にデプロイしている場合は、namespace: default の値を変更する必要があります)

HelmでKubernetesにOBIをデプロイする

Mon, 08 Jun 2026 13:45:02 +0900

注記

Helm の各種設定オプションの詳細については、 OBI Helm チャートドキュメントを参照するか、 Artifact Hub でチャートを参照してください。詳細な設定パラメーターについては、 values.yaml ファイルを参照してください。

Helm から OBI をデプロイする
OBI の設定
OBI メタデータの設定
k8s-cache による Kubernetes メタデータの集約
Helm 設定へのシークレットの提供

Helm から OBI をデプロイする

まず、OpenTelemetry Helm リポジトリを Helm に追加する必要があります。

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts

次のコマンドは、obi 名前空間にデフォルト設定の OBI DaemonSet をデプロイします。

helm install obi -n obi --create-namespace open-telemetry/opentelemetry-ebpf-instrumentation

OBI のデフォルト設定は次のようになっています。

Pod HTTP ポート 9090 の /metrics パスで Prometheus メトリクスとしてメトリクスをエクスポートします。
クラスター内のすべてのアプリケーションを計装しようとします。
デフォルトではアプリケーションレベルのメトリクスのみを提供し、ネットワークレベルのメトリクスは除外します。
k8s.namespace.name や k8s.pod.name などの Kubernetes メタデータラベルでメトリクスを装飾するよう OBI を設定します。

OBI の設定

OBI のデフォルト設定をオーバーライドしたい場合があります。たとえば、Prometheus のかわりに OpenTelemetry としてメトリクスやスパンをエクスポートしたり、計装するサービス数を制限したりする場合です。

はじめに

Mon, 08 Jun 2026 08:54:21 +0900

セットアップ

opentelemetry-java-instrumentationリポジトリの Releasesからopentelemetry-javaagent.jarをダウンロードし、任意のディレクトリに配置してください。この JAR ファイルにはエージェントと計装ライブラリが含まれています。
JVM の起動引数に -javaagent:path/to/opentelemetry-javaagent.jar とその他の設定を追加し、アプリケーションを起動します。
- 起動コマンドに直接指定する場合。
```
java -javaagent:path/to/opentelemetry-javaagent.jar -Dotel.service.name=your-service-name -jar myapp.jar
```
- JAVA_TOOL_OPTIONS やその他の環境変数を経由する場合。
```
export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME="your-service-name"
java -jar myapp.jar
```

宣言的設定

宣言的設定では、環境変数やシステムプロパティのかわりに YAML ファイルを使用します。多くの設定オプションを指定する場合や、環境変数やシステムプロパティでは利用できない設定オプションを使用したい場合に便利です。

詳細については、宣言的設定ページを参照してください。

エージェントの設定

エージェントは高度にカスタマイズ可能です。

一つの選択肢は、設定プロパティを-Dフラグを通じて渡すことです。この例では、サービス名とトレース用の Zipkin エクスポーターを設定しています。

java -javaagent:path/to/opentelemetry-javaagent.jar \
 -Dotel.service.name=your-service-name \
 -Dotel.traces.exporter=zipkin \
 -jar myapp.jar

環境変数を使用してエージェントを設定することもできます。

OTEL_SERVICE_NAME=your-service-name \
OTEL_TRACES_EXPORTER=zipkin \
java -javaagent:path/to/opentelemetry-javaagent.jar \
 -jar myapp.jar

Javaプロパティファイルを指定して、そこから設定値を読み込むこともできます。

java -javaagent:path/to/opentelemetry-javaagent.jar \
 -Dotel.javaagent.configuration-file=path/to/properties/file.properties \
 -jar myapp.jar

または、以下のように設定もできます。

OTEL_JAVAAGENT_CONFIGURATION_FILE=path/to/properties/file.properties \
java -javaagent:path/to/opentelemetry-javaagent.jar \
 -jar myapp.jar

すべての設定オプションについては、エージェント設定を参照してください。

OBI ネットワークメトリクスのクイックスタート

Sun, 07 Jun 2026 21:39:39 +0900

OBI は、あらゆる環境（物理ホスト、仮想ホスト、コンテナ）でネットワークメトリクスを生成できます。 OBI は送信元および送信先の Kubernetes エンティティのメタデータで各メトリクスを装飾できるため、Kubernetes 環境の使用が推奨されます。

このクイックスタートガイドの手順は、kubectl コマンドラインユーティリティを使用して直接 Kubernetes にデプロイすることに焦点を当てています。このチュートリアルでは、OBI を Kubernetes にゼロからデプロイする方法を説明します。 Helm を使用する場合は、Helm を使用した Kubernetes への OBI のデプロイドキュメントを参照してください。

ネットワークメトリクスを有効化して OBI をデプロイする

ネットワークメトリクスを有効化するには、OBI の設定で次のオプションを指定します。

環境変数:

export OTEL_EBPF_NETWORK_METRICS=true

ネットワークメトリクスでは、メトリクスを Kubernetes メタデータで装飾する必要があります。この機能を有効化するには、OBI の設定で次のオプションを指定します。

環境変数:

export OTEL_EBPF_KUBE_METADATA_ENABLE=true

その他の設定オプションについては、OBI 設定オプションを参照してください。

OBI の設定の詳細については、OBI 設定ドキュメントを参照してください。

シンプルなセットアップ

OBI をデプロイする

次の YAML 設定は、ネットワークメトリクス用のシンプルな OBI デプロイメントを提供します。

apiVersion: v1
kind: ServiceAccount
metadata:
 namespace: obi
 name: obi
---
apiVersion: v1
kind: ConfigMap
metadata:
 namespace: obi
 name: obi-config
data:
 obi-config.yml: |
 network:
 enable: true
 attributes:
 kubernetes:
 enable: true
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
 namespace: obi
 name: obi
spec:
 selector:
 matchLabels:
 instrumentation: obi
 template:
 metadata:
 labels:
 instrumentation: obi
 spec:
 serviceAccountName: obi
 hostNetwork: true
 dnsPolicy: ClusterFirstWithHostNet
 containers:
 - name: obi-config
 configMap:
 name: obi-config
 - name: obi
 image: otel/ebpf-instrument:main
 securityContext:
 privileged: true
 volumeMounts:
 - mountPath: /config
 name: obi-config
 env:
 - name: OTEL_EBPF_CONFIG_PATH
 value: '/config/obi-config.yml'

この設定についての注意点は次のとおりです。

クラウドアベイラビリティゾーン間のトラフィックを測定する

Sun, 07 Jun 2026 04:38:15 +0900

注記

この機能は現在 Kubernetes クラスターでのみ利用可能です。

クラウドアベイラビリティゾーン間のトラフィックには追加コストがかかる場合があります。 OBI は、通常のネットワークメトリクスに src.zone および dst.zone 属性を追加するか、または別のメトリクス obi.network.inter.zone.bytes（OTel）/ obi_network_inter_zone_bytes_total（Prometheus）を提供することで、これを測定できます。

通常のネットワークメトリクスに `src.zone` と `dst.zone` 属性を追加する

送信元と送信先のアベイラビリティゾーン属性は、OBI ではデフォルトで無効化されています。有効化するには、OBI の YAML 設定で含めるネットワーク属性のリストに明示的に追加します。

attributes:
 select:
 obi_network_flow_bytes:
 include:
 - k8s.src.owner.name
 - k8s.src.namespace
 - k8s.dst.owner.name
 - k8s.dst.namespace
 - k8s.cluster.name
 - src.zone
 - dst.zone

この設定により、異なる src_zone および dst_zone 属性を持つ obi_network_flow_bytes_total メトリクスごとにゾーン間トラフィックが可視化されます。

ゾーン間トラフィック測定でより高い粒度（たとえば、送信元/送信先の Pod やノード）が必要な場合、ゾーン属性の追加は、同じアベイラビリティゾーン内のトラフィックに対してもメトリクスのカーディナリティに影響します。

`obi.network.inter.zone` メトリクスを使用する

ゾーン間トラフィック用に別のメトリクスを使用すると、通常のネットワークメトリクスに src.zone および dst.zone 属性が追加されないため、データ収集によるメトリクスのカーディナリティへの影響を低減できます。

obi.network.inter.zone メトリクスを有効化するには、network_inter_zone オプションを OTEL_EBPF_METRICS_FEATURES 設定オプション、またはそれに対応する YAML オプションに追加します。たとえば、OBI が OpenTelemetry 経由でメトリクスをエクスポートするように設定されている場合は次のとおりです。

バゲッジ

Sun, 07 Jun 2026 03:38:57 +0900

OpenTelemetryでは、バゲッジ（Baggage）はコンテキストの隣にあるコンテキスト情報です。バゲッジはキーバリューストアなので、コンテキストと一緒に好きなデータを伝搬できます。

バゲッジは、サービスやプロセス間でデータを受け渡し、それらのサービス内のトレース、メトリクス、ログに追加できるようにします。

例

バゲッジは、トレースで、サービス間で追加データを伝搬するためによく使用されます。

たとえば、リクエストの最初に clientId があるとします。しかし、そのIDをトレース内のすべてのスパン、別のサービスのいくつかのメトリクス、そして途中のいくつかのログで利用できるようにしたいとします。トレースは複数のサービスにまたがる可能性があるため、 clientId を多くのサービスにコピーすることなくデータを伝搬する方法が必要です。 clientId をコードベースのあちこちにコピーすることなく、そのデータを伝搬する方法が必要です。

コンテキスト伝搬を使用して、これらのサービス間でバゲッジを渡すことで、 clientId を追加のスパン、メトリクス、またはログに追加できます。さらに、計装は自動的にバゲッジを伝搬してくれます。

OTelバゲッジの使い道

バゲッジは、通常リクエストの開始時にのみ利用可能な情報を、さらに下流に含めるために使用するのが最適です。これはたとえば、アカウント識別子、ユーザーID、製品ID、オリジンIPのようなものを含められます。

バゲッジを使ってこの情報を伝搬することで、バックエンドのテレメトリーをより深く分析できます。たとえば、データベース呼び出しを追跡するスパンにユーザーIDのような情報を含めると、「どのユーザーがもっとも遅いデータベース呼び出しを経験しているか」のような質問に、より簡単に答えられます。また、下流の操作に関する情報をログに記録し、同じユーザーIDをログデータに含めることもできます。

バゲッジのセキュリティに関する懸念事項

機密性の高いバゲッジのアイテムは、サードパーティのAPIなど、意図しないリソースと共有される可能性があります。これは、自動計装が、サービスのネットワークリクエストのほとんどにバゲッジを含むためです。具体的には、バゲッジやトレースコンテキストの他の部分はHTTPヘッダーで送信されるため、ネットワークトラフィックを検査する誰もがそれを見ることができます。トラフィックがネットワーク内で制限されている場合は、このリスクは適用されないかもしれませんが、下流のサービスがバゲッジをネットワーク外に伝搬する可能性があることに留意してください。

また、バゲッジのアイテムがあなたのものであることを確認するための完全性チェックは組み込まれていません。そのため、読み取る際には注意が必要です。

バゲッジは属性とは異なる

バゲッジについて注意すべき重要な点は、バゲッジは独立したキーバリューストアであり、明示的に追加しない限り、スパン、メトリクス、ログの属性と関連付けられないということです。

バゲッジの要素を各テレメトリーの属性に追加するには、明示的にバゲッジからデータを読み取り、スパン、メトリクス、またはログに属性として追加する必要があります。

バゲッジの一般的な使用例は、トレース全体にわたってスパン属性にデータを追加することなので、いくつかの言語には、スパン作成時にバゲッジからデータを属性として追加するバゲッジスパンプロセッサーがあります。

詳細はバゲッジ仕様を参照のこと。

はじめに

Fri, 05 Jun 2026 16:36:18 +0900

このページでは、OpenTelemetry を使って Kubernetes クラスターの監視を始める最速の方法を説明します。 Kubernetesクラスター、ノード、ポッド、コンテナのメトリクスとログの収集、そしてクラスタがOTLPデータを出力するサービスをサポートできるようにすることに焦点を当てます。

Kubernetes で OpenTelemetry が動いているところを見たいのであれば、OpenTelemetryデモから始めるのがベストです。このデモは OpenTelemetry の実装を説明するためのものですが、Kubernetes 自体を監視する方法の例ではありません。このウォークスルーを終えたら、デモをインストールして、すべての監視がアクティブなワークロードにどのように反応するかを見るのは楽しい実験になるでしょう。

PrometheusからOpenTelemetryへの移行を始めようとしている場合、あるいはOpenTelemetryコレクターを使ってPrometheusメトリクスを収集することに興味がある場合は、Prometheusレシーバーを参照してください。

概要

Kubernetesは多くの重要なテレメトリーをさまざまな方法で公開しています。ログ、イベント、多くの異なるオブジェクトのメトリクス、そしてワークロードによって生成されたデータがあります。

このすべてのデータを収集するために、OpenTelemetryコレクターを使用します。コレクターは、このデータを効率的に収集し、意味のある方法で強化できる、自由に使えるさまざまなツールを備えています。

すべてのデータを収集するには、コレクターを2つの方法でインストールする必要があります。 1つはデーモンセットとして、もう1つはデプロイメントとしてです。コレクターのデーモンセットインストールは、ノード、ポッド、コンテナのサービス、ログ、メトリクスが発するテレメトリーを収集するために使用されます。コレクターのデプロイメントインストールは、クラスタのメトリクスとイベントの収集に使用されます。

コレクターをインストールするには、OpenTelemetry Collector Helm チャートを使用します。 Helm には、コレクターを簡単に設定するためのいくつかの設定オプションが付属しています。 Helm に慣れていない場合は、Helm プロジェクトサイトを確認してください。 Kubernetes オペレーターを使うことに興味があるなら、OpenTelemetry Operator を参照してほしいですが、このガイドでは Helm チャートにフォーカスします。

準備

このガイドでは、Kindクラスターを使用することを前提に説明しますが、適切と思われるKubernetesクラスターを自由に使用することができます。

すでにKindがインストールされていると仮定して、新しいKindクラスタを作成します。

kind create cluster

すでに Helm がインストールされていると仮定して、OpenTelemetry Collector Helm チャートを追加し、後でインストールできるようにします。

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts

デーモンセットコレクター

Kubernetesのテレメトリーを収集する最初のステップは、ノードとそのノード上で実行されているワークロードに関連するテレメトリーを収集するために、OpenTelemetry Collectorのデーモンセットインスタンスをデプロイすることです。デーモンセットは、コレクターのこのインスタンスがすべてのノードにインストールされていることを保証するために使用されます。デーモンセット内のコレクターの各インスタンスは、それが実行されているノードからのみデータを収集します。

OBI ネットワークメトリクスの設定オプション

Fri, 05 Jun 2026 15:51:26 +0900

ネットワークメトリクスは、OBI 設定 YAML ファイルの network プロパティ、または OTEL_EBPF_NETWORK_ を接頭辞とする環境変数のセットで設定します。

YAML の例:

network:
 enable: true
 cidrs:
 - 10.10.0.0/24
 - 10.0.0.0/8
 - 10.30.0.0/16
attributes:
 kubernetes:
 enable: true
 select:
 obi_network_flow_bytes:
 include:
 - k8s.src.owner.name
 - k8s.src.namespace
 - k8s.dst.owner.name
 - k8s.dst.namespace
 - src.cidr
 - dst.cidr
otel_metrics_export:
 endpoint: http://localhost:4318

network YAML セクションに加えて、OBI の設定にはネットワークメトリクスをエクスポートするためのエンドポイントが必要です（前述の例では otel_metrics_export ですが、Prometheus エンドポイントも受け付けます）。

ネットワークメトリクスの設定プロパティ

ネットワークメトリクスを有効化するには、第一階層のメトリクスセクションの features に次のいずれかを追加します。

network は obi_network_flow_bytes メトリクスを有効化します。これは、クラスター内の 2 つのエンドポイント間のバイト数です
network_inter_zone は obi_network_inter_zone_bytes メトリクスを有効化します。これは、クラウドクラスター内の異なるアベイラビリティゾーン間のバイト数です

注意

obi_network_inter_zone_bytes 仕様は現在実験的であり、Kubernetes クラスターでのみ利用可能です。仕様は最終的なものではなく、将来のバージョンの OBI で破壊的変更が導入される可能性があります。

OBIをスタンドアロンプロセスとして実行する

Thu, 04 Jun 2026 11:53:28 -0400

OBIは、他の実行中プロセスを検査できる昇格された権限を持つスタンドアロンのLinux OSプロセスとして実行できます。

ダウンロードとインストール

OBIの実行可能ファイルは、OBIリリースページからダウンロードできます。

OBIのセットアップ

構成オプションドキュメントに従って構成ファイルを作成します。
OBIを特権プロセスとして実行します。

sudo ./obi --config=<構成ファイルのパス>

構成例

構成ファイルの例(obi-config.yml)を示します。

# 基本設定
discovery:
 services:
 - name: my-service
 open_ports: [8080, 8090]
 exe_path: /usr/local/bin/my-service

# トレース構成
traces:
 # トレース有効化
 enabled: true

 # OpenTelemetryエンドポイント
 otlp_endpoint: http://localhost:4318

 # トレースフォーマット
 format: otlp

# メトリクス構成
metrics:
 # メトリクス有効化
 enabled: true

 # OpenTelemetryエンドポイント
 otlp_endpoint: http://localhost:4318

 # メトリクスフォーマット
 format: otlp

# ログ構成
log_level: info

OBIの実行

構成ファイルを使用してOBIを実行します。

DockerコンテナとしてOBIを実行する

Thu, 04 Jun 2026 11:53:28 -0400

OBIは、スタンドアロンのDockerコンテナとして実行し、別のコンテナで実行されているプロセスを計装できます。

OBIの最新イメージは、Docker Hubで次の名前で見つけられます。

ebpf-instrument:main

OBIコンテナは、次のように構成する必要があります。

特権コンテナとして実行するか、SYS_ADMIN ケーパビリティを持つコンテナとして実行します(ただし、この最後のオプションは一部のコンテナ環境では機能しない場合があります)。
host PID名前空間を使用して、他のコンテナ内のプロセスにアクセスできるようにします。

Docker CLIの例

この例では、HTTP/SまたはgRPCサービスを実行しているコンテナが必要です。コンテナがない場合は、Goで書かれたシンプルなブログエンジンサービスを使用できます。

docker run -p 18443:8443 --name goblog mariomac/goblog:dev

上記のコマンドは、シンプルなHTTPSアプリケーションを実行します。このプロセスはコンテナの内部ポート8443を開き、ホストレベルではポート18443として公開されます。

環境変数を設定し、OBIが標準出力に出力し、実行可能ファイルを検査するようにポート(コンテナ)をリッスンするように構成します。

export OTEL_EBPF_TRACE_PRINTER=text
export OTEL_EBPF_OPEN_PORT=8443

OBIは次の設定で実行する必要があります。

--privileged モード、または SYS_ADMIN ケーパビリティ(ただし、一部のコンテナ環境では SYS_ADMIN だけでは特権が不十分な場合があります)
--pid=host オプションを使用したホストのPID名前空間を使用

docker run --rm \
 -e OTEL_EBPF_OPEN_PORT=8443 \
 -e OTEL_EBPF_TRACE_PRINTER=text \
 --pid=host \
 --privileged \
 docker.io/otel/ebpf-instrument:main

OBIの実行後、ブラウザで https://localhost:18443 を開き、アプリを使用してテストデータを生成し、OBIが標準出力に次のようなトレースリクエストを出力することを確認します。

time=2023-05-22T14:03:42.402Z level=INFO msg="creating instrumentation pipeline"
time=2023-05-22T14:03:42.526Z level=INFO msg="Starting main node"
2023-05-22 14:03:53.5222353 (19.066625ms[942.583µs]) 200 GET / [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:03:53.5222353 (355.792µs[321.75µs]) 200 GET /static/style.css [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:03:53.5222353 (170.958µs[142.916µs]) 200 GET /static/img.png [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:13:47.52221347 (7.243667ms[295.292µs]) 200 GET /entry/201710281345_instructions.md [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:13:47.52221347 (115µs[75.625µs]) 200 GET /static/style.css [172.17.0.1]->[localhost:18443] size:0B

これで、OBIがターゲットのHTTPサービスをトレースするようになったので、OpenTelemetryエンドポイントにメトリクスとトレースを送信するか、Prometheusでメトリクスをスクレイプするように構成します。

トレース

Wed, 03 Jun 2026 17:03:29 +0900

トレース は、リクエストがアプリケーションに投げられたときに何が起こるかの全体像を教えてくれます。あなたのアプリケーションが、単一のデータベースを持つモノリスであろうと、洗練されたメッシュサービスであろうと、トレースは、リクエストがアプリケーションの中でたどる完全な「経路」を理解するために不可欠です。

スパンで表現される以下の3つのJSONデータで、これを探ってみましょう。

注記

以下のJSONの例は、特定のフォーマット、特にOTLP/JSONを表すものではありません。OTLP/JSONは、より冗長です。

hello スパンは次のとおりです。

{
 "name": "hello",
 "context": {
 "trace_id": "5b8aa5a2d2c872e8321cf37308d69df2",
 "span_id": "051581bf3cb55c13"
 },
 "parent_id": null,
 "start_time": "2022-04-29T18:52:58.114201Z",
 "end_time": "2022-04-29T18:52:58.114687Z",
 "attributes": {
 "http.route": "some_route1"
 },
 "events": [
 {
 "name": "Guten Tag!",
 "timestamp": "2022-04-29T18:52:58.114561Z",
 "attributes": {
 "event_attributes": 1
 }
 }
 ]
}

これはルートスパンであり、オペレーション全体の始まりと終わりを示します。トレースを示す trace_id フィールドがありますが、parent_id がないことに注意してください。これがルートスパンであることを示します。

hello-greetings スパンは次のとおりです。

{
 "name": "hello-greetings",
 "context": {
 "trace_id": "5b8aa5a2d2c872e8321cf37308d69df2",
 "span_id": "5fb397be34d26b51"
 },
 "parent_id": "051581bf3cb55c13",
 "start_time": "2022-04-29T18:52:58.114304Z",
 "end_time": "2022-04-29T22:52:58.114561Z",
 "attributes": {
 "http.route": "some_route2"
 },
 "events": [
 {
 "name": "hey there!",
 "timestamp": "2022-04-29T18:52:58.114561Z",
 "attributes": {
 "event_attributes": 1
 }
 },
 {
 "name": "bye now!",
 "timestamp": "2022-04-29T18:52:58.114585Z",
 "attributes": {
 "event_attributes": 1
 }
 }
 ]
}

このスパンは、挨拶（greetings）のような特定のタスクをカプセル化していて、その親は hello スパンです。このスパンはルートスパンと同じ trace_id を共有していて、同じトレースの一部であることを示しています。さらに、 hello スパンの span_id と一致する parent_id を持っています。

プロファイル

Fri, 22 May 2026 18:16:58 +0900

ステータス: アルファ

プロファイルは、実行中にどこでアプリケーションがリソースを消費するかを示すサンプルと関連メタデータの集まりです。

サンプルは、あるプログラムのコンテキスト（典型的にはスタックトレース）で検出した値を記録します。

オプションで、より上位のリクエストに対応するトレース ID のような補助情報が付加される場合もあります。

サンプルを取得する瞬間はサンプルイベントとして知られており、観測データ点だけでなく、それが取得された時刻も含みます。

たとえば、On-CPU プロファイルには、サンプル取得時に CPU 上で実行されていたコードに対するサンプル（集約されたスタックトレース）と、各スタックトレースが観測されたタイムスタンプおよび回数が一緒に含まれます。

プロファイルの概要

プロファイルは、ログ、メトリクス、そしてトレースに並ぶ、可観測性における第4の本質的シグナルとして台頭しつつあります。

システムおよびアプリケーションの挙動に対する独自の洞察を提供し、他のシグナルでは見落とされがちなパフォーマンスのボトルネックを明らかにすることがよくあります。

プロファイルは、リソース消費とコード実行に関する詳細な時間に基づくビューを提供し、以下を包含します。

アプリケーションレベルのプロファイリング: どのようにソフトウェアの関数が CPU、メモリ、その他のリソースを消費するかを明らかにし、遅いまたは非効率なコードを特定します。
システムレベルのプロファイリング: インフラストラクチャの全体的なビューを提供し、オペレーティングシステムのコール、カーネル操作、I/O における問題を特定します。

このパフォーマンスの全体像は、以下につながる可能性があります。

より速い根本原因分析: パフォーマンス低下の正確な原因を迅速に特定します。
事前の最適化: ユーザーに影響が出る前に、潜在的な問題を特定します。
リソース利用の改善: コスト削減と効率のためにインフラストラクチャを最適化します。
開発者生産性の向上: 開発者がコードのパフォーマンスを検証し、リグレッションを防ぐのに役立ちます。

プロファイルが他のシグナルをどう補完するか

各 OpenTelemetry シグナルは以下の異なる問いに答えます。

シグナル	問い
ログ	どのような離散イベントが起きたか？（システムの挙動への洞察）
メトリクス	システムレベルで何が起きているか？（例: CPU 使用率が 90%）
トレース	リクエストは、どのように分散システムを通過するか？
プロファイル	どのコードがリソース消費の原因になっているか？

OpenTelemetry のプロファイルは、他のシグナルとの双方向リンクをサポートします。これらの相関は、以下の 2 つの次元で機能します。

リクエストコンテキストの相関: 特定のトレースまたはスパンにプロファイリングデータを結び付けることで、特定のリクエスト中にどのコードが実行されていたかを把握できます。
リソースコンテキストの相関: プロファイリングデータを同じサービスインスタンスのような関連するメトリクス、ログまたはトレースを発したのと同じリソースに結び付けます。

プロファイルは、他のシグナルと相関させたときに特に強力になります。

ログからプロファイルへ: メモリ不足のログエントリから、メモリ負荷の原因となっているコードパスを見つけます。
メトリクスからプロファイルへ: CPU またはメモリ使用量の急増から、それらのリソースを消費している関数に直接たどり着きます。
トレースからプロファイルへ: トレース内の遅いスパンから、レイテンシの原因となっているコードを特定するために対応するプロファイルを参照します。

プロファイルの種類

プロファイリングは、さまざまな種類のリソース使用を取得できます。一般的なプロファイルの種類には、以下が含まれます。

OBI グローバル設定プロパティ

Mon, 11 May 2026 18:00:59 +0900

OBI は、環境変数またはコマンドライン引数 -config か環境変数 OTEL_EBPF_CONFIG_PATH を使用して渡す YAML 設定ファイルを通じて設定できます。環境変数は設定ファイルのプロパティよりも優先されます。たとえば、次のコマンドラインでは、OTEL_EBPF_LOG_LEVEL オプションが config.yaml 内の log_level 設定を上書きします。

設定引数の場合は次のとおりです。

OTEL_EBPF_LOG_LEVEL=debug obi -config /path/to/config.yaml

設定環境変数の場合は次のとおりです。

OTEL_EBPF_LOG_LEVEL=debug OTEL_EBPF_CONFIG_PATH=/path/to/config.yaml obi

設定ファイルのテンプレートについては、YAML 設定ファイルの例を参照してください。

OBI は、HTTP および gRPC アプリケーションからトレースを生成、変換、エクスポートするコンポーネントのパイプラインで構成されています。 YAML 設定では、各コンポーネントに独自のトップレベルセクションがあります。

オプションとして、OBI はネットワークレベルのメトリクスも提供します。詳細については、ネットワークメトリクスのドキュメントを参照してください。

以下のセクションでは、OBI 設定全体に適用されるグローバル設定プロパティについて説明します。

例

trace_printer: json
shutdown_timeout: 30s
channel_buffer_len: 33

YAML 環境変数	説明	型	デフォルト
(YAML なし) `OTEL_EBPF_AUTO_TARGET_EXE`	実行可能ファイルのフルパスへのグロブマッチングによって計装するプロセスを選択します。	string	未設定
(YAML なし) `OTEL_EBPF_AUTO_TARGET_LANGUAGE`	検出されたプログラミング言語（グロブマッチャー）によって計装するプロセスを選択します。たとえば `go`、`java`、`nodejs` などです。	string	未設定
`open_port` `OTEL_EBPF_OPEN_PORT`	オープンポートによって計装するプロセスを選択します。ポートとポート範囲のカンマ区切りリストを受け付けます。	string	未設定
`target_pids` `OTEL_EBPF_TARGET_PID`	PID によって計装するプロセスを選択します。YAML リスト、単一値、またはカンマ区切り環境変数リストを受け付けます。	integer または integer のリスト	未設定
`shutdown_timeout` `OTEL_EBPF_SHUTDOWN_TIMEOUT`	グレースフルシャットダウンのタイムアウトを設定します。	string	“10s”
`log_level` `OTEL_EBPF_LOG_LEVEL`	プロセスロガーの詳細レベルを設定します。有効な値は `DEBUG`、`INFO`、`WARN`、`ERROR` です。	string	`INFO`
`log_format` `OTEL_EBPF_LOG_FORMAT`	ロガーの出力形式を設定します。有効な値は `text`、`json`　です。	string	`text`
`trace_printer` `OTEL_EBPF_TRACE_PRINTER`	計装されたトレースを指定された形式で標準出力に出力します。トレースプリンター形式を参照してください。	string	`disabled`
`enforce_sys_caps` `OTEL_EBPF_ENFORCE_SYS_CAPS`	起動時にシステムケーパビリティが不足している場合の OBI の処理方法を制御します。	boolean	`false`

実行可能ファイル名のマッチング

このプロパティは、ファイルシステム上で実行可能ファイルが存在するディレクトリを含む完全な実行可能コマンドラインに対してグロブマッチングを行います。 OBI は 1 つのプロセス、または同様の特性を持つ複数のプロセスを選択します。より詳細なプロセスの選択とグルーピングについては、サービスディスカバリーのドキュメントを参照してください。

OBI のエクスポートモードを構成する

Mon, 11 May 2026 18:00:43 +0900

Direct モードでは、OBI は OpenTelemetry protocol（OTLP）を使用して、メトリクスとトレースをリモートエンドポイントへ直接プッシュします。

OBI は、たとえばプルモードでスクレイプできるように、Prometheus HTTP エンドポイントを公開することもできます。

Direct モードを使用するには、認証情報を含む構成が必要です。 OTLP エンドポイントの認証情報は、次の環境変数で設定します。

OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_EXPORTER_OTLP_HEADERS

Prometheus のスクレイプエンドポイントを使用して Direct モードで実行する方法については、構成ドキュメントを参照してください。

OBI の構成と実行

このチュートリアルでは、OBI と OTel Collector が同じホスト上でネイティブに実行されていることを前提としています。そのため、トラフィックを保護したり、OTel Collector の OTLP レシーバーで認証を提供したりする必要はありません。

OpenTelemetry eBPF Instrumentation をインストールし、サンプルの構成ファイルをダウンロードしてください。

まず、計装する実行ファイルを指定します。ポート 443 で実行されているサービスの実行ファイルの場合は、YAML ドキュメントに open_port プロパティを追加します。

discovery:
 instrument:
 - open_ports: 443

次に、トレースとメトリクスの送信先を指定します。 OTel collector がローカルホストで実行されている場合は、ポート 4318 を使用します。

otel_metrics_export:
 endpoint: http://localhost:4318
otel_traces_export:
 endpoint: http://localhost:4318

メトリクス、トレース、またはその両方をエクスポートするには、otel_metrics_export と otel_traces_export プロパティの組み合わせを指定できます。

ログ

Mon, 13 Apr 2026 22:50:12 +0900

ログは、構造化（推奨）または非構造化された、任意のメタデータを含む、タイムスタンプ付きのテキストレコードです。すべてのテレメトリーシグナルの中で、ログは最も大きな遺産を持っています。ほとんどのプログラミング言語には、組み込みのログ機能があるか、もしくはよく知られ、広く使われているログライブラリがあります。

OpenTelemetry のログ

OpenTelemetry は、ログレコードを生成するための Logs API と SDK、そして既存のロギングフレームワークと統合するための言語 SDK とロギングブリッジを提供します。ログとは、ロギングプロバイダを通して送信されるあらゆるデータを指し、イベントはログの特殊なタイプです。すべてのログがイベントであるとは限りませんが、すべてのイベントはログです。 Logs API は公開されており、アプリケーションコードから直接使用することも、既存のロギングライブラリやブリッジを介して間接的に使用することもできます。

OpenTelemetry は、既に生成されているログを扱うように設計されており、ログを他のシグナルと関連付けたり、コンテキスト属性を追加したり、異なるソースを共通のフォーマットに正規化して処理およびエクスポートするためのツールを提供します。

OpenTelemetry コレクターの OpenTelemetry のログ

OpenTelemetry コレクターはログを扱うための複数のツールを提供します。

既知の特定のログデータソースを解析する複数のレシーバー
任意のファイルからログを読み取り、異なるフォーマットの解析や正規表現の解析が可能な filelogreceiver
ネストされたデータの解析、構造のフラット化、値の追加/削除/更新などを実行できる transformprocessor などのプロセッサー
OpenTelemetry 以外のフォーマットでログデータを送信できるエクスポーター

OpenTelemetry を採用する最初のステップとして、汎用的なログエージェントとしてコレクターをデプロイすることがよく含まれます。

アプリケーションの OpenTelemetry

アプリケーションにおいて、OpenTelemetry のログは任意のログライブラリやビルトインのログ機能を使って作成されます。自動計装を追加したりSDKを活用したりすると、OpenTelemetry は既存のログをアクティブなトレースやスパンと自動的に関連付け、それらの ID をログの本体に含めます。つまり、OpenTelemetry はログとトレースを自動的に関連付けます。

言語サポート

ログは OpenTelemetry 仕様の stable シグナルです。ログAPIとSDKの各言語固有の実装については、ステータスは以下の通りです。

Language	Logs
C++	Stable
C#/.NET	Stable
Erlang/Elixir	Development
Go	Beta
Java	Stable
JavaScript	Development
PHP	Stable
Python	Development
Ruby	Development
Rust	Beta
Swift	Development

構造化、非構造化、半構造化ログ

OpenTelemetryはあらゆるログ形式に対応していますが、すべての形式が分析に等しく役立つわけではありません。次のセクションでは、構造化ログ、半構造化ログ、非構造化ログの違いについて説明します。重要：JSON形式でエンコードされたログは、安定したスキーマを持つという意味で自動的に「構造化」されるわけではありません。半構造化されている場合もあります。構造化ログとは、一貫したスキーマ、または明確に定義された型付きフィールドを持ち、下流の処理が確実に依存できるログを指します。

仕様ステータスの概要

Wed, 17 Dec 2025 18:49:09 +0900

OpenTelemetryは、シグナルごとに開発されています。シグナルの例として、トレース、メトリクス、バゲージ、ロギングがあります。シグナルは、分散システム全体でデータを相関させるための共有メカニズムであるコンテキスト伝搬に基づいて構築されています。

各シグナルは、4つのコアコンポーネントで構成されています。

シグナルには、プラグインと計装のエコスステムであるcontribコンポーネントも存在します。すべての計装は同じセマンティック規則を共有しており、HTTPリクエストなどの一般的な操作を監視する際に同じデータを生成することを保証しています。

シグナルとコンポーネントの詳細については、OTel仕様の概要を参照してください。

コンポーネントのライフサイクル

コンポーネントは、Draft、Experimental、Stable、Deprecated、Removedの開発サイクルに従います。

Draft コンポーネントは設計中であり、仕様には追加されていません。
Experimental コンポーネントはリリースされており、ベータテストが可能です。
Stable コンポーネントは後方互換性があり、長期サポートの対象となります。
Deprecated コンポーネントは安定していますが、最終的には削除される可能性があります。

ライフサイクルと長期サポートの完全な定義については、バージョニングと安定性を参照してください。

現在のステータス

以下は、現在利用可能なシグナルの高レベルなステータスレポートです。 OpenTelemetryクライアントは共通の仕様に準拠していますが、それぞれ独立して開発されている点に注意してください。

各クライアントの現在のステータスは、GitHubリポジトリのREADMEで確認することをお勧めします。特定の機能に対するクライアントのサポート状況は、仕様準拠の表で確認できます。

次の各セクションでは、コレクターのステータスはプロトコルのステータスと同じであることに注意してください。

トレーシング

仕様
API: stable
SDK: stable
プロトコル: stable
注意事項:
- トレーシングの仕様は現在完全に安定しており、長期サポートの対象となっています。
- トレーシングの仕様は拡張可能ですが、後方互換性のある方法のみです。
- OpenTelemetryクライアントは、トレーシングの実装が完了するとv1.0にバージョニングされます。

メトリクス

仕様
API: stable
SDK: mixed
プロトコル: stable
注意事項:
- OpenTelemetryのメトリクスは現在アクティブに開発中です。
- データモデルはOTLPプロトコルの一部として安定してリリースされています。
- 実験的なメトリクスパイプラインのサポートがコレクターで利用可能です。
- PrometheusのCollectorサポートは、Prometheusコミュニティと協力して開発中です。

バゲージ

仕様
API: stable
SDK: stable
プロトコル: N/A
注意事項:
- OpenTelemetryのバゲージは現在完全に安定しています。
- バゲージはオブザーバビリティツールではなく、トランザクションに任意のキーと値を付与し、ダウンストリームのサービスがそれらにアクセスできるようにするシステムです。そのため、バゲージにはOTLPやコレクターのコンポーネントは存在しません。

ロギング

仕様
Bridge API: stable
SDK: stable
プロトコル: stable
注意事項:
- ログデータモデルは、OpenTelemetryプロトコルの一部としてリリースされています。
- StanzaのOpenTelemetryプロジェクトへの寄贈により、多くのデータ形式のログ処理がコレクターに追加されました。
- OpenTelemetry Log Bridge APIを使用して、既存のログフレームワークからOpenTelemetryにログをブリッジするアペンダーの作成できます。 Log Bridge APIは、エンドユーザーが直接呼び出すことを想定していません。ログアペンダーは現在多くの言語で開発中です。
- OpenTelemetry Log SDKは、Log Bridge APIの標準的な実装です。アプリケーションはSDKを構成して、ログの処理とエクスポート方法（例、OTLPの使用）を指定します。
- OpenTelemetry Log Bridge APIは、イベントセマンティック規約に準拠したログレコードを発行するための実験的なサポートを含んでいます。

プロファイル

仕様
プロトコル: development

メトリクス

Mon, 08 Sep 2025 15:58:45 +0900

メトリクスとは、実行時に取得されるサービスの測定値のことです。測定値を取得した瞬間はメトリクスイベントとして知られており、測定値そのものだけでなく、キャプチャした時刻と関連するメタデータから構成されます。

アプリケーションとリクエストのメトリクスは、可用性とパフォーマンスの重要な指標です。カスタムメトリクスは、可用性指標がユーザー体験やビジネスにどのような影響を与えるかについての洞察を提供できます。収集したデータを使用して、障害を警告したり、需要が高まったときにデプロイを自動的にスケールアップするスケジューリング決定をトリガーしたりできます。

OpenTelemetryのメトリクスがどのように機能するのかを理解するために、コードの計装の一部を担うコンポーネントのリストを見てみましょう。

メータープロバイダー

メータープロバイダー（MeterProvider と呼ばれることもあります）は、Meterのファクトリーです。ほとんどのアプリケーションでは、メータープロバイダーは一度だけ初期化され、そのライフサイクルはアプリケーションのライフサイクルと一致します。メータープロバイダーの初期化には、リソースとエクスポーターの初期化も含まれます。これは通常、OpenTelemetryを使った計測の最初のステップです。いくつかの言語SDKでは、グローバルなメータープロバイダーがすでに初期化されています。

メーター

メーターはメトリクス計装を作成し、実行時にサービスに関する測定値を取得します。メーターはメータープロバイダーから作成されます。

メトリクスエクスポーター

メトリクスエクスポーターはメトリクスデータをコンシューマーに送ります。このコンシューマーは、開発中のデバッグのための標準出力、OpenTelemetryコレクター、あるいは、あなたが選んだオープンソースやベンダーのバックエンドです。

メトリクス計装

OpenTelemetryでは、計測は メトリクス計装 によって行われます。メトリクス計装は以下のように定義されます。

名前
種類
単位（オプション）
説明（オプション）

名前、単位、説明は、開発者が自分で定義するか、リクエストやプロセスメトリクスのような一般的なものについては、セマンティック規約を介して定義されます。

計装の種類は以下のいずれかです。

Counter（カウンター）：時間とともに蓄積される値。これは車のオドメーターのようなものだと考えられます。
Asynchronous Counter（非同期カウンター）： カウンター と同じですが、各エクスポートに対して一度だけ収集されます。連続したインクリメントにアクセスできず、集約された値のみにアクセスできる場合に使用できます。
UpDownCounter（アップダウンカウンター）: 時間の経過とともに蓄積されるけれども、減少することもある値。たとえば、キューの長さは、キュー内のワークアイテムの数によって増減します。
Asynchronous UpDownCounter（非同期アップダウンカウンター）: アップダウンカウンターと同じですが、各エクスポートに対して一度だけ収集されます。連続的な変更にアクセスできず、集約された値（たとえば、現在のキューのサイズ）のみにアクセスできる場合に使用できます。
Gauge（ゲージ）: 読み取った時点での現在の値を測定します。たとえば、自動車の燃料計など。ゲージは同期しています。
Asynchronous Gauge（非同期ゲージ）: ゲージと同じですが、各エクスポートに対して一度だけ収集されます。連続的な変更にアクセスできず、集約された値のみにアクセスできる場合に使用できます。
Histogram（ヒストグラム）: リクエストのレイテンシーなどの値をクライアント側で集約したもの。値の統計に興味がある場合は、ヒストグラムが良いでしょう。たとえば、どれくらいのリクエストが1秒未満か、といった疑問に答えてくれます。

同期と非同期の計装、またどの種類の計装があなたのユースケースにもっとも適しているかについては、補足ガイドラインを参照してください。

集約（アグリゲーション）

メトリクス計装に加えて、**集約（アグリゲーション）**という概念も理解すべき重要なものです。集約とは、多数の測定値を組み合わせて、ある時間ウィンドウの間に発生したメトリクスイベントに関する正確な統計値または推定統計値にする手法です。 OTLPプロトコルは、このような集約されたメトリクスを伝送します。 OpenTelemetry APIは、各計装に対してデフォルトの集約を提供します。これはビューを使ってオーバーライドできます。 OpenTelemetryプロジェクトは、ビジュアライザーやテレメトリーバックエンドでサポートされるデフォルトの集計を提供することを目指しています。

Getting Started

Tue, 12 Aug 2025 09:57:29 +0200

This page will show you how to get started with OpenTelemetry in .NET.

If you are looking for a way to automatically instrument your application, check out this guide.

You will learn how you can instrument a simple .NET application, in such a way that traces, metrics and logs are emitted to the console.

Prerequisites

Ensure that you have the following installed locally:

.NET SDK 8+

Example Application

The following example uses a basic Minimal API with ASP.NET Core application. If you are not using a minimal API with ASP.NET Core, that’s OK — you can use OpenTelemetry .NET with other frameworks as well. For a complete list of libraries for supported frameworks, see the registry.

前提条件

Tue, 05 Aug 2025 22:35:37 +0900

このリポジトリにコントリビュートするために、以下の技術とツールに精通している必要があります。

git
GitHub
Markdown (CommonMark)
YAML

ローカルでドキュメントがビルドとテストされる方法に関連する技術的な詳細は、開発を参照してください。

CNCF CLA に署名

すべての OpenTelemetry コントリビューターは Linux Foundation Contributor License Agreement (CLA) に署名しなければいけません。

CLA への署名を終えていないコントリビューターからのプルリクエストは自動テストが失敗します。指定する名前とメールアドレスは git config で見つかったものと一致している必要があり、git 名とメールアドレスは CNCF で利用するものと一致している必要があります。

行動規範

すべての OpenTelemetry コントリビューターは CNCF Community Code of Conduct に従う必要があります。

コミュニティガイドライン

役割や期待事項を含む OpenTelemetry コミュニティの一般的なガイドラインは、OpenTelemetry New Contributor Guide を参照してください。

Getting Started

Fri, 21 Mar 2025 16:06:24 -0400

This page will show you how to get started with OpenTelemetry .NET Automatic Instrumentation.

If you are looking for a way to manually instrument your application, check out this guide.

You will learn how you can instrument a simple .NET application automatically, in such a way that traces, metrics and logs are emitted to the console.

Prerequisites

Ensure that you have the following installed locally:

.NET SDK 6+

Example Application

The following example uses a basic Minimal API with ASP.NET Core application. If you are not using ASP.NET Core, that’s OK — you can still use OpenTelemetry .NET Automatic Instrumentation.

OpenTelemetry

KubernetesにOBIをデプロイする

Kubernetesメタデータデコレーションを構成する

HelmでKubernetesにOBIをデプロイする

Helm から OBI をデプロイする

OBI の設定

はじめに

セットアップ

宣言的設定

エージェントの設定

OBI ネットワークメトリクスのクイックスタート

ネットワークメトリクスを有効化して OBI をデプロイする

シンプルなセットアップ

OBI をデプロイする

クラウドアベイラビリティゾーン間のトラフィックを測定する

通常のネットワークメトリクスに src.zone と dst.zone 属性を追加する

obi.network.inter.zone メトリクスを使用する

バゲッジ

例

OTelバゲッジの使い道

バゲッジのセキュリティに関する懸念事項

バゲッジは属性とは異なる

はじめに

概要

準備

デーモンセットコレクター

OBI ネットワークメトリクスの設定オプション

ネットワークメトリクスの設定プロパティ

OBIをスタンドアロンプロセスとして実行する

ダウンロードとインストール

OBIのセットアップ

構成例

OBIの実行

DockerコンテナとしてOBIを実行する

Docker CLIの例

トレース

プロファイル

プロファイルの概要

プロファイルが他のシグナルをどう補完するか

プロファイルの種類

OBI グローバル設定プロパティ

実行可能ファイル名のマッチング

OBI のエクスポートモードを構成する

OBI の構成と実行

ログ

OpenTelemetry のログ

OpenTelemetry コレクターの OpenTelemetry のログ

アプリケーションの OpenTelemetry

言語サポート

構造化、非構造化、半構造化ログ

仕様ステータスの概要

コンポーネントのライフサイクル

現在のステータス

トレーシング

メトリクス

バゲージ

ロギング

プロファイル

メトリクス

メータープロバイダー

メーター

メトリクスエクスポーター

メトリクス計装

集約（アグリゲーション）

Getting Started

Prerequisites

Example Application

前提条件

CNCF CLA に署名

行動規範

コミュニティガイドライン

Getting Started

Prerequisites

Example Application

通常のネットワークメトリクスに `src.zone` と `dst.zone` 属性を追加する

`obi.network.inter.zone` メトリクスを使用する