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 ビルドパックをプロジェクトに追加します:

cd <HEROKU_PROJECT_ROOT_FOLDER>

# 最新のメジャーバージョンの Agent を使用
heroku config:add DD_AGENT_MAJOR_VERSION=7

# Heroku Labs Dyno Metadata を有効にして HEROKU_APP_NAME 環境変数を自動的に設定
heroku labs:enable runtime-dyno-metadata -a $APPNAME

# メトリクスが連続するよう、Datadog でホスト名を appname.dynotype.dynonumber に設定
heroku config:add DD_DYNO_HOST=true

# このビルドパックを追加して Datadog API キーを設定
heroku buildpacks:add --index 1 https://github.com/DataDog/heroku-buildpack-datadog.git
heroku config:add DD_API_KEY=$DD_API_KEY

# 強制的に再構築して Heroku をデプロイ
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-<INTEGRATION_NAME> インテグレーションを有効にするには、アプリケーション内に Datadog のコンフィギュレーションフォルダーにファイルを作成します。dyno 起動時、この YAML ファイルは該当する Datadog Agent コンフィギュレーションディレクトリにコピーされます。

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

init_config:

instances:

    ## @param host - 文字列 - 必須
    ## 接続するホストを入力します。
    #
  - host: <REDIS_ホスト>

    ## @param port - 整数 - 必須
    ## 接続するホストのポートを入力します。
    #
    port: 6379

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

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

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

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

たとえば Ping インテグレーションをインストールするには、コンフィギュレーションファイル datadog/conf.d/ping.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

# Heroku アプリケーションの環境変数を使用して、Postgres のコンフィギュレーションを上記の設定から更新
if [ -n "$DATABASE_URL" ]; then
  POSTGREGEX='^postgres://([^:]+):([^@]+)@([^:]+):([^/]+)/(.*)$'
  if [[ $DATABASE_URL =~ $POSTGREGEX ]]; then
    sed -i "s/<YOUR HOSTNAME>/${BASH_REMATCH[3]}/" "$DD_CONF_DIR/conf.d/postgres.d/conf.yaml"
    sed -i "s/<YOUR USERNAME>/${BASH_REMATCH[1]}/" "$DD_CONF_DIR/conf.d/postgres.d/conf.yaml"
    sed -i "s/<YOUR PASSWORD>/${BASH_REMATCH[2]}/" "$DD_CONF_DIR/conf.d/postgres.d/conf.yaml"
    sed -i "s/<YOUR PORT>/${BASH_REMATCH[4]}/" "$DD_CONF_DIR/conf.d/postgres.d/conf.yaml"
    sed -i "s/<YOUR DBNAME>/${BASH_REMATCH[5]}/" "$DD_CONF_DIR/conf.d/postgres.d/conf.yaml"
  fi
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 のアップグレード後は、アプリケーションのスラグを再コンパイルする必要があります。詳細については、アップグレードとスラグの再コンパイルのセクションを確認してください。