選択したサイト () では現在 CI Visibility は利用できません。

Ruby のテストインスツルメンテーションはベータ版です。

互換性

サポートされている Ruby インタープリター:

  • Ruby >= 2.1
  • JRuby >= 9.2

サポートされているテストフレームワーク:

  • Cucumber >= 3.0
  • RSpec >= 3.0.0

Datadog Agent をインストールする

Datadog にテスト結果を報告するには、Datadog Agent をインストールする必要があります。

オンプレミスの CI プロバイダーを使用する

Jenkins や自己管理型の GitLab CI などのオンプレミスの CI プロバイダー上でテストを実行している場合は、Agent のインストール手順に従って各ワーカーノードに Datadog Agent をインストールします。

CI プロバイダーがコンテナベースのエグゼキューターを使用している場合は、ビルド内の localhost の使用で Datadog Agent が実行されている基底のワーカーノードではなく、コンテナ自体を参照するため、すべてのビルド (デフォルトは http://localhost:8126) の DD_AGENT_HOST 環境変数をビルドコンテナ内からアクセス可能なエンドポイントに設定します。

Kubernetes エグゼキューターを使用している場合、Datadog は Datadog Admission Controller を使用することをお勧めします。これにより、ビルドポッドの DD_AGENT_HOST 環境変数が自動的に設定されてローカルの Datadog Agent と通信します。

クラウドの CI プロバイダーを使用する

GitHub Actions や CircleCI など、基底のワーカーノードにアクセスできないクラウドの CI プロバイダーを使用している場合は、コンテナ内の Datadog Agent をビルドサービスとして実行します。このメソッドは、各ワーカーノードへの Datadog Agent のインストールというオプションがない場合に、コンテナベースのエグゼキューターを使用するオンプレミス CI プロバイダーでも使用できます。

単純な結果フォワーダーとして機能するコンテナとして Datadog Agent を実行するには、Docker イメージ gcr.io/datadoghq/agent:latest と次の環境変数を使用します。

DD_API_KEY (必須)
テスト結果のアップロードに使用される Datadog API キー
デフォルト: (なし)
DD_INSIDE_CI (必須)
基底のホストにアクセスできないため、Datadog Agent コンテナの監視を無効にします。
デフォルト: false
必要な値: true
DD_HOSTNAME (必須)
基底のホストを監視できないため、テストに関連付けられたホスト名のレポートを無効にします。
デフォルト: (自動検出)
必要な値: none

さらに、選択したサイトを使用するように Datadog サイトを構成します ():

DD_SITE
結果をアップロードする Datadog サイト。
デフォルト: datadoghq.com
選択したサイト:

CI プロバイダーのコンフィギュレーション例

次のセクションでは、Agent を実行し、テスト情報を報告するよう構成するために必要となる CI プロバイダー固有の手順をご説明します。

Azure Pipelines で Datadog Agent を実行するには、リソースセクションで新しいコンテナを定義し、それを サービスコンテナとして宣言しているジョブと関連付けます。

azure-pipeline.yml

variables:
  ddApiKey: $(DD_API_KEY)

resources:
  containers:
    - container: dd_agent
      image: gcr.io/datadoghq/agent:latest
      ports:
        - 8126:8126
      env:
        DD_API_KEY: $(ddApiKey)
        DD_INSIDE_CI: "true"
        DD_HOSTNAME: "none"

jobs:
  - job: test
    services:
      dd_agent: dd_agent
    steps:
      - script: make test

<DD_SITE> を選択したサイトに置き換えます:

azure-pipeline.yml

variables:
  ddApiKey: $(DD_API_KEY)

resources:
  containers:
    - container: dd_agent
      image: gcr.io/datadoghq/agent:latest
      ports:
        - 8126:8126
      env:
        DD_API_KEY: $(ddApiKey)
        DD_INSIDE_CI: "true"
        DD_HOSTNAME: "none"
        DD_SITE: "<DD_SITE>"

jobs:
  - job: test
    services:
      dd_agent: dd_agent
    steps:
      - script: make test

Datadog API キーを、キー DD_API_KEY と合わせてプロジェクト環境変数に追加します。

GitLab で Agent を実行するには、 サービス下で Agent コンテナを定義します。

.gitlab-ci.yml

variables:
  DD_API_KEY: $DD_API_KEY
  DD_INSIDE_CI: "true"
  DD_HOSTNAME: "none"
  DD_AGENT_HOST: "datadog-agent"

test:
  services:
    - name: gcr.io/datadoghq/agent:latest
  script:
    - make test

<DD_SITE> を選択したサイトに置き換えます:

.gitlab-ci.yml

variables:
  DD_API_KEY: $DD_API_KEY
  DD_INSIDE_CI: "true"
  DD_HOSTNAME: "none"
  DD_AGENT_HOST: "datadog-agent"
  DD_SITE: "<DD_SITE>"

test:
  services:
    - name: gcr.io/datadoghq/agent:latest
  script:
    - make test

Datadog API キーを、キー DD_API_KEY と合わせてプロジェクト環境変数に追加します。

GitHub Actions で Agent を実行するには、Datadog Agent GitHub Action datadog/agent-github-action を使用します。

jobs:
  test:
    steps:
      - name: Start the Datadog Agent locally
        uses: datadog/agent-github-action@v1
        with:
          api_key: ${{ secrets.DD_API_KEY }}
      - run: make test

<datadog_site> を選択したサイトに置き換えます:

jobs:
  test:
    steps:
      - name: Start the Datadog Agent locally
        uses: datadog/agent-github-action@v1
        with:
          api_key: ${{ secrets.DD_API_KEY }}
          datadog_site: <datadog_site>
      - run: make test

Datadog API キーを、キー DD_API_KEY と合わせてプロジェクト環境変数に追加します。

CircleCI で Agent を実行するには、テストを実行する前に datadog/agent CircleCI orb を使用して Agent コンテナを起動し、結果が Datadog に送信されたことを確認してから停止します。

.circleci/config.yml

version: 2.1

orbs:
  datadog-agent: datadog/agent@0

jobs:
  test:
    docker:
      - image: circleci/<language>:<version_tag>
    steps:
      - checkout
      - datadog-agent/setup
      - run: make test
      - datadog-agent/stop

workflows:
  test:
    jobs:
      - test

<DD_SITE> を選択したサイトに置き換えます:

.circleci/config.yml

version: 2.1

orbs:
  datadog-agent: datadog/agent@0

jobs:
  test:
    docker:
      - image: circleci/<language>:<version_tag>
    environment:
      DD_SITE: "<DD_SITE>"
    steps:
      - checkout
      - datadog-agent/setup
      - run: make test
      - datadog-agent/stop

workflows:
  test:
    jobs:
      - test

Datadog API キーを、キー DD_API_KEY と合わせてプロジェクト環境変数に追加します。

Ruby トレーサーのインストール

Ruby トレーサーをインストールするには

  1. ddtrace gem を Gemfile に追加します。

    Gemfile

    ソース 'https://rubygems.org'
    gem 'ddtrace', "~> 1.0"
  2. bundle install を実行して gem をインストールします

詳細については、Ruby トレーサーのインストールドキュメントを参照してください。

テストのインスツルメンテーション

Cucumber インテグレーションでは、cucumber フレームワークを使用している場合のシナリオとステップの実行をトレースすることができます。

インテグレーションをアクティブ化するには、次のコードをアプリケーションに追加します。

require 'cucumber'
require 'datadog/ci'

Datadog.configure do |c|
  # CI でのみテストインスツルメンテーションをアクティブ化します
  c.tracing.enabled = (ENV["DD_ENV"] == "ci")

  # 結果が確実に配信されるようにトレーサーを構成します
  c.ci.enabled = true

  # テスト中のサービスまたはライブラリの名前
  c.service = 'my-ruby-app'

  # Cucumber のインスツルメンテーションを有効にします
  c.ci.instrument :cucumber
end

DD_ENV 環境変数でテストを実行する環境 (たとえば、開発者ワークステーションでテストを実行する場合は local、CI プロバイダーでテストを実行する場合は ci) を指定して、通常どおりにテストを実行します。例:

DD_ENV=ci bundle exec rake cucumber

RSpec インテグレーションでは、rspec テストフレームワーク使用時に、グループ単位や個別での例の実行すべてをトレースできます。

インテグレーションを有効にするには、これを spec_helper.rb ファイルに追加します。

require 'rspec'
require 'datadog/ci'

Datadog.configure do |c|
  # CI でのみテストインスツルメンテーションをアクティブ化します
  c.tracing.enabled = (ENV["DD_ENV"] == "ci")

  # 結果が確実に配信されるようにトレーサーを構成します
  c.ci.enabled = true

  # テスト中のサービスまたはライブラリの名前
  c.service = 'my-ruby-app'

  # RSpec のインスツルメンテーションを有効にします
  c.ci.instrument :rspec
end

DD_ENV 環境変数でテストを実行する環境 (たとえば、開発者ワークステーションでテストを実行する場合は local、CI プロバイダーでテストを実行する場合は ci) を指定して、通常どおりにテストを実行します。例:

DD_ENV=ci bundle exec rake spec

テストにカスタムタグを追加する

現在アクティブなスパンを使用して、テストにカスタムタグを追加することができます。

require 'ddtrace'

# テスト内
Datadog::Tracing.active_span&.set_tag('test_owner', 'my_team')
# テストは正常に続きます
# ...

これらのタグに対して、フィルターや group by フィールドを作成するには、まずファセットを作成する必要があります。タグの追加についての詳細は、Ruby カスタムインスツルメンテーションドキュメントのタグの追加セクションを参照してください。

コンフィギュレーション設定

以下は、Datadog.configure ブロックを使用するか、環境変数を使用するコードで、トレーサーで使用できる最も重要なコンフィギュレーション設定のリストです。

service
テスト中のサービスまたはライブラリの名前。
環境変数: DD_SERVICE
デフォルト: $PROGRAM_NAME
: my-ruby-app
env
テストが実行されている環境の名前。
環境変数: DD_ENV
デフォルト: none
: localci

次の環境変数を使用して、Datadog Agent の場所を構成できます。

DD_TRACE_AGENT_URL
http://hostname:port の形式のトレース収集用の Datadog Agent URL。
デフォルト: http://localhost:8126

他のすべての Datadog トレーサーコンフィギュレーションオプションも使用できます。

Git のメタデータを収集する

Datadog は、テスト結果を可視化し、リポジトリ、ブランチ、コミットごとにグループ化するために Git の情報を使用します。Git のメタデータは、CI プロバイダーの環境変数や、プロジェクトパス内のローカルな .git フォルダがあれば、そこからテストインスツルメンテーションによって自動的に収集されます。

サポートされていない CI プロバイダーでテストを実行する場合や、.git フォルダがない場合は、環境変数を使って Git の情報を手動で設定することができます。これらの環境変数は、自動検出された情報よりも優先されます。Git の情報を提供するために、以下の環境変数を設定します。

DD_GIT_REPOSITORY_URL
コードが格納されているリポジトリの URL。HTTP と SSH の両方の URL に対応しています。
: git@github.com:MyCompany/MyApp.githttps://github.com/MyCompany/MyApp.git
DD_GIT_BRANCH
テスト中の Git ブランチ。タグ情報を指定する場合は、空のままにしておきます。
: develop
DD_GIT_TAG
テストされる Git タグ (該当する場合)。ブランチ情報を指定する場合は、空のままにしておきます。
: 1.0.1
DD_GIT_COMMIT_SHA
フルコミットハッシュ。
: a18ebf361cc831f5535e58ec4fae04ffd98d8152
DD_GIT_COMMIT_MESSAGE
コミットのメッセージ。
: Set release number
DD_GIT_COMMIT_AUTHOR_NAME
コミット作成者名。
: John Smith
DD_GIT_COMMIT_AUTHOR_EMAIL
コミット作成者メールアドレス。
: john@example.com
DD_GIT_COMMIT_AUTHOR_DATE
ISO 8601 形式のコミット作成者の日付。
: 2021-03-12T16:00:28Z
DD_GIT_COMMIT_COMMITTER_NAME
コミットのコミッター名。
: Jane Smith
DD_GIT_COMMIT_COMMITTER_EMAIL
コミットのコミッターのメールアドレス。
: jane@example.com
DD_GIT_COMMIT_COMMITTER_DATE
ISO 8601 形式のコミットのコミッターの日付。
: 2021-03-12T16:00:28Z

収集した情報

CI Visibility を有効にすると、プロジェクトから以下のデータが収集されます。

  • テストの名前と時間。
  • CI プロバイダーが設定する事前定義された環境変数。
  • Git のコミット履歴。ハッシュ、メッセージ、作成者情報、変更されたファイル (ファイルの内容は含まず) が含まれます。
  • CODEOWNERS ファイルからの情報。

その他の参考資料