Datadog Heroku Buildpack

Heroku 빌드팩을 사용해 Heroku dyno에 Datadog 에이전트를 설치하고 시스템 메트릭, 커스텀 애플리케이션 메트릭, 트레이스를 수집해요.

출처: 문서

본문

이 Heroku 빌드팩은 Heroku dyno에 Datadog 에이전트를 설치해 시스템 메트릭, 커스텀 애플리케이션 메트릭, 트레이스를 수집해요. 커스텀 애플리케이션 메트릭이나 트레이스를 수집하려면 애플리케이션에 언어에 맞는 DogStatsD 또는 Datadog APM 라이브러리를 포함하세요.

설치

Fleet Automation의 인앱 설치 가이드를 따라 Heroku에 Datadog 에이전트를 설치하세요.

이 가이드는 이미 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=<YOUR_DATADOG_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 -a $APPNAME
   
   # Set the DD_SITE env variable automatically
   heroku config:add DD_SITE=$DD_SITE -a $APPNAME
   
   # Add this buildpack and set your Datadog API key
   heroku buildpacks:add --index 1 https://github.com/DataDog/heroku-buildpack-datadog.git -a $APPNAME
   heroku config:add DD_API_KEY=$DD_API_KEY -a $APPNAME
   
   # Deploy to Heroku forcing a rebuild
   git commit --allow-empty -m "Rebuild slug"
   git push heroku main
   

완료되면 각 dyno가 시작될 때 Datadog 에이전트가 자동으로 시작돼요.

Datadog 에이전트는 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 에이전트 버전 고정

Heroku는 항상 빌드팩의 최신 커밋을 사용할 것을 권장해요. 빌드팩 버전을 고정해야 한다면 빌드팩 릴리스 태그를 지정하면 돼요.

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

<DATADOG_BUILDPACK_RELEASE>를 사용하려는 빌드팩 릴리스로 바꾸세요.

기본적으로 빌드팩은 릴리스 시점의 최신 Datadog 에이전트 버전을 고정해요. DD_AGENT_VERSION 환경 변수를 설정해 에이전트를 이전 버전으로 고정할 수 있어요.

업그레이드와 slug 재컴파일

이 빌드팩을 업그레이드하거나 일부 빌드팩 옵션을 수정하려면 slug를 재컴파일해야 해요.

다음 옵션은 slug 재컴파일이 필요해요.

• DD_AGENT_VERSION
• DD_AGENT_MAJOR_VERSION
• DD_PYTHON_VERSION
• DD_APM_ENABLED
• DD_PROCESS_AGENT

이 빌드팩을 업그레이드하거나/또는 DD_AGENT_VERSION 같은 옵션을 변경하려면 다음 단계가 필요해요.

# Set new version of the Agent
heroku config:set DD_AGENT_VERSION=<NEW_AGENT_VERSION> -a <YOUR_APP_NAME>

# Rebuild your slug with the new Agent version:
git commit --allow-empty -m "Rebuild slug"
git push heroku main

구성

위에서 본 환경 변수 외에도 설정할 수 있는 다른 변수가 여러 개 있어요.

