Datadog Heroku ビルドパック

Heroku ビルドパックは、Datadog Agent を Heroku dyno にインストールして、システムメトリクス、カスタムアプリケーションメトリクス、トレースを収集します。カスタムアプリケーションメトリクスとトレースを収集するには、DogStatsD または Datadog APM ライブラリをアプリケーションに含める必要があります。

インストール

このガイドでは、Heroku で実行中のアプリケーションがあることを前提としています。アプリケーションを Heroku にデプロイする方法については、Heroku のドキュメントを参照してください。

1. Datadog API 設定で Datadog API キーをコピーし、次の環境変数へエクスポートします:

   export DD_API_KEY=<YOUR_API_KEY>
   

2. アプリケーション名を APPNAME 環境変数へエクスポートします:

   export APPNAME=<YOUR_HEROKU_APP_NAME>
   

3. Datadog サイトを DD_SITE 環境変数にエクスポートします。

   export DD_SITE=
   

4. Datadog ビルドパックをプロジェクトに追加します:

   cd <HEROKU_PROJECT_ROOT_FOLDER>
   
   # Enable Heroku Labs Dyno Metadata to set HEROKU_APP_NAME env variable automatically
   heroku labs:enable runtime-dyno-metadata -a $APPNAME
   
   # Set hostname in Datadog as appname.dynotype.dynonumber for metrics continuity
   heroku config:add DD_DYNO_HOST=true
   
   # Set the DD_SITE env variable automatically
   heroku config:add DD_SITE=$DD_SITE
   
   # Add this buildpack and set your Datadog API key
   heroku buildpacks:add --index 1 https://github.com/DataDog/heroku-buildpack-datadog.git
   heroku config:add DD_API_KEY=$DD_API_KEY
   
   # Deploy to Heroku forcing a rebuild
   git commit --allow-empty -m "Rebuild slug"
   git push heroku main
   

完了すると、各 dyno の起動時に Datadog Agent が自動的に起動します。

Datadog Agent は、statsd/dogstatsd のメトリクスおよびイベント用に 8125 でリスニングポートを提供します。トレースは、ポート 8126 で収集されます。

ビルドパックの順序

ビルドパックの表示の Heroku のドキュメントに記載の通り、リスト内の最後のビルドパックはアプリケーションのプロセスタイプを決定するために使用されます。

apt パッケージをインストールするビルドパック (heroku-buildpack-apt、puppeteer-heroku-buildpack など) または /app フォルダーを変更するビルドパック (heroku-buildpack-monorepo など) は Datadog ビルドパックの前に追加される必要があります。たとえば、アプリケーションが ruby、datadog、apt ビルドパックを使用している場合、これは正しい heroku buildpacks 出力になります。

1. https://github.com/heroku/heroku-buildpack-apt.git
2. https://github.com/DataDog/heroku-buildpack-datadog.git
3. heroku/ruby

特定のビルドパックバージョンおよび特定の Datadog Agent バージョンを固定する

Heroku では、常にビルドパックの最新コミットを使用することが推奨されています。ビルドパックのバージョンを固定する必要がある場合は、ビルドパックのリリースタグを指定します。

heroku buildpacks:add --index 1 https://github.com/DataDog/heroku-buildpack-datadog.git#<DATADOG_BUILDPACK_RELEASE>

<DATADOG_BUILDPACK_RELEASE> を、現在のビルドパックリリースに置き換えます。

デフォルトで、ビルドパックはリリース時に Datadog Agent の最新バージョンを固定します。DD_AGENT_VERSION の環境変数を設定することで、Agent を以前のバージョンに固定することができます。

アップグレードとスラグの再コンパイル

このビルドパックをアップグレードするか、特定のビルドパックオプションを変更するには、スラグを再コンパイルする必要があります。

次のオプションでは、スラグの再コンパイルが必要です。

• DD_AGENT_VERSION
• DD_AGENT_MAJOR_VERSION
• DD_PYTHON_VERSION
• DD_APM_ENABLED
• DD_PROCESS_AGENT

