Datadog Heroku ビルドパック

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

インストール

このビルドパックをプロジェクトに追加し、かつ必要な環境変数を設定するには、以下を参照してください。

cd <HEROKU_プロジェクトルートフォルダー>

# これが新しい Heroku プロジェクトの場合
heroku create

# 適切な言語固有のビルドパックを追加します。例:
heroku buildpacks:add heroku/ruby

# Heroku Labs Dyno メタデータを有効にします
heroku labs:enable runtime-dyno-metadata -a $(heroku apps:info|grep ===|cut -d' ' -f2)

# このビルドパックを追加して、Datadog API キーを設定します
heroku buildpacks:add https://github.com/DataDog/heroku-buildpack-datadog.git#<DATADOG_ビルドパックリリース>
heroku config:add DD_API_KEY=<DATADOG_API_キー>

# Heroku にデプロイします
git push heroku master

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

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

<DATADOG_API_キー> は、現在の Datadog API キーに置き換えてください。 また、<DATADOG_ビルドパックリリース> は、使用するビルドパックのリリースに置き換えてください。

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

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

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

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

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

• DD_AGENT_VERSION
• DD_AGENT_MAJOR_VERSION
• DD_PYTHON_VERSION
• DD_APM_ENABLED
• DD_PROCESS_AGENT

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

# Heroku リポジトリプラグインをインストールします
heroku plugins:install heroku-repo

# Agent の新しいバージョンを設定します
heroku config:set DD_AGENT_VERSION=<新しい_AGENT_バージョン> -a appname

# "appname" アプリケーションの Heroku のビルドキャッシュをクリアします
heroku repo:purge_cache -a appname

# 新しい Agent バージョンでスラグを再構築します:
git commit --allow-empty -m "Purge cache"
git push heroku master

コンフィギュレーション

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

その他のドキュメントについては、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 を実行しているホストマシンのシステムメトリクスを収集します。システムメトリクスは、このビルドパックを使用している個別の 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-<インテグレーション名> インテグレーションを有効にするには、アプリケーションのルートにファイル /datadog/conf.d/<インテグレーション名>.yaml を作成します。dyno の起動中に、YAML ファイルが適切な Datadog Agent 構成ディレクトリにコピーされます。

たとえば、Datadog-Redis インテグレーションを有効にするには、アプリケーションのルートにファイル /datadog/conf.d/redisdb.yaml を作成します。

init_config:

instances:

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

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

注: 使用可能なすべての構成オプションの詳細については、サンプル redisdb.d/conf.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

# 以下に基づきアプリのバージョンを設定 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

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 のドキュメントにリストされている情報/デバッグコマンドのいずれかを実行するには、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 7 に移行することをお勧めします。6.15 以降、同じマイナーバージョンの v7 リリースは同じ機能セットを共有するため、これら 2 つの間を安全に移動できます。たとえば、6.16 を実行していて、Python バージョン 2 が必要ない場合、7.16 にジャンプしても安全です。

Heroku ログの収集

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

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

このビルドパックは、Heroku の Slug Compiler を使用する Heroku のデプロイメントにのみ利用できます。Docker コンテナを使用して Heroku にアプリケーションをデプロイするには、 Datadog Agent を Docker イメージの一部として追加し、Agent をコンテナ内の異なるプロセスとして起動する必要があります。

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

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

# Datadog レポジトリと署名キーを追加
RUN sh -c "echo 'deb https://apt.datadoghq.com/ stable 7' > /etc/apt/sources.list.d/datadog.list"
RUN apt-key adv --recv-keys --keyserver hkp://keyserver.ubuntu.com:80 A2923DFF56EDA6E76E55E492D3A80E30382E94DE

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

# entrypoint をコピー
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 にあります。

FAQ/トラブルシューティング

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

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

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

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