설정	설명
DD_API_KEY	필수. API 키는 Organization Settings -> API Keys 페이지에서 확인할 수 있어요. 참고: 이는 API 키이며 애플리케이션 키가 아니에요.
DD_HOSTNAME	선택. 경고: 호스트 이름을 수동으로 설정하면 메트릭 연속성 오류가 발생할 수 있어요. 이 변수는 설정하지 않는 것이 좋아요. dyno 호스트는 임시적이므로 dynoname 또는 appname 태그를 기준으로 모니터링하는 것이 좋아요.
DD_DYNO_HOST	선택. true로 설정하면 호스트 이름으로 dyno 이름(예: web.1 또는 run.1234)을 사용해요. 아래 호스트 이름 섹션 참고. 기본값은 false.
DD_TAGS	선택. 공백으로 구분된 문자열로 추가 태그를 설정해요(참고: 빌드팩 버전 1.16 이하에서는 쉼표 구분 문자열; 하위 호환을 위해 여전히 지원됨). 예: heroku config:set DD_TAGS="simple-tag-0 tag-key-1:tag-value-1". 빌드팩은 dyno 이름(예: web.1)을 나타내는 dyno 태그와 dynotype(dyno 유형, 예: run 또는 web)을 자동으로 추가해요. 태깅 가이드 참고.
DD_VERSION	선택. 트레이스를 버전별로 구성하는 데 사용되는 애플리케이션 버전을 설정해요.
DD_HISTOGRAM_PERCENTILES	선택. 히스토그램 메트릭에 추가 백분위수를 선택적으로 설정해요. 백분위수 그래프 참고.
DISABLE_DATADOG_AGENT	선택. 설정하면 Datadog 에이전트가 실행되지 않아요.
DD_APM_ENABLED	선택. 트레이스 수집은 기본적으로 활성화돼요. 트레이스 수집을 비활성화하려면 false로 설정하세요. 이 옵션 변경은 slug 재컴파일이 필요해요. 업그레이드와 slug 재컴파일 섹션 참고.
DD_PROCESS_AGENT	선택. Datadog 프로세스 에이전트는 기본적으로 비활성화돼요. 프로세스 에이전트를 활성화하려면 true로 설정하세요. 이 옵션 변경은 slug 재컴파일이 필요해요. 업그레이드와 slug 재컴파일 섹션 참고.
DD_SITE	선택. app.datadoghq.eu 서비스를 사용한다면 datadoghq.eu로 설정하세요. 기본값은 datadoghq.com.
DD_AGENT_VERSION	선택. 기본적으로 빌드팩은 패키지 저장소에서 사용 가능한 최신 6.x Datadog 에이전트 버전을 설치해요. 이 변수를 사용해 이전 버전의 Datadog 에이전트를 설치하세요. 참고: 모든 에이전트 버전이 사용 가능한 것은 아닐 수 있어요. 이 옵션은 DD_AGENT_MAJOR_VERSION보다 우선해요. 이 옵션 변경은 slug 재컴파일이 필요해요. 업그레이드와 slug 재컴파일 참고.
DD_AGENT_MAJOR_VERSION	선택. 기본적으로 빌드팩은 패키지 저장소에서 사용 가능한 최신 7.x Datadog 에이전트 버전을 설치해요. 이 변수를 6으로 설정하면 최신 6.x Datadog 에이전트 버전을 설치해요. 에이전트 버전과 Python 버전의 관계는 Python 버전 섹션 참고. 이 옵션 변경은 slug 재컴파일이 필요해요. 업그레이드와 slug 재컴파일 참고.
DD_DISABLE_HOST_METRICS	선택. 기본적으로 빌드팩은 dyno를 실행하는 호스트 머신의 시스템 메트릭을 보고해요. 시스템 메트릭 수집을 비활성화하려면 true로 설정하세요. 아래 시스템 메트릭 섹션 참고.
DD_PYTHON_VERSION	선택. 버전 6.14.0부터 Datadog 에이전트는 Python 2와 3 버전과 함께 제공돼요. 빌드팩은 한 버전만 유지해요. 에이전트가 유지할 Python 버전을 선택하려면 2 또는 3으로 설정하세요. 설정하지 않으면 빌드팩은 2를 유지해요. Python 버전 섹션 참고. 이 옵션 변경은 slug 재컴파일이 필요해요. 업그레이드와 slug 재컴파일 섹션 참고.
DD_HEROKU_CONF_FOLDER	선택. 기본적으로 빌드팩은 애플리케이션 루트에서 포함할 구성 파일용 /datadog 폴더를 찾아요(prerun.sh 스크립트 참고). 이 변수에 원하는 경로를 설정해 이 위치를 덮어쓸 수 있어요.
DD_ENABLE_HEROKU_REDIS	선택. Redis 통합 자동 검색을 활성화하려면 true로 설정하세요. Datadog Redis 통합 활성화 섹션 참고.
DD_REDIS_URL_VAR	선택. 기본적으로 Redis 통합 자동 검색은 REDIS_URL에 저장된 연결 문자열을 사용해요. 이를 덮어쓰려면 이 변수를 연결 문자열을 저장하는 변수 이름의 쉼표 구분 목록으로 설정하세요. Datadog Redis 통합 활성화 섹션 참고.
DD_ENABLE_HEROKU_POSTGRES	선택. Postgres 통합 자동 검색을 활성화하려면 true로 설정하세요. Datadog Postgres 통합 활성화 섹션 참고.
DD_POSTGRES_URL_VAR	선택. 기본적으로 Postgres 통합 자동 검색은 DATABASE_URL에 저장된 연결 문자열을 사용해요. 이를 덮어쓰려면 이 변수를 연결 문자열을 저장하는 변수 이름의 쉼표 구분 목록으로 설정하세요. Datadog Postgres 통합 활성화 섹션 참고.
DD_ENABLE_DBM	선택. 이 가이드를 따라 Datadog Postgres 통합을 활성화한다면 Database Monitoring을 활성화하려면 DD_ENABLE_DBM을 true로 설정하세요.

