Contents
Datadog APM の概要と導入前提条件
Point（結論）
Datadog APM を有効化すれば、サービス間のリクエスト経路をコードレベルで可視化でき、ボトルネックやエラー原因の特定が迅速に行えます。
Reason（理由）
APM は 分散トレーシング と Datadog の分析 UI を組み合わせた機能です。バックエンドだけでなく、データベース・外部 API への呼び出しまで一括で追跡でき、公式ドキュメントは「コードレベルの分散トレーシング」として位置付けています。
Example（具体例）
| 手順 | 操作内容 | 補足 |
|---|---|---|
| 1️⃣ | API キー取得：Datadog コンソール → Integrations → APIs → 「New API Key」ボタンでキーを生成 | API キーはシークレットとして管理（例: GitHub Secrets） |
| 2️⃣ | Agent インストール（Linux apt 系）DD_AGENT_MAJOR_VERSION=7 DD_API_KEY=<YOUR_API_KEY> bash -c "$(curl -L https://s3.amazonaws.com/dd-agent/scripts/install_script.sh)" |
Agent バージョンは 7.x 以上を推奨（公式: https://docs.datadoghq.com/agent/） |
| 3️⃣ | APM 有効化：DD_APM_ENABLED=true を datadog.yaml に追記、または環境変数で設定 |
設定ファイルの場所は /etc/datadog-agent/datadog.yaml |
Point（再提示）
まずは API キー取得 → Datadog Agent (v7 以上) のインストール → DD_APM_ENABLED=true の設定 を完了させることが、APM 有効化の最小前提条件です。
主要言語別 APM 有効化手順（2026 年最新版）
共通ルール
- 環境変数はすべて 大文字・スネークケース（例:
DD_SERVICE）で統一。 - ライブラリ側の設定オブジェクトでは camelCase（例:
service,env）を使用。 - サンプリング率・ヘッダー除外など、公式に存在しないキーは記載しません。
Java（dd-java-agent）
Point
JVM 起動時に -javaagent:/opt/datadog/dd-java-agent.jar を指定するだけでトレースが取得できます。
Reason
Java エージェントはバイトコードを書き換えて自動インストルメントし、アプリ側の修正が不要です（公式: https://docs.datadoghq.com/tracing/setup_overview/java/）。
Example
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
# 1. エージェント JAR を取得（最新バージョンを推奨） curl -L https://github.com/DataDog/dd-trace-java/releases/latest/download/dd-java-agent.jar \ -o /opt/datadog/dd-java-agent.jar # 2. 環境変数で基本情報を設定 export DD_SERVICE=my-java-service export DD_ENV=production export DD_VERSION=1.4.3 export DD_TRACE_SAMPLE_RATE=0.5 # 50% のサンプリング # 3. JVM 起動オプションにエージェントを追加 java -javaagent:/opt/datadog/dd-java-agent.jar \ -Ddd.service=$DD_SERVICE \ -Ddd.env=$DD_ENV \ -Ddd.version=$DD_VERSION \ -jar /app/myapp.jar |
ポイント
DD_TRACE_SAMPLE_RATE は 環境変数 でも設定可能です。
サービス名・環境はコード側で上書きしたい場合、Tracer.builder().service("override").build() のようにプログラムからも指定できます。
Python（ddtrace-run）
Point
実行コマンドを ddtrace-run でラップするだけでトレースが有効化されます。
Reason
ddtrace-run がインポートフックを設定し、対象プロセス全体に自動計測を付与します（公式: https://docs.datadoghq.com/tracing/setup_overview/python/）。
Example
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# 1. ddtrace パッケージをインストール pip install "ddtrace>=2.0" # 2. 必要な環境変数をエクスポート export DD_SERVICE=my-python-service export DD_ENV=staging export DD_VERSION=0.9.0 export DD_TRACE_SAMPLE_RATE=0.75 # 75% のサンプリング # 3. アプリ起動（自動インストルメント） ddtrace-run python app.py |
ポイント
グローバルタグは DD_TAGS 環境変数で設定可能です。例: export DD_TAGS="team:backend,region:ap-northeast-1"
ヘッダー除外は DD_TRACE_HEADER_TAGS で行います（例: export DD_TRACE_HEADER_TAGS="!authorization,!cookie"）。
Node.js（dd-trace）
Point
dd-trace パッケージをインポートし、init() で有効化します。
Reason
公式 SDK が主要フレームワーク（Express, Koa, Fastify 等）を自動検出し、ミドルウェア層でトレースを付与するためです（公式: https://docs.datadoghq.com/tracing/setup_overview/nodejs/）。
Example
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# 1. パッケージインストール npm install dd-trace --save # 2. アプリのエントリポイント (index.js) の先頭に追加 const tracer = require('dd-trace').init({ service: process.env.DD_SERVICE || 'node-api', env: process.env.DD_ENV || 'production', version: process.env.DD_VERSION || '2.1.0', sampleRate: parseFloat(process.env.DD_TRACE_SAMPLE_RATE) || 0.6, analytics: true, // Analytic events を有効化 }); # 3. 通常通りアプリ起動 node index.js |
ポイント
デフォルトのエージェント接続先は localhost:8126（環境変数 DD_TRACE_AGENT_HOSTNAME, DD_TRACE_AGENT_PORT で上書き可）。
ヘッダー除外はフレームワークごとのプラグイン設定で行います。例: tracer.use('express', { headers: ['x-request-id'] })。
Ruby（ddtrace）
Point
ddtrace gem を導入し、Datadog.configure で設定します。
Reason
公式ガイドは Rails・Sinatra の自動インストルメントを標準提供しており、設定は数行で完了します（公式: https://docs.datadoghq.com/tracing/setup_overview/ruby/）。
Example
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
# 1. Gemfile に追記 gem 'ddtrace', '~> 2.0' # 2. bundle install 後、初期化ファイル (config/initializers/datadog.rb) を作成 Datadog.configure do |c| c.service = ENV.fetch('DD_SERVICE', 'ruby-app') c.env = ENV.fetch('DD_ENV', 'production') c.version = ENV.fetch('DD_VERSION', '3.0.1') # トレース設定 c.tracing.analytics_enabled = true c.tracing.sample_rate = Float(ENV.fetch('DD_TRACE_SAMPLE_RATE', '0.5')) # 50% サンプリング # ヘッダー除外例（authorization をタグ付けしない） c.tracing.header_tags = { 'authorization' => nil } end |
ポイント
DD_TRACE_AGENT_HOSTNAME と DD_TRACE_AGENT_PORT は環境変数で上書き可能です。
PII 除外は header_tags の値を nil にするか、c.tracing.instrument :rails, request_headers: %w[authorization] で個別指定します。
Docker / Kubernetes 環境でのエージェント連携とリソース設定
基本方針
- サイドカー方式または DaemonSet で Datadog Agent をデプロイし、アプリコンテナはローカル
8126ポートへトレースを送信。 - エージェントのリソース上限は過剰に割り当てず、CPU 200m・Memory 256Mi 程度で抑える（公式推奨: https://docs.datadoghq.com/containers/kubernetes/）。
Dockerfile と docker‑compose の具体例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# ---- アプリ側 Dockerfile（Java）---- FROM eclipse-temurin:17-jdk-alpine AS builder ARG DD_AGENT_VERSION=7 # Datadog Java エージェントをビルドステージに取得 RUN curl -L https://github.com/DataDog/dd-trace-java/releases/latest/download/dd-java-agent.jar \ -o /opt/datadog/dd-java-agent.jar FROM eclipse-temurin:17-jre-alpine COPY --from=builder /opt/datadog/dd-java-agent.jar /opt/datadog/dd-java-agent.jar COPY target/app.jar /app.jar ENV DD_SERVICE=my-java-service \ DD_ENV=dev \ DD_VERSION=1.0.0 ENTRYPOINT ["java","-javaagent:/opt/datadog/dd-java-agent.jar","-jar","/app.jar"] |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
# ---- docker-compose.yml ---- version: "3.8" services: app: build: . environment: - DD_SERVICE=${DD_SERVICE} - DD_ENV=dev depends_on: - datadog-agent datadog-agent: image: gcr.io/datadoghq/agent:7 env_file: .env.agent # API_KEY 等は .env ファイルで管理 environment: - DD_APM_ENABLED=true ports: - "8126:8126" volumes: - /var/run/docker.sock:/var/run/docker.sock |
Kubernetes DaemonSet（抜粋）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
apiVersion: apps/v1 kind: DaemonSet metadata: name: datadog-agent labels: app: datadog-agent spec: selector: matchLabels: app: datadog-agent template: metadata: labels: app: datadog-agent spec: containers: - name: agent image: gcr.io/datadoghq/agent:7 env: - name: DD_API_KEY valueFrom: secretKeyRef: name: datadog-secret key: api-key - name: DD_APM_ENABLED value: "true" resources: limits: cpu: "200m" memory: "256Mi" requests: cpu: "100m" memory: "128Mi" |
ポイント
* アプリ側 Pod の env に DD_AGENT_HOST=datadog-agent、DD_TRACE_AGENT_PORT=8126 を設定すれば自動的にエージェントへ接続できます。
トレースデータの可視化と分析（Datadog UI 活用）
Point
APM データは サービスマップ, トレース検索, ダッシュボード から直感的に確認でき、問題箇所を即座に特定できます。
Reason
UI はリアルタイムで集計されたトレース情報をカード形式で表示し、スローレスポンスやエラーレートが高いエンドポイントをハイライトします（公式 UI ガイド: https://docs.datadoghq.com/tracing/visualization/）。
操作手順例
-
サービスマップ
左メニュー → APM → Services → 「Service Map」タブで全サービス間の呼び出し関係がグラフ化され、エッジに平均 latency と error rate が表示されます。 -
トレース検索とフィルタリング
APM → Traces で検索バーにservice:my-java-service env:productionを入力。
「Operation」や「HTTP status code」で絞り込み、遅延が顕著なリクエストをクリックすると個別トレースのタイムラインと各スパン（DB クエリ、外部 API 呼び出し等）が可視化されます。 -
主要メトリクス
Latency (p95), Error Rate (%) が自動でダッシュボードに追加。必要に応じて APM > Dashboards からカスタムビューを作成できます。
ポイント
トレース検索結果の URL（例: https://app.datadoghq.com/apm/traces?query=service%3Amy-java-service）はチーム内共有に便利です。
「Service Overview」ウィジェットをダッシュボードに配置すると、SLO 監視がシンプルになります（公式例: https://docs.datadoghq.com/dashboards/widgets/service_overview/）。
ベストプラクティスと運用フロー
Point
APM の効果を最大化するには データ量抑制・機密情報保護・アラート設計 の 3 点を体系的に管理します。
推奨設定例
| 項目 | 推奨値 / 設定例 | 管理ポイント |
|---|---|---|
| サンプリング率 | DD_TRACE_SAMPLE_RATE=0.2（本番は 20%） |
環境変数で統一管理、負荷テスト時は 1.0 に切替 |
| 機密情報除外 | DD_TRACE_HEADER_TAGS="!authorization,!cookie" |
CI パイプラインで注入、コードレビューでチェック |
| エラートラッキング | DD_ANALYTICS_ENABLED=true + DD_ERROR_STATUS_CODES=500,502,503 |
Datadog の Error Tracking アラートと Slack 連携 |
| 設定の一元管理 | ConfigMap / Secret に datadog-apm-env を作成し、Pod が参照 |
K8s 更新は kubectl rollout restart で即時反映 |
ポイント
サンプリングはサービスごとの負荷特性を考慮し、ConfigMap 経由で一括更新すると運用が楽です。
PII 除外はヘッダーだけでなく リクエストボディの正規表現マスク も検討（DD_TRACE_BODY_SCRUBBER は公式に存在しないため、アプリ側でミドルウェアを利用してください）。
トラブルシューティングチェックリスト
| 症状 | 確認項目 |
|---|---|
| Trace が UI に出ない | 1. エージェントのログ (/var/log/datadog/trace-agent.log) にエラーが無いか2. DD_AGENT_HOST と DD_TRACE_AGENT_PORT が正しいか3. 環境変数 DD_APM_ENABLED=true が設定されているか |
| Latency が異常に高い | 1. サンプリング率が低すぎないか（サンプル不足） 2. ネットワーク遅延 (Agent → Datadog) を ping/traceroute で確認3. エージェントの CPU 使用率が上限に達していないか |
| 機密ヘッダーがタグ付けされている | DD_TRACE_HEADER_TAGS に除外対象 (!authorization) が正しく設定されているか |
CI/CD パイプラインへの自動導入手順
Point
CI/CD に Datadog APM 設定を組み込むことで、デプロイ時の抜け漏れが防げ、テスト環境でも同一設定で検証できます。
GitHub Actions（YAML）例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
name: CI / CD on: push: branches: [ main ] jobs: build-and-deploy: runs-on: ubuntu-latest env: DD_API_KEY: ${{ secrets.DD_API_KEY }} DD_SERVICE: my-service DD_ENV: staging DD_VERSION: ${{ github.sha }} DD_TRACE_SAMPLE_RATE: "0.5" steps: - uses: actions/checkout@v3 # Docker イメージビルド（エージェントはベースイメージに同梱済みと想定） - name: Build image run: | docker build -t ghcr.io/${{ github.repository }}/my-service:${{ github.sha }} . # Kubernetes デプロイ - name: Deploy to K8s env: KUBE_CONFIG_DATA: ${{ secrets.KUBE_CONFIG }} run: | echo "$KUBE_CONFIG_DATA" | base64 --decode > $HOME/.kube/config kubectl set image deployment/my-service my-service=ghcr.io/${{ github.repository }}/my-service:${{ github.sha }} -n staging |
GitLab CI（YAML）例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
stages: - build - deploy variables: DD_SERVICE: "my-service" DD_ENV: "staging" DD_VERSION: "$CI_COMMIT_SHA" DD_TRACE_SAMPLE_RATE: "0.5" build: stage: build image: docker:latest services: - docker:dind script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA . - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA deploy: stage: deploy image: bitnami/kubectl:latest script: - echo "$KUBE_CONFIG" | base64 --decode > /tmp/kubeconfig - export KUBECONFIG=/tmp/kubeconfig - kubectl set image deployment/my-service my-service=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA -n staging |
ポイント
環境変数は GitHub Secrets や GitLab CI/CD Variables に安全に保管し、ジョブ実行時に自動注入。
テスト環境では DD_APM_ENABLED=false をデフォルトとし、Pull Request 時だけ true に切り替える条件式（例: if: github.event_name == 'pull_request'）を追加するとコスト削減につながります。
まとめ
- 前提：API キー取得 → Datadog Agent (v7+) インストール →
DD_APM_ENABLED=true設定 - 言語別設定はすべて公式ドキュメントに沿った環境変数・コード例で統一。
- コンテナ環境はサイドカーまたは DaemonSet でエージェントを配置し、リソース上限は CPU 200m / Memory 256Mi が目安。
- 可視化はサービスマップ・トレース検索・カスタムダッシュボードで実施。
- ベストプラクティスはサンプリング率、ヘッダー除外、エラートラッキングを環境変数で一元管理。
- CI/CD 連携により設定漏れを防止し、ステージごとに APM 有効化フラグを制御。
これらの手順とベストプラクティスをプロジェクトに組み込めば、Datadog APM の導入・運用がスムーズになり、サービス品質向上とコスト最適化の両立が実現できます。