このビルドパックをアップグレードしたり、これらのオプションのいずれか、たとえば DD_AGENT_VERSION を変更するには、次の手順が必要です。

# Agent の新規バージョンを設定
heroku config:set DD_AGENT_VERSION=<NEW_AGENT_VERSION> -a <YOUR_APP_NAME>

# Agent の新バージョンでスラグを再構築:
git commit --allow-empty -m "Rebuild slug"
git push heroku main

コンフィギュレーション

上で示した環境変数のほかにも、いくつか設定できる変数があります。

その他のドキュメントについては、Datadog Agent のドキュメントを参照してください。

ホスト名

Heroku dyno はエフェメラルです。新しいコードのデプロイ、構成に対する変更、リソースの必要性/可用性の変化などが発生した場合はいつでも 、dyno を別のホストマシンに移動できます。Heroku はこれによって高い柔軟性と応答性を実現していますが、Datadog に報告されるホスト数が非常に多くなる可能性があります。Datadog の課金はホスト単位で行われ、ビルドパックのデフォルトでは実際のホスト数が報告されるため、コストが予想以上に高額になる可能性があります。

使用状況によっては、ホスト名を設定してホストを集約し、報告される数を減らしたい場合があります。このような場合は、DD_DYNO_HOST を true に設定します。これにより、Agent は、アプリケーション名と dyno 名を組み合わせたもの (appname.web.1、appname.run.1234 など) をホスト名として報告するようになり、ホスト数が dyno の使用状況とほぼ一致します。この欠点の 1 つは、dyno が再利用されるたびにメトリクスの連続性エラーが発生することです。

これを適切に機能させるには、HEROKU_APP_NAME を設定する必要がありますが、その最も簡単な方法は、dyno メタデータの有効化です。注: プライベート空間では dyno メタデータはまだ使用できません。この場合、HEROKU_APP_NAME を手動で設定する必要があります。

存続期間が短い dyno の Datadog Agent を無効にする

デフォルトでは、Datadog Agent はアプリケーションの一部である各 dyno で実行されます。これには、scheduler、release、または run dynoが含まれます。多くの場合、これらの dyno からのメトリクスは不要であり、それらの Datadog Agent を無効にすることは理にかなっています。