추가 문서는 Datadog 에이전트 문서를 참고하세요.

호스트 이름

Heroku dyno는 임시적이에요. 새 코드가 배포되거나, 구성 변경이 있거나, 리소스 필요/가용성이 바뀌면 다른 호스트 머신으로 이동할 수 있어요. 이로 인해 Heroku는 유연하고 반응성이 좋지만 Datadog에 보고되는 호스트 수가 높아질 수 있어요. Datadog는 호스트당 과금하며, 빌드팩 기본값은 실제 호스트를 보고하므로 예상보다 높은 비용이 발생할 수 있어요.

사용 사례에 따라 호스트 이름을 설정해 호스트를 통합하고 더 적은 수로 보고하고 싶을 수 있어요. 그러려면 DD_DYNO_HOST를 true로 설정하세요. 그러면 에이전트는 호스트 이름을 앱·dyno 이름(예: appname.web.1 또는 appname.run.1234)으로 보고하고 호스트 수가 dyno 사용량과 거의 일치해요. 단점은 dyno가 순환될 때 메트릭 연속성 오류가 발생할 수 있다는 점이에요.

이것이 올바르게 작동하려면 HEROKU_APP_NAME이 설정되어야 해요. 가장 쉬운 방법은 dyno 메타데이터 활성화예요. 참고: dyno 메타데이터는 Private Spaces에서는 아직 사용할 수 없으며, 그 경우 HEROKU_APP_NAME을 수동으로 설정해야 해요.

단기 dyno에서 Datadog 에이전트 비활성화

기본적으로 Datadog 에이전트는 애플리케이션의 일부인 각 dyno에서 실행돼요. 여기에는 scheduler, release, run dyno가 포함돼요. 많은 경우 이 dyno들의 메트릭은 필요하지 않으므로 이들에 대해 Datadog 에이전트를 비활성화하는 게 합리적이에요.

dyno 유형에 따라 Datadog 에이전트를 비활성화하려면 prerun.sh 스크립트에 다음 스니펫을 추가하세요(모니터링하지 않으려는 dyno 유형에 맞게 조정).

DYNOTYPE=${DYNO%%.*}
# Disable the Datadog Agent based on dyno type
if [[ "$DYNOTYPE" == "run" || "$DYNOTYPE" == "scheduler" || "$DYNOTYPE" == "release" || "$DYNOTYPE" == advanced-scheduler* ]]; 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 에이전트는 /app/.apt/opt/datadog-agent에 설치돼요.
• Datadog 에이전트 구성 파일은 /app/.apt/etc/datadog-agent에 있어요.
• Datadog 에이전트 로그는 /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이 다른 환경 변수에 정의되어 있거나 1개 이상의 Redis 인스턴스를 구성하려면 DD_REDIS_URL_VAR 환경 변수를 연결 문자열의 변수 이름들로 쉼표 구분해 설정하세요. 예를 들어 Heroku Redis와 Redis Enterprise Cloud를 모두 사용한다면 DD_REDIS_URL_VAR를 그에 맞게 설정하세요.

heroku config:set REDIS_URL="redis://aaaaa:***@redis-url"
heroku config:set REDISCLOUD_URL="redis://xxxxx:***@redis-cloud-url"

# This env var must point to other env vars.
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이 다른 환경 변수에 정의되어 있거나 1개 이상의 Postgres 인스턴스를 구성하려면 DD_POSTGRES_URL_VAR 환경 변수를 연결 문자열의 변수 이름들로 쉼표 구분해 설정하세요. 예를 들어 Postgres 인스턴스가 2개이고 연결 문자열이 POSTGRES_URL1과 POSTGRES_URL2에 저장되어 있다면 DD_POSTGRES_URL_VAR를 그에 맞게 설정하세요.

heroku config:set POSTGRES_URL1="postgres://aaaaa:***@postgres-url-1:5432/dbname"
heroku config:set POSTGRES_URL2="postgres://xxxxx:***@postgres-url-2:5432/dbname"

# This env var must point to other env vars.
heroku config:set DD_POSTGRES_URL_VAR=POSTGRES_URL1,POSTGRES_URL2

