- 重要な情報
- はじめに
- 用語集
- エージェント
- インテグレーション
- OpenTelemetry
- 開発者
- API
- CoScreen
- アプリ内
- インフラストラクチャー
- アプリケーションパフォーマンス
- 継続的インテグレーション
- ログ管理
- セキュリティ
- UX モニタリング
- 管理
OpenTelemetry Collector は、あらゆるベンダーに対応するエージェントプロセスで、さまざまなプロセスにより送信されたテレメトリデータを収集、エクスポートします。OpenTelemetry Collector 用の Datadog エクスポーターでは、OpenTelemetry SDK から Datadog にトレース、メトリクス、ログデータを転送することができます (Datadog Agent は不要です)。すべての対応言語で動作するほか、これらの OpenTelemetry トレースデータをアプリケーションログに接続することができます。
Datadog Exporter と一緒に OpenTelemetry Collector を実行するには
OpenTelemetry Collector Contribute の最新リリースをプロジェクトのリポジトリからダウンロードします。
Datadog Exporter を使用するには、OpenTelemetry Collector の構成に追加します。コンフィギュレーションファイルを作成し、collector.yaml
という名前をつけます。Datadog API キーを環境変数 DD_API_KEY
に設定した後、すぐに使用できる基本構成を提供するサンプルファイルを使用します。
collector.yaml
receivers:
otlp:
protocols:
http:
grpc:
# Datadog で正しいインフラストラクチャーのメトリクスを取得するためには、hostmetrics レシーバーが必要です。
hostmetrics:
collection_interval: 10s
scrapers:
paging:
metrics:
system.paging.utilization:
enabled: true
cpu:
metrics:
system.cpu.utilization:
enabled: true
disk:
filesystem:
metrics:
system.filesystem.utilization:
enabled: true
load:
memory:
network:
processes:
# prometheus レシーバーは、OpenTelemetry コレクターダッシュボードに必要なメトリクスをスクレイピングします。
prometheus:
config:
scrape_configs:
- job_name: 'otelcol'
scrape_interval: 10s
static_configs:
- targets: ['0.0.0.0:8888']
filelog:
include_file_path: true
poll_interval: 500ms
include:
- /var/log/**/*example*/*.log
processors:
batch:
send_batch_max_size: 100
send_batch_size: 10
timeout: 10s
exporters:
datadog:
api:
site: <DD_SITE>
key: ${env:DD_API_KEY}
service:
pipelines:
metrics:
receivers: [hostmetrics, prometheus, otlp]
processors: [batch]
exporters: [datadog]
traces:
receivers: [otlp]
processors: [batch]
exporters: [datadog]
logs:
receivers: [otlp, filelog]
processors: [batch]
exporters: [datadog]
ここで <DD_SITE>
はあなたのサイト、 となります。
上記の構成により、OpenTelemetry のインスツルメンテーションライブラリから HTTP と gRPC で OTLP データを受信できるようになり、非開発環境では必須のバッチ処理が設定されます。なお、バッチ処理でテレメトリーデータを大量に処理すると、413 - Request Entity Too Large
エラーが発生することがあります。
バッチプロセッサの正確な構成は、シグナルの種類だけでなく、特定のワークロードに依存します。Datadog インテークは、3 つのシグナルタイプに対して異なるペイロードサイズ制限を設けています。
Datadog Exporter の構成オプションは、このドキュメントにあるコンフィギュレーションファイルの例で説明されています。デプロイメントに関連する他のオプション、例えば api::site
や host_metadata
セクションにあるものがあるかもしれません。
トレースのメタデータを充実させ、Datadog とのインテグレーションを円滑に行うには
リソース検出システムを使用する: 言語 SDK で提供されている場合、コンテナ情報をリソース属性としてアタッチします。例えば、Go の場合、WithContainer()
リソースオプションを使用します。
**統合サービスタグ付け**を適用する: 統合サービスタグ付けに適切なリソース属性をアプリケーションに構成していることを確認してください。これは、Datadog のテレメトリーを、サービス名、デプロイ環境、サービスバージョンなどのタグで結びつけます。アプリケーションはこれらのタグを OpenTelemetry のセマンティック規則 (service.name
、deployment.environment
、service.version
) を使用して設定する必要があります。
OpenTelemetry SDK のロギング機能は完全にサポートされていないため (詳細は OpenTelemetry ドキュメントの各言語を参照)、Datadog ではアプリケーションに標準のロギングライブラリを使用することを推奨しています。言語固有のログ収集のドキュメントに従って、アプリケーションに適切なロガーをセットアップしてください。Datadog は、カスタムパースルールの必要性を避けるために、JSON でログを出力するようにロギングライブラリを設定することを強く推奨しています。
演算子を使って、filelog レシーバーを構成します。例えば、checkoutservice
というサービスがあり、それが /var/log/pods/services/checkout/0.log
にログを書き込んでいるとしたら、ログのサンプルは以下のようになります。
{"level":"info","message":"order confirmation email sent to \"jack@example.com\"","service":"checkoutservice","span_id":"197492ff2b4e1c65","timestamp":"2022-10-10T22:17:14.841359661Z","trace_id":"e12c408e028299900d48a9dd29b0dc4c"}
filelog の構成例
filelog:
include:
- /var/log/pods/**/*checkout*/*.log
start_at: end
poll_interval: 500ms
operators:
- id: parse_log
type: json_parser
parse_from: body
- id: trace
type: trace_parser
trace_id:
parse_from: attributes.trace_id
span_id:
parse_from: attributes.span_id
attributes:
ddtags: env:staging
include
: レシーバーが追跡するファイルのリストstart_at: end
: 書き込まれている新しいコンテンツを読むことを示しますpoll_internal
: ポーリング頻度を設定しますjson_parser
: JSON ログをパースします。デフォルトでは、filelog レシーバーは各ログ行をログレコードに変換し、それがログのデータモデルの body
となります。次に、json_parser
が JSON の本文をデータモデルの属性に変換します。trace_parser
: Datadog でログとトレースを関連付けるために、ログから trace_id
と span_id
を抽出します。Kubernetes インフラストラクチャーで OpenTelemetry Collector と Datadog Exporter をデプロイする方法は複数あります。filelog レシーバーを動作させるためには、Agent/DaemonSet デプロイが推奨されるデプロイ方法です。
コンテナ環境では、アプリケーションは stdout
または stderr
にログを書き込みます。Kubernetes はログを収集し、標準的な場所に書き込みます。ホストノード上のロケーションを filelog レシーバー用の Collector にマウントする必要があります。以下は、ログを送信するために必要なマウントを持つ拡張機能例です。
apiVersion: apps/v1
kind: DaemonSet
metadata:
name: otel-agent
labels:
app: opentelemetry
component: otel-collector
spec:
template:
metadata:
labels:
app: opentelemetry
component: otel-collector
spec:
containers:
- name: collector
command:
- "/otelcol-contrib"
- "--config=/conf/otel-agent-config.yaml"
image: otel/opentelemetry-collector-contrib:0.61.0
env:
- name: POD_IP
valueFrom:
fieldRef:
fieldPath: status.podIP
# k8s.pod.ip は、k8sattributes のポッドを関連付けるために使用されます
- name: OTEL_RESOURCE_ATTRIBUTES
value: "k8s.pod.ip=$(POD_IP)"
ports:
- containerPort: 4318 # OpenTelemetry HTTP レシーバーのデフォルトポート。
hostPort: 4318
- containerPort: 4317 # OpenTelemetry gRPC レシーバーのデフォルトポート。
hostPort: 4317
- containerPort: 8888 # メトリクスをクエリするためのデフォルトのエンドポイント。
volumeMounts:
- name: otel-agent-config-vol
mountPath: /conf
- name: varlogpods
mountPath: /var/log/pods
readOnly: true
- name: varlibdockercontainers
mountPath: /var/lib/docker/containers
readOnly: true
volumes:
- name: otel-agent-config-vol
configMap:
name: otel-agent-conf
items:
- key: otel-agent-config
path: otel-agent-config.yaml
# マウントノードのログファイルの場所。
- name: varlogpods
hostPath:
path: /var/log/pods
- name: varlibdockercontainers
hostPath:
path: /var/lib/docker/containers
コンフィグレーションファイルを --config
パラメータで指定し、コレクターを実行します。
otelcontribcol_linux_amd64 --config collector.yaml
OpenTelemetry Collector を Docker イメージとして実行し、同じホストからトレースを受信するには
otel/opentelemetry-collector-contrib
などの公開された Docker イメージを選択します。
OpenTelemetry のトレースを OpenTelemetry Collector に送信するために、コンテナ上でどのポートをオープンするかを決定します。デフォルトでは、トレースはポート 4317 の gRPC で送信されます。gRPC を使用しない場合は、ポート 4138 を使用します。
コンテナを実行し、事前に定義した collector.yaml
ファイルを使用して、必要なポートを公開します。例えば、ポート 4317 を使用する場合を考えてみましょう。
$ docker run \
-p 4317:4317 \
--hostname $(hostname) \
-v $(pwd)/otel_collector_config.yaml:/etc/otelcol-contrib/config.yaml \
otel/opentelemetry-collector-contrib
OpenTelemetry Collector を Docker イメージとして実行し、その他のコンテナからトレースを受信するには
Docker ネットワークを作成します。
docker network create <NETWORK_NAME>
OpenTelemetry Collector とアプリケーションコンテナを同じネットワークの一部として実行します。
# Run the OpenTelemetry Collector
docker run -d --name opentelemetry-collector \
--network <NETWORK_NAME> \
--hostname $(hostname) \
-v $(pwd)/otel_collector_config.yaml:/etc/otelcol-contrib/config.yaml \
otel/opentelemetry-collector-contrib
アプリケーションコンテナの実行中は、環境変数 OTEL_EXPORTER_OTLP_ENDPOINT
が OpenTelemetry Collector 向けの適切なホスト名を使用して構成されていることをご確認ください。以下の例では opentelemetry-collector
を使用しています。
# Run the application container
docker run -d --name app \
--network <NETWORK_NAME> \
--hostname $(hostname) \
-e OTEL_EXPORTER_OTLP_ENDPOINT=http://opentelemetry-collector:4317 \
company/app:latest
Kubernetes 環境で OTel 収集を構成するには、DaemonSet を使用することが最も一般的で推奨される方法です。Kubernetes インフラクチャーに OpenTelemetry コレクターと Datadog エクスポーターをデプロイするには
アプリケーションの構成例も含め、こちらの [Datadog Exporter を DaemonSet として使用した OpenTelemetry Collector の全構成例][11]を使用してください。
特に、DaemonSet の重要なポートがアプリケーションに公開され、アクセスできることを保証する、いくつかの例からの重要な構成オプションに注意してください。
# ...
ports:
- containerPort: 4318 # default port for OpenTelemetry HTTP receiver.
hostPort: 4318
- containerPort: 4317 # default port for OpenTelemetry gRPC receiver.
hostPort: 4317
- containerPort: 8888 # Default endpoint for querying Collector observability metrics.
# ...
もし、アプリケーションに標準の HTTP ポートと gRPC ポートの両方が必要ない場合は、削除しても問題ありません。
Datadog コンテナのタグ付けに使用される貴重な Kubernetes 属性を収集し、例に示すように Pod IP をリソース属性として報告します。
# ...
env:
- name: POD_IP
valueFrom:
fieldRef:
fieldPath: status.podIP
# The k8s.pod.ip is used to associate pods for k8sattributes
- name: OTEL_RESOURCE_ATTRIBUTES
value: "k8s.pod.ip=$(POD_IP)"
# ...
これにより、構成マップで使用される Kubernetes Attributes Processor が、トレースにアタッチするために必要なメタデータを抽出することができるようになるのです。このメタデータにアクセスできるようにするために、追加で設定する必要のあるロールが存在します。この例は完成しており、すぐに使用でき、正しいロールが設定されています。
アプリケーションコンテナを用意します。アプリケーションコンテナを構成するには、正しい OTLP エンドポイントホスト名が使用されていることを確認します。OpenTelemetry コレクターは DaemonSet として実行されるので、現在のホストをターゲットにする必要があります。アプリケーションコンテナの OTEL_EXPORTER_OTLP_ENDPOINT
環境変数を、サンプルチャートのように正しく設定します。
# ...
env:
- name: HOST_IP
valueFrom:
fieldRef:
fieldPath: status.hostIP
# The application SDK must use this environment variable in order to successfully
# connect to the DaemonSet's collector.
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: "http://$(HOST_IP):4318"
# ...
Kubernetes Gateway のデプロイで OpenTelemetry コレクターと Datadog エクスポーターをデプロイするには
アプリケーションの構成例も含め、こちらの Datadog Exporter を DaemonSet として使用した OpenTelemetry Collector の全構成例を使用してください。
特に、DaemonSet の重要なポートがアプリケーションに公開され、アクセスできることを保証する、いくつかの例からの重要な構成オプションに注意してください。
# ...
ports:
- containerPort: 4318 # default port for OpenTelemetry HTTP receiver.
hostPort: 4318
- containerPort: 4317 # default port for OpenTelemetry gRPC receiver.
hostPort: 4317
- containerPort: 8888 # Default endpoint for querying Collector observability metrics.
# ...
もし、アプリケーションに標準の HTTP ポートと gRPC ポートの両方が必要ない場合は、削除しても問題ありません。
Datadog コンテナのタグ付けに使用される貴重な Kubernetes 属性を収集し、例に示すように Pod IP をリソース属性として報告します。
# ...
env:
- name: POD_IP
valueFrom:
fieldRef:
fieldPath: status.podIP
# The k8s.pod.ip is used to associate pods for k8sattributes
- name: OTEL_RESOURCE_ATTRIBUTES
value: "k8s.pod.ip=$(POD_IP)"
# ...
これにより、構成マップで使用される Kubernetes Attributes Processor が、トレースにアタッチするために必要なメタデータを抽出することができるようになるのです。このメタデータにアクセスできるようにするために、追加で設定する必要のあるロールが存在します。この例は完成しており、すぐに使用でき、正しいロールが設定されています。
アプリケーションコンテナを用意します。アプリケーションコンテナを構成するには、正しい OTLP エンドポイントホスト名が使用されていることを確認します。OpenTelemetry コレクターは DaemonSet として実行されるので、現在のホストをターゲットにする必要があります。アプリケーションコンテナの OTEL_EXPORTER_OTLP_ENDPOINT
環境変数を、サンプルチャートのように正しく設定します。
# ...
env:
- name: HOST_IP
valueFrom:
fieldRef:
fieldPath: status.hostIP
# The application SDK must use this environment variable in order to successfully
# connect to the DaemonSet's collector.
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: "http://$(HOST_IP):4318"
# ...
DaemonSet に現在設置されている Datadog Exporter の代わりに OTLP エクスポーターを含めるように変更します。
# ...
exporters:
otlp:
endpoint: "<GATEWAY_HOSTNAME>:4317"
# ...
サービスパイプラインが、サンプルにある Datadog のものでなく、このエクスポーターを使用することを確認してください。
# ...
service:
pipelines:
metrics:
receivers: [hostmetrics, otlp]
processors: [resourcedetection, k8sattributes, batch]
exporters: [otlp]
traces:
receivers: [otlp]
processors: [resourcedetection, k8sattributes, batch]
exporters: [otlp]
# ...
これにより、各 Agent は OTLP プロトコルを介して Collector Gateway にデータを転送することが保証されます。
GATEWAY_HOSTNAME
を OpenTelemetry Collector Gateway のアドレスに置き換えます。
Kubernetes のメタデータがトレースに適用され続けるようにするには、k8sattributes
プロセッサー に Pod IP を Gateway Collector に転送して、メタデータを取得できるようにします。
# ...
k8sattributes:
passthrough: true
# ...
passthrough
オプションの詳細については、そのドキュメントを参照してください。
Gateway Collector の構成が、Agent で OTLP エクスポーターに置き換わったのと同じ Datadog Exporter 設定を使用していることを確認します。例えば、以下のようになります (ここで <DD_SITE>
はあなたのサイト、 です)。
# ...
exporters:
datadog:
api:
site: <DD_SITE>
key: ${env:DD_API_KEY}
# ...
OpenTelemetry Operator を使用するには
OpenTelemetry Operator のデプロイメントに関する公式ドキュメントに従ってください。そこに記載されているように、Operator に加えて、証明書マネージャをデプロイします。
OpenTelemetry Collector の標準 Kubernetes 構成の 1 つを使用して Operator を構成します。
例:
apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
name: opentelemetry-example
spec:
mode: daemonset
hostNetwork: true
image: otel/opentelemetry-collector-contrib
env:
- name: DD_API_KEY
valueFrom:
secretKeyRef:
key: datadog_api_key
name: opentelemetry-example-otelcol-dd-secret
config:
receivers:
otlp:
protocols:
grpc:
http:
hostmetrics:
collection_interval: 10s
scrapers:
paging:
metrics:
system.paging.utilization:
enabled: true
cpu:
metrics:
system.cpu.utilization:
enabled: true
disk:
filesystem:
metrics:
system.filesystem.utilization:
enabled: true
load:
memory:
network:
processors:
k8sattributes:
batch:
send_batch_max_size: 100
send_batch_size: 10
timeout: 10s
exporters:
datadog:
api:
key: ${env:DD_API_KEY}
service:
pipelines:
metrics:
receivers: [hostmetrics, otlp]
processors: [k8sattributes, batch]
exporters: [datadog]
traces:
receivers: [otlp]
processors: [k8sattributes, batch]
exporters: [datadog]
Datadog Agent と並行して OpenTelemetry Collector を使用するには
先に設定した OpenTelemetry Collector DaemonSet と並行して Datadog Agent が各ホストで実行されるように、追加の DaemonSet を設定します。詳細は、Kubernetes での Datadog Agent のデプロイに関するドキュメントをお読みください。
Datadog Agent での OTLP 取り込みを有効にします。
Datadog Agent が OTLP トレースとメトリクスを受信できるようになったので、以下の構成を構成マップに追加することで、OpenTelemetry Collector DaemonSet を変更して Datadog Exporter ではなく、OTLP エクスポーターを使用するように変更します。
# ...
exporters:
otlp:
endpoint: "${HOST_IP}:4317"
tls:
insecure: true
# ...
DaemonSet で環境変数 HOST_IP
が提供されていることを確認します。
# ...
env:
- name: HOST_IP
valueFrom:
fieldRef:
fieldPath: status.hostIP
# ...
サービスパイプラインが OTLP を使用していることを確認します。
# ...
service:
pipelines:
metrics:
receivers: [otlp]
processors: [resourcedetection, k8sattributes, batch]
exporters: [otlp]
traces:
receivers: [otlp]
processors: [resourcedetection, k8sattributes, batch]
exporters: [otlp]
# ...
この場合、Datadog Agent によってこれらのメトリクスが発行されるため、hostmetrics
レシーバーを使用しないでください。
Datadog Exporter を使って OpenTelemetry のトレースも Datadog に送る場合、trace_parser
演算子を使って各トレースから trace_id
を抽出し、それを関連するログに追加してください。Datadog は関連するログとトレースを自動的に関連付けます。詳細は OpenTelemetry のトレースとログの接続を参照してください。
OpenTelemetry シグナルがタグ付けされるホスト名は、以下のソースを基に順番に取得され、現在のソースが利用できないか無効な場合は、次のソースにフォールバックされます。
host.name
(他の多くの属性もサポートされています)。hostname
フィールド。OpenTelemetry コレクターには、2 つの主要なデプロイメント方法があります。Agent と Gateway です。デプロイメント方法によっては、利用できないコンポーネントがあります。
デプロイメントモード | ホストメトリクス | Kubernetes オーケストレーションメトリクス | トレース | ログの自動取り込み |
---|---|---|---|---|
Gateway として | ||||
Agent として |
Datadog は、すぐに使えるダッシュボードを提供しており、コピーしてカスタマイズすることができます。Datadog のすぐに使える OpenTelemetry ダッシュボードを使用するには
OpenTelemetry インテグレーションをインストールします。
Dashboards > Dashboards list にアクセスし、opentelemetry
を検索します。
Host Metrics ダッシュボードは、ホストメトリクスレシーバー から収集されたデータ用です。Collector Metrics ダッシュボードは、有効化するメトリクスレシーバーに応じて収集された他の種類のメトリクス用です。