dyno タイプに基づいて Datadog Agent を無効にするには、次のスニペットを [prerun.sh スクリプト]（＃prerun-script）(#prerun-script)に追加します (監視したくない dyno のタイプに適合させます)。

# dyno タイプに基づいて Datadog Agent を無効にします
if [ "$DYNOTYPE" == "run" ] || [ "$DYNOTYPE" == "scheduler" ] || [ "$DYNOTYPE" == "release" ]; then
  DISABLE_DATADOG_AGENT="true"
fi

システムメトリクス

ビルドパックは、デフォルトで、dyno を実行しているホストマシンのシステムメトリクスを収集します。システムメトリクスは、このビルドパックを使用している個別の dyno では使用できません。ホストシステムメトリクスの収集を無効にするには、DD_DISABLE_HOST_METRICS 環境変数を true に設定します。

dyno のシステムメトリクスを収集するには、以下を行う必要があります。

1. Heroku Labs: log-runtime-metrics を有効にします。
2. Datadog ログドレインを使用して、Heroku Logplex からメトリクスログを収集し、Datadog に転送します。
3. 収集されたログに対してログベースのメトリクスを生成します。

ファイルの場所

• Datadog Agent は、/app/.apt/opt/datadog-agent にインストールされます
• Datadog Agent の構成ファイルは、/app/.apt/etc/datadog-agent にあります
• Datadog Agent のログは、/app/.apt/var/log/datadog にあります

インテグレーションの有効化

Datadog Redis インテグレーションを有効にする

Heroku アプリケーションで Redis アドオン (例: Heroku Data for Redis、Redis Enterprise Cloud) を使用している場合、環境変数を設定することにより、Datadog Redis インテグレーションを有効にすることができます。

heroku config:set DD_ENABLE_HEROKU_REDIS=true

このインテグレーションは、デフォルトで、Redis の接続 URL が REDIS_URL という名前の環境変数で定義されていることを前提としています (これは Heroku Data for Redis およびその他の Redis アドオンのデフォルトの構成です）。

接続 URL が別の環境変数で定義されている場合、または複数の Redis インスタンスを構成したい場合は、DD_REDIS_URL_VAR 環境変数に接続文字列の変数名をカンマ区切りで設定します。例えば、Heroku Redis と Redis Enterprise Cloud の両方を利用している場合は、それに従って DD_REDIS_URL_VAR を設定します。

heroku config:set DD_REDIS_URL_VAR=REDIS_URL,REDISCLOUD_URL

Datadog Postgres インテグレーションを有効にする

Heroku アプリケーションで Postgres アドオン (例: Heroku Postgres) を使用している場合、環境変数を設定することにより、Datadog Postgres インテグレーションを有効にすることができます。

heroku config:set DD_ENABLE_HEROKU_POSTGRES=true

このインテグレーションは、デフォルトで、Postgres の接続 URL が DATABASE_URL という名前の環境変数で定義されていることを前提としています (これは Heroku Postgres およびその他の Postgres アドオンのデフォルトの構成です）。

接続 URL が別の環境変数で定義されている場合、または複数の Postgres インスタンスを構成したい場合は、DD_POSTGRES_URL_VAR 環境変数に接続文字列の変数名をカンマ区切りで設定します。例えば、Postgres インスタンスが 2 つあり、接続文字列が POSTGRES_URL1 と POSTGRES_URL2 に格納されている場合は、それに従って DD_POSTGRES_URL_VAR を設定します。

heroku config:set DD_POSTGRES_URL_VAR=POSTGRES_URL1,POSTGRES_URL2

その他のインテグレーションを有効にする

任意の Datadog-<INTEGRATION_NAME> インテグレーションを有効にするには:

• アプリケーション内に datadog/conf.d フォルダーを作成します。
• 有効にするインテグレーションごとに <INTEGRATION_NAME>.d フォルダーを作成します
• そのフォルダーの配下に、インテグレーションの構成を記載した conf.yaml を作成します。

dyno 起動時、この YAML ファイルは該当する Datadog Agent 構成ディレクトリにコピーされます。

例えば、Datadog-Memcache インテグレーションを有効にする場合、アプリケーションのルートにファイル /datadog/conf.d/mcache.d/conf.yaml (この構成オプションを変更した場合は /$DD_HEROKU_CONF_FOLDER/conf.d/mcache.d/conf.yaml) を追加します。

init_config:

instances:
  ## @param url - string - required
  ## url used to connect to the Memcached instance.
  #
  - url: localhost

注: 使用可能なすべての構成オプションの詳細については、サンプル mcache.d/conf.yaml を参照してください。

コミュニティのインテグレーション

有効にするインテグレーションがコミュニティインテグレーションの一部である場合は、事前実行スクリプトの一部としてパッケージをインストールします。

agent-wrapper integration install -t datadog-<INTEGRATION_NAME>==<INTEGRATION_VERSION>

例えば、Ping インテグレーションをインストールするには、コンフィギュレーションファイル datadog/conf.d/ping.d/conf.yaml を作成し、以下の行を事前実行スクリプトに追加します。

agent-wrapper integration install -t datadog-ping==1.0.0

dyno に基づくインテグレーションを無効にする

Heroku アプリケーションのファイルシステムはすべての dyno で共有されるため、インテグレーションを有効にすると、run または worker dyno を含むすべての dyno で実行されます。もし、dyno 名やタイプに基づいてインテグレーションの実行を制限したい場合は、prerun スクリプトに小さなスニペットを追加することで可能です。

例えば、Gunicorn のインテグレーションが web タイプの dyno でのみ実行される必要がある場合、プリランスクリプトに以下を追加します。

if [ "$DYNOTYPE" != "web" ]; then
  rm -f "$DD_CONF_DIR/conf.d/gunicorn.d/conf.yaml"
fi

カスタムチェックを有効にする

独自の Agent カスタムチェックを有効にするには、アプリケーション内の datadog コンフィギュレーションフォルダーに checks.d フォルダーを作成します。その下に、カスタムチェックのすべての .py と .yaml ファイルをコピーします。dyno の起動中に、ファイルは適切な Datadog Agent のコンフィギュレーションディレクトリにコピーされます。

例えば、foo と bar という 2 つのカスタムチェックがある場合、これは正しいフォルダツリーになります。

.
└── app
    └── datadog
        └── checks.d
            ├── foo.py
            ├── foo.yaml
            ├── bar.py
            └── bar.yaml

事前実行スクリプト

上述したすべてのコンフィギュレーションに加えて、事前実行スクリプト /datadog/prerun.sh をアプリケーションに含めることができます。事前実行スクリプトは、すべての標準コンフィギュレーションアクションの実行後、Datadog Agent の起動直前に実行されます。これにより、環境変数の変更 (例: DD_TAGS または DD_VERSION) や追加構成の実行、コミュニティインテグレーションのインストール、さらには Datadog Agent をプログラムで無効にすることもできます。

以下に、prerun.sh スクリプトで実行できるいくつかの例を示します。

#!/usr/bin/env bash

# dyno タイプに基づいて Datadog Agent を無効にします
if [ "$DYNOTYPE" == "run" ]; then
  DISABLE_DATADOG_AGENT="true"
fi

# dyno タイプに基づいてインテグレーションを無効にします
if [ "$DYNOTYPE" != "web" ]; then
  rm -f "$DD_CONF_DIR/conf.d/gunicorn.d/conf.yaml"
fi

# HEROKU_SLUG_COMMIT に基づいてアプリのバージョンを設定します
if [ -n "$HEROKU_SLUG_COMMIT" ]; then
  DD_VERSION=$HEROKU_SLUG_COMMIT
fi

# "ping" コミュニティインテグレーションをインストールします
agent-wrapper integration install -t datadog-ping==1.0.0

Datadog のコンソール出力の制限

Datadog ビルドパックがコンソールに書き込むログの量を制限したい場合があります。

ビルドパックのログ出力を制限するには、DD_LOG_LEVEL 環境変数を次の値のいずれかに設定します。TRACE、DEBUG、INFO、WARN、ERROR、CRITICAL、OFF。

heroku config:add DD_LOG_LEVEL=ERROR

オプションバイナリ

DD_APM_ENABLED が false に設定されている場合、または DD_PROCESS_AGENT が設定されていないか false に設定されている場合、あるいはその両方の場合は、スラグスペースを節約するために、コンパイル時に trace-agent および process-agent オプションバイナリが削除されます。

スラグサイズを削減するには、APM 機能を使用していない場合は DD_APM_ENABLED を false に設定し、プロセスモニタリングを使用していない場合は DD_PROCESS_AGENT を true に設定します。

デバッグ作業

情報またはデバッグコマンドのいずれかを実行するには、agent-wrapper コマンドを使用します。

たとえば、Datadog Agent と有効なインテグレーションのステータスを表示するには、以下を実行します。

agent-wrapper status

Python と Agent のバージョン

バージョン 6.14 より前の Datadog v6 Agent には、Python バージョン 2 が組み込まれていました。6.14 以降、2020 年 1 月に発表された Python バージョン 2 のサポート終了に合わせて、Datadog v6 Agent には Python バージョン 2 と 3 の両方が付属しています。これは、お客様にカスタムチェックを Pythonバージョン 3 に移行する十分な時間を提供するためです。Heroku ビルドパックは、いずれかのバージョンのみを保持します。DD_PYTHON_VERSION を 2 または 3 に設定して、Agent が保持する Python バージョンを選択します。設定しない場合、ビルドパックは Python バージョン 2 を保持します。Python バージョン 2 でのみ動作するカスタムチェックを使用している場合、サポート終了の前にバージョン 3 に移行します。

Agent v7 には、Python バージョン 3 のみが付属しています。カスタムチェックを使用していない場合、またはカスタムチェックがすでにバージョン 3 に移行されている場合は、できるだけ早く Agent v7 に移行します。6.15 以降、同じマイナーバージョンの v7 リリースは同じ機能セットを共有するため、これら 2 つの間を安全に移動できます。たとえば、6.16 を実行していて、Python バージョン 2 が必要ない場合、7.16 にジャンプしても安全です。

Heroku ログの収集

Datadog ビルドパックは、Heroku プラットフォームからログを収集しません。Heroku のログ収集を設定するには、専用ガイドをご覧ください。

Docker イメージと共に Heroku を使用する

このビルドパックは、Heroku のスラッグコンパイラを使用する Heroku デプロイメントにのみ有効です。Docker コンテナを使用して Heroku にアプリケーションをデプロイしている場合:

1. Datadog Agent を Docker イメージの一部として追加し、コンテナ内の別プロセスとして Agent を起動します。
2. Heroku アプリケーションに以下の構成オプションを設定し、Datadog が Heroku dyno として正しく報告されるようにします。

heroku config:add DD_HEROKU_DYNO=true

たとえば、Debian ベースの OS を使用して Docker イメージをビルドする場合は、以下の行を Dockerfile に追加します。

# GPG 依存関係をインストール
RUN apt-get update \
 && apt-get install -y gnupg apt-transport-https gpg-agent curl ca-certificates

# Datadog リポジトリおよび署名キーを追加
ENV DATADOG_APT_KEYRING="/usr/share/keyrings/datadog-archive-keyring.gpg"
ENV DATADOG_APT_KEYS_URL="https://keys.datadoghq.com"
RUN sh -c "echo 'deb [signed-by=${DATADOG_APT_KEYRING}] https://apt.datadoghq.com/ stable 7' > /etc/apt/sources.list.d/datadog.list"
RUN touch ${DATADOG_APT_KEYRING}
RUN curl -o /tmp/DATADOG_APT_KEY_CURRENT.public "${DATADOG_APT_KEYS_URL}/DATADOG_APT_KEY_CURRENT.public" && \
    gpg --ignore-time-conflict --no-default-keyring --keyring ${DATADOG_APT_KEYRING} --import /tmp/DATADOG_APT_KEY_CURRENT.public
RUN curl -o /tmp/DATADOG_APT_KEY_F14F620E.public "${DATADOG_APT_KEYS_URL}/DATADOG_APT_KEY_F14F620E.public" && \
    gpg --ignore-time-conflict --no-default-keyring --keyring ${DATADOG_APT_KEYRING} --import /tmp/DATADOG_APT_KEY_F14F620E.public
RUN curl -o /tmp/DATADOG_APT_KEY_382E94DE.public "${DATADOG_APT_KEYS_URL}/DATADOG_APT_KEY_382E94DE.public" && \
    gpg --ignore-time-conflict --no-default-keyring --keyring ${DATADOG_APT_KEYRING} --import /tmp/DATADOG_APT_KEY_382E94DE.public


# Datadog Agent をインストール
RUN apt-get update && apt-get -y --force-yes install --reinstall datadog-agent

# エンドポイントをコピー
COPY entrypoint.sh /

# DogStatsD および trace-agent ポートを公開
EXPOSE 8125/udp 8126/tcp

# Datadog コンフィギュレーションをコピー
COPY datadog-config/ /etc/datadog-agent/

CMD ["/entrypoint.sh"]

Docker コンテナのエントリポイントで Datadog Agent、Datadog APM Agent、Datadog プロセス Agentを起動させます。

#!/bin/bash

datadog-agent run &
/opt/datadog-agent/embedded/bin/trace-agent --config=/etc/datadog-agent/datadog.yaml &
/opt/datadog-agent/embedded/bin/process-agent --config=/etc/datadog-agent/datadog.yaml

Docker イメージのより高度なオプションについては、Datadog Agent の Docker ファイルを参照してください。

寄稿

Heroku-buildpack-datadog リポジトリで問題またはプルリクエストを投稿する方法については、寄稿ガイドラインを参照してください。

履歴

このプロジェクトの以前のバージョンは、miketheman heroku-buildpack-datadog プロジェクトから分岐したものです。その後、Datadog の Agent バージョン 6 向けに大幅な書き換えが行われました。変更内容と詳細は、changelog にあります。

トラブルシューティング

Agent ステータスの取得

ビルドパックをセットアップ済みで、期待するデータの一部を Datadog で取得していない場合、Datadog Agent にステータスコマンドを実行して原因を探ることができます。

# Heroku アプリケーション名を環境変数としてエクスポート
export APPNAME=your-application-name

heroku ps:exec -a $APPNAME

# 認証情報を確立中... 完了
#  ⬢ ruby-heroku-datadog で web.1 に接続中...
# DD_API_KEY 環境変数が設定されていません。実行: heroku config:add DD_API_KEY=<your API key>
# Datadog Agent が無効です。DISABLE_DATADOG_AGENT を未設定にするか、不足している環境変数を設定します。

~ $

DD_API_KEY が設定されていないという警告は無視できます。Heroku では SSH セッション自体のコンフィギュレーション変数は設定されませんが、Datadog Agent プロセスによりアクセス可能です。

SSH セッション内で Datadog ステータスコマンドを実行します。

~ $ agent-wrapper status

Getting the status from the agent.

===============
Agent (v7.27.0)
===============

[...]

デバッグ作業

Datadog にデータがない

status コマンドが正常に実行していることと、出力のこのセクションに、使用している API キーが有効であると表示されることを確認します。

  API Keys status
  ===============
    API key ending with 68306: API Key valid

インテグレーションのチェック

有効にしたインテグレーションが正常に実行されていることを確認するには、Collector セクションに注目し、チェックが正常に実行されていることを確認します。

=========
Collector
=========

  Running Checks
  ==============

[...]
    postgres (5.4.0)
    ----------------
      Instance ID: postgres:e07ef94b907fe733 [OK]
      Configuration Source: file:/app/.apt/etc/datadog-agent/conf.d/postgres.d/conf.yaml
      Total Runs: 4,282
      Metric Samples: Last Run: 15, Total: 64,230
      Events: Last Run: 0, Total: 0
      Service Checks: Last Run: 1, Total: 4,282
      Average Execution Time : 43ms
      Last Execution Date : 2021-05-13 08:15:46 UTC (1620893746000)
      Last Successful Execution Date : 2021-05-13 08:15:46 UTC (1620893746000)
      metadata:
        version.major: 13
        version.minor: 2
        version.patch: 0
        version.raw: 13.2 (Ubuntu 13.2-1.pgdg20.04+1)
        version.scheme: semver

APM Agent の確認

APM にアプリケーションをインスツルメントし、Datadog でトレースを取得していない場合は、APM Agent が正常に実行しトレースを収集していることを確認します。

[...]
=========
APM Agent
=========
  Status: Running
  Pid: 63
  Uptime: 64702 seconds
  Mem alloc: 10,331,128 bytes
  Hostname: ruby-heroku-datadog.web.1
  Receiver: localhost:8126
  Endpoints:
    https://trace.agent.datadoghq.com

  Receiver (previous minute)
  ==========================
    From ruby 2.6.6 (ruby-x86_64-linux), client 0.48.0
      Traces received: 11 (14,181 bytes)
      Spans received: 33

    Default priority sampling rate: 100.0%
    Priority sampling rate for 'service:ruby-heroku-datadog,env:': 100.0%
    Priority sampling rate for 'service:ruby-heroku-datadog,env:development': 100.0%

[...]

Datadog から報告される Agent 数が dynos 数を超えています

DD_DYNO_HOST が true に設定され、HEROKU_APP_NAME にすべての Heroku アプリケーションの値が設定されていることを確認してください。詳細は、ホスト名のセクションを参照してください。

ビルドパックまたは Agent をアップグレードした後、Agent が起動時にエラーをレポートしている

ビルドパックまたは Agent のアップグレード後は、アプリケーションのスラグを再コンパイルする必要があります。詳細については、アップグレードとスラグの再コンパイルのセクションを確認してください。