Postgres 인스턴스에 대해 Database Monitoring을 활성화하려면 이 지침에 따라 에이전트에 데이터베이스 접근 권한을 부여하고 DD_ENABLE_DBM을 true로 설정하세요.

heroku config:set DD_ENABLE_DBM=true

Database Monitoring은 Datadog 에이전트용 데이터베이스 자격 증명을 만들어야 하므로 DBM은 Heroku Postgres Essential Tier 플랜에서 사용할 수 없어요.

DogStatsD Mapper 프로필 활성화(Sidekiq)

Sidekiq 같은 일부 통합은 DogStatsD Mapper 프로필이 필요해요.

새 DogStatsD Mapper 프로필을 추가하려면 prerun.sh 스크립트에 다음 스니펫을 추가하세요.

cat << 'EOF' >> "$DATADOG_CONF"

dogstatsd_mapper_profiles:
  - name: '<PROFILE_NAME>'
    prefix: '<PROFILE_PREFIX>'
    mappings:
      - match: '<METRIC_TO_MATCH>'
        match_type: '<MATCH_TYPE>'
        name: '<MAPPED_METRIC_NAME>'
        tags:
          '<TAG_KEY>': '<TAG_VALUE_TO_EXPAND>'
EOF

예를 들어 Sidekiq 통합을 활성화하려면 다음 스니펫을 추가하세요.

cat << 'EOF' >> "$DATADOG_CONF"

dogstatsd_mapper_profiles:
  - name: sidekiq
    prefix: "sidekiq."
    mappings:
      - match: 'sidekiq\.sidekiq\.(.*)'
        match_type: "regex"
        name: "sidekiq.$1"
      - match: 'sidekiq\.jobs\.(.*)\.perform'
        name: "sidekiq.jobs.perform"
        match_type: "regex"
        tags:
          worker: "$1"
      - match: 'sidekiq\.jobs\.(.*)\.(count|success|failure)'
        name: "sidekiq.jobs.worker.$2"
        match_type: "regex"
        tags:
          worker: "$1"
EOF

다른 통합 활성화

Datadog-<INTEGRATION_NAME> 통합을 활성화하려면:

• 애플리케이션 내에 datadog/conf.d 폴더를 만들세요.
• 활성화할 각 통합에 대해 <INTEGRATION_NAME>.d 폴더를 만드세요.
• 그 폴더 아래에 통합 구성이 있는 conf.yaml을 만드세요.

dyno 시작 동안 YAML 파일이 적절한 Datadog 에이전트 구성 디렉터리에 복사돼요.

예를 들어 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을 참고하세요.

prerun.sh 스크립트로 통합 구성 동적 변경

환경 변수에 구성 세부 정보(데이터베이스 구성 또는 비밀 같은)가 저장되어 있다면 prerun.sh 스크립트를 사용해 에이전트 시작 전에 이를 Datadog 에이전트 구성에 동적으로 추가할 수 있어요.

예를 들어 Postgres 통합을 활성화하려면 애플리케이션 루트(이 구성 옵션을 변경했다면 /$DD_HEROKU_CONF_FOLDER/conf.d/postgres.d/conf.yaml)에 자리 표시자가 있는 datadog/conf.d/postgres.d/conf.yaml 파일을 추가할 수 있어요.

init_config:

instances:
  - host: <YOUR HOSTNAME>
    port: <YOUR PORT>
    username: <YOUR USERNAME>
    password: <YOUR PASSWORD>
    dbname: <YOUR DBNAME>
    ssl: True

그리고 prerun.sh 스크립트를 사용해 환경 변수의 실제 값으로 자리 표시자를 바꾸세요.

# Update the Postgres configuration from above using the Heroku application environment variable
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

커뮤니티 통합

활성화하려는 통합이 커뮤니티 통합의 일부라면 prerun 스크립트의 일부로 패키지를 설치하세요.

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

예를 들어 ping 통합을 설치하려면 구성 파일 datadog/conf.d/ping.d/conf.yaml을 만들고 prerun 스크립트에 다음 줄을 추가하세요.

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

dyno 기준 통합 비활성화

Heroku 애플리케이션의 파일 시스템은 모든 dyno가 공유하므로, 통합을 활성화하면 run이나 worker dyno를 포함해 모든 dyno에서 실행돼요. 통합 실행을 dyno 이름이나 유형에 따라 제한하려면 prerun 스크립트에 작은 스니펫을 추가하면 돼요.

예를 들어 Gunicorn 통합이 web 유형 dyno에서만 실행되어야 한다면 prerun 스크립트에 다음을 추가하세요.

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

커스텀 체크 활성화

자체 에이전트 커스텀 체크를 활성화하려면 애플리케이션의 datadog 구성 폴더에 checks.d 폴더를 만들고 그 아래 커스텀 체크의 모든 .py와 .yaml 파일을 복사하세요. dyno 시작 동안 파일이 적절한 Datadog 에이전트 구성 디렉터리에 복사돼요.

예를 들어 foo와 bar 두 개의 커스텀 체크가 있다면 올바른 폴더 트리는 다음과 같아요.

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

Prerun 스크립트

위의 모든 구성에 더해 애플리케이션에 prerun 스크립트 /datadog/prerun.sh를 포함할 수 있어요. prerun 스크립트는 모든 표준 구성 작업 후, Datadog 에이전트를 시작하기 직전에 실행돼요. 이를 통해 환경 변수(예: DD_TAGS 또는 DD_VERSION)를 수정하고, 추가 구성을 수행하고, 커뮤니티 통합을 설치하거나, Datadog 에이전트를 프로그램 방식으로 비활성화할 수 있어요.

아래 예제는 prerun.sh 스크립트에서 할 수 있는 몇 가지를 보여 줘요.

#!/usr/bin/env bash

# Extract dyno type from Heroku's '$DYNO' environment variable
DYNOTYPE="${DYNO%%.*}"

# Disable the Datadog Agent based on dyno type
if [ "$DYNOTYPE" == "run" ]; then
  DISABLE_DATADOG_AGENT="true"
fi

# Disable integrations based on dyno type
if [ "$DYNOTYPE" != "web" ]; then
  rm -f "$DD_CONF_DIR/conf.d/gunicorn.d/conf.yaml"
fi

# Set app version based on HEROKU_SLUG_COMMIT
if [ -n "$HEROKU_SLUG_COMMIT" ]; then
  DD_VERSION=$HEROKU_SLUG_COMMIT
fi

# Install the "ping" community integration
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

선택적 바이너리

slug 공간을 절약하기 위해 DD_APM_ENABLED가 false로 설정되고/또는 DD_PROCESS_AGENT가 설정되지 않거나 false로 설정되면 컴파일 중 trace-agent와 process-agent 선택적 바이너리가 제거돼요.

slug 크기를 줄이려면 APM 기능을 사용하지 않는다면 DD_APM_ENABLED가 false로 설정되어 있고, 프로세스 모니터링을 사용하지 않는다면 DD_PROCESS_AGENT가 true로 설정되지 않았는지 확인하세요.

디버깅

정보 또는 디버깅 명령을 실행하려면 agent-wrapper 명령을 사용하세요.

예를 들어 Datadog 에이전트와 활성화된 통합의 상태를 표시하려면 다음을 실행하세요.

agent-wrapper status

Python과 에이전트 버전

버전 6.14 이전에는 Datadog v6 에이전트가 Python 2 버전을 임베디드로 함께 제공했어요. 6.14부터는 2020년 1월로 발표된 Python 2 End Of Life에 대비해 Datadog v6 에이전트가 Python 2와 3 버전을 모두 제공해 고객이 커스텀 체크를 Python 3으로 마이그레이션할 시간을 줬어요. Heroku 빌드팩은 한 버전만 유지해요. 에이전트가 유지할 Python 버전을 선택하려면 DD_PYTHON_VERSION을 2 또는 3으로 설정하세요. 설정하지 않으면 빌드팩은 Python 2를 유지해요. Python 2에서만 작동하는 커스텀 체크를 사용한다면 EOL 전에 버전 3으로 마이그레이션하세요.

에이전트 v7은 Python 3 버전만 제공해요. 커스텀 체크를 사용하지 않거나 커스텀 체크가 이미 버전 3으로 마이그레이션됐다면 가능한 한 빨리 에이전트 v7로 이동하세요. 6.15부터 동일한 마이너 버전의 v7 릴리스는 동일한 기능 세트를 공유하므로 둘 사이 이동이 안전해요. 예를 들어 6.16을 실행 중이고 Python 2가 필요 없다면 7.16으로 점프하는 게 안전해요.

Heroku 로그 수집

Datadog 빌드팩은 Heroku 플랫폼에서 로그를 수집하지 않아요. Heroku 로그 수집을 설정하려면 전용 가이드를 참고하세요.

Docker 이미지와 Heroku 사용

이 빌드팩은 Heroku Slug 컴파일러를 사용하는 Heroku 배포에서만 작동해요. Docker 컨테이너로 Heroku에서 애플리케이션을 배포한다면:

1. Docker 이미지의 일부로 Datadog 에이전트를 추가하고 컨테이너의 별도 프로세스로 에이전트를 시작하세요.
2. Datadog가 이를 Heroku dyno로 올바르게 보고하도록 Heroku 애플리케이션에 다음 구성 옵션을 설정하세요.

heroku config:add DD_HEROKU_DYNO=true

예를 들어 Debian 기반 OS로 Docker 이미지를 빌드한다면 Dockerfile에 다음 줄을 추가하세요.

# Install GPG dependencies
RUN apt-get update \
 && apt-get install -y gnupg apt-transport-https gpg-agent curl ca-certificates

# Add Datadog repository and signing keys
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_06462314.public "${DATADOG_APT_KEYS_URL}/DATADOG_APT_KEY_06462314.public" && \
    gpg --ignore-time-conflict --no-default-keyring --keyring ${DATADOG_APT_KEYRING} --import /tmp/DATADOG_APT_KEY_06462314.public
RUN curl -o /tmp/DATADOG_APT_KEY_C0962C7D.public "${DATADOG_APT_KEYS_URL}/DATADOG_APT_KEY_C0962C7D.public" && \
    gpg --ignore-time-conflict --no-default-keyring --keyring ${DATADOG_APT_KEYRING} --import /tmp/DATADOG_APT_KEY_C0962C7D.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


# Install the Datadog Agent
RUN apt-get update && apt-get -y --force-yes install --reinstall datadog-agent

# Copy entrypoint
COPY entrypoint.sh /

# Expose DogStatsD and trace-agent ports
EXPOSE 8125/udp 8126/tcp

# Copy your Datadog configuration
COPY datadog-config/ /etc/datadog-agent/

CMD ["/entrypoint.sh"]

Docker 컨테이너 엔트리 포인트에서 Datadog 에이전트, Datadog APM 에이전트, Datadog 프로세스 에이전트를 시작하세요.

#!/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 에이전트 Docker 파일을 참고하세요.

기여

기여 가이드라인을 참고해 Heroku-buildpack-datadog 저장소에 이슈나 PR을 여는 방법을 알아보세요.

기록

이 프로젝트의 이전 버전은 miketheman heroku-buildpack-datadog 프로젝트에서 포크됐어요. Datadog 에이전트 버전 6용으로 크게 다시 작성됐어요. 변경 사항과 더 많은 정보는 changelog에서 찾을 수 있어요.

트러블슈팅

에이전트 상태 가져오기

빌드팩을 설정했는데 Datadog에서 예상하는 일부 데이터를 얻지 못한다면 Datadog 에이전트에 대해 상태 명령을 실행해 원인을 찾을 수 있어요.

# Export the name of your Heroku application as an environment variable
export APPNAME=your-application-name

heroku ps:exec -a $APPNAME

# Establishing credentials... done
# Connecting to web.1 on ⬢ ruby-heroku-datadog...
# DD_API_KEY environment variable not set. Run: heroku config:add DD_API_KEY=<your API key>
# The Datadog Agent has been disabled. Unset the DISABLE_DATADOG_AGENT or set missing environment variables.

~ $

DD_API_KEY가 설정되지 않았다는 경고는 무시해도 돼요. Heroku는 SSH 세션 자체에 대한 구성 변수를 설정하지 않지만, Datadog 에이전트 프로세스는 이를 접근할 수 있어요.

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 에이전트 확인

APM용으로 애플리케이션을 계측했는데 Datadog에서 트레이스를 얻지 못한다면, APM 에이전트가 올바르게 실행되고 트레이스를 수집하는지 확인할 수 있어요.

[...]
=========
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이 dyno보다 많은 수의 에이전트를 보고함

DD_DYNO_HOST가 true로 설정되어 있고 모든 Heroku 애플리케이션에 대해 HEROKU_APP_NAME에 값이 있는지 확인하세요. 자세한 내용은 호스트 이름 섹션을 참고하세요.

빌드팩이나 에이전트 업그레이드 후 에이전트가 시작 시 오류를 보고함

빌드팩이나 에이전트를 업그레이드한 후 애플리케이션의 slug를 재컴파일해야 해요. 자세한 내용은 업그레이드와 slug 재컴파일 섹션을 참고하세요.