datadog-ciの導入と使い分け｜3つの配布形態とプラグイン方式・CI連携コマンド

「datadog cli」で調べ始めた人が最初に踏む段差は、名前の似た2つのコマンドが存在することです。CI/CDパイプラインから叩くdatadog-ciと、ホストに常駐するAgentを操作するdatadog-agentは別物として設計されています。2026年8月時点の一次情報をもとに、どちらを入れるべきかの判断から、配布形態の選び分け、v5系で変わったプラグイン方式までを順に整理します。

まとめ：datadog-ci導入前に決める配布形態とプラグイン管理

結論から置きます。着手前に決めるのは3点です。どの配布形態で入れるか、プラグインを明示インストールするか自動任せにするか、そしてバージョンをどこまで固定するか。曖昧にしたまま進めると、ある日ジョブが落ちて原因が特定できない状態になります。

配布形態から述べます。Node.jsのランタイムがすでにジョブ内にあるなら、npmパッケージをdevDependenciesへ入れる形が素直でしょう。GoやJavaのビルドコンテナで実行するなら、スタンドアロンバイナリを1本落とす形が軽く済みます。コンテナイメージdatadog/ciは、ジョブそのものをイメージで切り替えられるCIに向く選択肢。

次にプラグイン。5.x系のnpmパッケージは、コマンド群がプラグインとして別パッケージに切り出されています。既定では未導入のプラグインが実行時に自動インストールされる挙動で、これはビルド中にネットワーク経由の追加取得が走るという副作用を伴います。CIの再現性を優先するなら、datadog-ci plugin installで先に入れ、自動導入は環境変数で止めてください。

最後にバージョン。公式のREADMEは正確なバージョンの固定を推奨しています。@v5のようなメジャーレンジ指定は、マイナー更新をそのまま本番へ流し込む指定です。理由は配布形態の章で具体的に書きます。

datadog cliが指す2系統のCLIとそれぞれの守備範囲

Datadogが配布するコマンドラインツールは1つではありません。目的が違うので、まずどちらの話をしているのかを確定させます。

CI/CDジョブから実行するdatadog-ciが担当する範囲

datadog-ciは、CI/CDパイプラインの中で実行し、既存のDatadog製品へデータを送るためのCLIです。テスト結果やカバレッジ、SBOM、ソースマップをアップロードし、パイプライントレースへタグや計測値を足し、デプロイをマークする。加えて、LambdaやCloud Runといったマネージド実行基盤へ計装を適用するinstrument系も持ちます。

実体はNPMパッケージ@datadog/datadog-ciで、npmレジストリ上のlatestは2026年8月15日時点で5.22.1、enginesはNode.js 20以上でした。多くのコマンドは非対話前提で--dry-runを備えます。常駐はせず、ジョブの中で走って終わる使い捨てのプロセスです。

ホストに常駐するAgentを操作するdatadog-agentコマンド

対してdatadog-agentは、ホストやコンテナに常駐するDatadog Agentを操作するコマンドです。statusで有効なインテグレーションを確認し、checkで個別チェックを単発実行し、diagnoseで接続診断を回し、flareで診断情報をまとめて送る。トラブルシュートの入口がここに集まっています。

2つは送るデータの性質が違います。Agentはメトリクス・ログ・トレースを継続的に収集する常駐プロセスで、その導入設計はホスト・Docker・DaemonSetの3方式とdatadog.yamlの設定で扱いました。datadog-ciはビルド1回ごとの成果物とイベントを送る側。役割が重なる場面は、実務ではほとんどありません。

datadog-ciとAgentのどちらを先に入れるかの判断順序

順序は明快です。アプリケーションの稼働監視が目的ならAgentが先、パイプラインの可視化が目的ならdatadog-ciが先。両方やるなら、Agentを先に入れてサービス名とenvタグの体系を固めてから、datadog-ci側の--serviceと--envを合わせます。逆順にすると、両者のデータがタグでつながらず手戻りが出ます。

Datadogで何がどう計測されるのかを押さえていない段階なら、Datadogの機能構成と導入の背景を先に読むと以降のコマンドの意味が通ります。CLIはあくまで既存製品への入口です。

datadog-ciの3つの配布形態とバージョン固定の判断基準

公式が案内する入れ方は3通りです。どれも同じコマンドが動きますが、ジョブの起動時間と再現性の性質が変わります。

npmパッケージとしてdevDependenciesへ入れる構成

Node.jsのプロジェクトなら、これが既定解になります。npm install --save-dev @datadog/datadog-ciでロックファイルに載せておけば、バージョンはリポジトリ側で管理されます。npxによる一発実行にも対応しますが、CIで毎回叩く構成はバージョン固定の観点で勧めません。

注意点はランタイム要件。5.x系はNode.js 20以上を求めます。MIGRATING.mdによると、Node.js 18は2025年4月にEOLを迎えたため4.0から5.0で対象外になりました。古いNodeイメージでCIを回しているなら、CLIを上げる前にベースイメージを確認してください。

Node.jsを用意できないCIで使うスタンドアロンバイナリ

ビルドジョブがGoやRust、Javaのコンテナで、そこにNode.jsを入れたくない場合の選択肢です。GitHub Releasesへアーキテクチャ別のバイナリが添付されており、linux-x64・linux-arm64・alpine系・darwin系・win-x64が用意されています。Linuxならcurl -L --failで取得して実行権限を付けるだけで動く手軽さ。

実務上の利点は、プラグインが最初から全部含まれている点です。追加取得が発生しないため、ネットワーク要因のばらつきが減ります。落とし穴も1つ。公式は、バイナリを小さくしようとstripでデバッグシンボルを削るとセグメンテーション違反を起こす場合があると警告しています。イメージ削減の自動処理を挟んでいるなら、対象から外してください。

コンテナイメージdatadog/ciをジョブ単位で起動する構成

3つ目は公式イメージです。Docker Hubのdatadog/ciに加え、Amazon ECR PublicとGoogleのレジストリでも配布されています。ジョブのimageを差し替えるだけで、ランタイムもプラグインも考えずに済む構成。認証情報は環境変数で渡します。

3方式の性質を並べると、選択の軸が見えてきます。

exactバージョン固定を推奨する理由とレンジ指定で起きる事故

公式READMEは、破壊的変更とサプライチェーン攻撃の両面から、正確なバージョンの固定を推奨しています。前者は現実に起きました。4.0から5.0では、Node.js 18の切り捨てに加えてsbom uploadがプルリクエスト起点のトリガーを非対応にし、lambda instrumentの--layer-versionと--extension-versionの既定値がnoneからlatestへ変わっています。

最後の変更はとくに影響が読みにくい部類です。明示指定をしていないパイプラインは、実行のたびに最新のレイヤーを適用する挙動へ切り替わります。従来どおりに戻すには--layer-version none --extension-version noneを明示します。CLIを上げただけのつもりが、本番Lambdaの計装内容まで動く。これがレンジ指定の怖さです。

datadog-ci v5系のプラグイン分割とコマンドスコープの全体像

5.x系を触るうえで避けて通れないのが、プラグイン方式です。ここを知らないままCIを組むと、意図しないタイミングでパッケージ取得が走ります。

一部コマンドがプラグインへ切り出された経緯とサイズ削減の狙い

プラグインは、本体パッケージのインストールサイズを削るために切り出されたNPMパッケージ群です。4.0でaas・cloud-run・lambda・stepfunctionsが移り、5.0ではsyntheticsが@datadog/datadog-ci-plugin-syntheticsへ移動しました。この管理を負うのはnpmパッケージ形式だけで、バイナリとイメージは全部入りです。

plugin listとplugin installで明示インストールする手順

プラグインの操作は2つのサブコマンドに集約されています。何が入るのかを見てから、必要なものだけ入れる流れです。

1. datadog-ci plugin listで導入可能なプラグインの一覧を確認する
2. 使うスコープだけをdatadog-ci plugin install syntheticsのように明示インストールする
3. インストール手順をCIのキャッシュ対象に含め、ジョブごとの再取得を避ける
4. 実行ジョブ側で自動インストールを無効化し、想定外の取得が起きないようにする

自動インストールを止めるDISABLE_PLUGIN_AUTO_INSTALL

既定では、プラグインを要するコマンドを叩いた時点で、そのプラグインが自動インストールされます。後方互換のための挙動で、手元の検証では手数が減る仕様。一方で本番へ置くと、ビルド時間が読めなくなり、外部レジストリの障害がそのままジョブの失敗になります。

止める手段はDISABLE_PLUGIN_AUTO_INSTALL=1の1行です。公式も明示インストールを推奨しており、自動導入は移行期の保険という位置づけと読めます。閉域網のCIランナーでは自動取得が失敗して分かりにくいエラーになるため、先に無効化しておくほうが調査が短く済みます。

コマンドスコープをアップロード系と計装系に分けて捉える整理法

スコープは20種類を超えますが、性質で4つに分けると全体像を掴めます。

この分類が効くのは権限設計です。アップロード系と注釈系はAPIキーだけで動きますが、計装系はAWSやAzureの認証情報を要求します。同じジョブに全部を詰め込むと、必要以上に広い権限を1つのジョブが抱えます。

CI/CDパイプラインへ組み込む主要コマンド4種類の実装手順

ここからは、使う頻度が高い4系統のコマンドを引数の意味まで含めて見ていきます。

sourcemaps uploadでフロントのスタックトレースを復元する

ミニファイされたJavaScriptのエラーは、そのままでは読めません。datadog-ci sourcemaps uploadは、ビルド成果物のディレクトリを渡すと配下の.js.mapを再帰的に探し、対応するJSファイルと送ります。必須オプションは--service、--release-version、--minified-path-prefixの3つ。

詰まりやすいのは3つ目の--minified-path-prefixです。配信先URLに合わせた共通プレフィクスを指定する引数で、フルURLでも絶対パスでも構いません。ここがずれると、アップロードは成功するのにスタックトレースが復元されないという分かりにくい状態になります。--dry-runで送信前の検査だけを回せるので、初回は必ず挟んでください。

前提として、送り先のservice名とversionタグはRUM SDK側の設定と一致している必要があります。SDKのタグ設計はRUMのブラウザSDK設定からAPMトレース紐付けまでの実装手順で扱った内容がそのまま噛み合う部分です。

junit uploadでテスト結果をTest Visibilityへ送る

テストフレームワークがJUnit形式のXMLを吐けるなら、datadog-ci junit uploadで送れます。位置引数にディレクトリかファイルパスを並べる形。--serviceはDD_SERVICE、--envはDD_ENVを既定値として拾うため、環境変数を揃えておけば引数を減らせます。

--auto-discoveryを付けると、渡したフォルダの配下を再帰的に探し、*junit*.xmlや*test*.xmlといった命名のレポートを自動で拾います。モノレポでは手数が減る一方、拾ってほしくないものまで入りやすく、--ignored-pathsとの併用が前提になります。

タグには順序の規則があります。--tagsで渡した値はDD_TAGS環境変数とマージされ、キーが衝突した場合は環境変数側が優先されます。セッション単位にだけ付けたいなら--report-tagsを使い、こちらはマージされません。

traceとtag・measureでパイプラインに独自の情報を足す

パイプライントレースに情報を足す3コマンドです。datadog-ci traceは任意のコマンドをラップして1スパンとして計測し、datadog-ci tagとdatadog-ci measureは実行中のスパンへ文字列タグと数値を追加します。

tagには--levelがあり、pipeline・job・stage・stepをカンマ区切りで並べられます。チーム名のように上位から伝播しないタグを複数階層へ同時に付けたい場面で効く引数。いずれかの階層で失敗すると非ゼロ終了しますが、成功した階層のタグは残ります。CIを落としたくないなら--no-failを添えてください。

前提条件として、これらはサポート対象のCIプロバイダでしか動きません。GitHub、GitLab、Jenkins、CircleCI、Azure DevOps Pipelines、AWS CodePipeline、Buildkiteが対象です。可視化そのものの考え方はCI Visibilityが何を可視化する仕組みなのかを先に押さえると、どのタグを足すべきかの判断が付きます。

betaコマンドとdeprecated扱いのgateを本番へ入れる線引き

スコープの中には、扱いを分けるべきものが2種類あります。1つはbetaコマンド。deploymentスコープのmark・correlate・gateなどは、DD_BETA_COMMANDS_ENABLED=1を立てないと呼び出せません。環境変数を要求する設計自体が、仕様変更の余地があるという合図と読めます。

もう1つはdeprecated扱いです。Quality Gatesを評価するgate evaluateは、READMEで非推奨と明記され、2026年中にPR Gatesへ置き換えられる旨が案内されています。これから新規に組むなら、gate evaluateを前提にした承認フローは避けるほうがよいでしょう。

線引きの基準は「デプロイを止める判断をそれに委ねるか」です。可視化やメタデータの付与に留まる用途なら、betaでも実害は小さい。一方、デプロイの可否を握らせる用途は安定版の機能に限ります。この切り分けを守れば、CLIの更新でリリースが止まる事故は避けられます。

datadog-ci採用の判断条件と見送るべきパイプライン構成

ここからは判断を言い切ります。導入は数行で終わりますが、入れるべき状態かは別の話です。

採用してよい条件はCIの実行環境をコードで固定できる開発体制

採用してよいのは、CIの実行環境がコードで固定されていて、serviceとenvのタグ体系が決まっている体制です。この2つが揃っていれば、CLIが送ったデータはAgent由来のデータと同じ軸で並びます。タグが揃わないままアップロードだけ始めても、テスト結果とアプリのメトリクスが別々の島として溜まるだけ。

もう1つの条件は、パイプライン定義がリポジトリ管理下にあることです。バージョン固定もプラグインの明示インストールも、定義に書いて初めて効きます。GUIでジョブを組む環境では、固定したはずの設定が手作業で戻ります。

見送るべき場面は成果物の受け渡しが定まっていないパイプライン

見送るべき場面を条件で示します。1つ目は、テストレポートやソースマップの出力先がジョブごとにばらつき、成果物の受け渡しが定まっていない構成。ここでアップロードを足すと、拾えたり拾えなかったりする不安定なジョブが増えるだけで、原因はパイプライン設計側にあります。先に成果物の置き場を決めてください。

2つ目は、閉域網でNPMレジストリへ到達できず、社内ミラーも用意していない環境です。バイナリを社内リポジトリへ置くか、イメージを社内レジストリへ複製する準備が先に要ります。3つ目は、CIプロバイダがサポート対象外の場合。注釈系コマンドが動かないため、得られるのはアップロード系だけになります。

APIキーとアプリケーションキーをCIジョブへ渡すときの権限分離

認証はDD_API_KEYが基本で、コマンドによってはDD_APP_KEYも要ります。送信先が米国既定以外ならDD_SITEの指定も必要です。押さえておきたいのは、アプリケーションキーが「発行した人の権限」を引き継ぐ点。個人名義のキーをCIに置くと、退職や権限変更でパイプラインが突然落ちます。

キーの役割分担とスコープの絞り方は、Datadog APIにおける2種類のキーの権限分離で整理した内容が当てはまります。サービスアカウント名義で発行し、スコープを必要最小に絞り、CIのシークレット機能で渡す。この3点でCLI経由の事故はほぼ塞げます。

組み込みそのものを内製で回し切れるか迷う場合は、保守運用・内製化支援の相談から、CI設計と監視設計をまとめて整理する進め方もあります。タグ体系と権限設計は、先に決めておくほど後の手戻りが減ります。

よくある質問

datadog-ciの導入で質問が集まる5点をまとめます。

datadog-ciとdatadog-agentは両方入れる必要がありますか？

目的が違うので、必要なほうだけで構いません。稼働を継続的に監視したいならAgent、パイプラインの成果物とイベントを送りたいならdatadog-ciです。両方導入する場合も同居は不要で、Agentは本番のホスト側、datadog-ciはCIランナー側が典型的な配置になります。タグのserviceとenvだけは両者で揃えてください。

Node.jsが入っていないCIでも使えますか？

使えます。GitHub Releasesで配布されているスタンドアロンバイナリを取得すれば、Node.jsのインストールは不要です。Linuxならダウンロードして実行権限を付けるだけで動きます。プラグインも同梱済みで追加手順は要りません。コンテナ実行が前提のCIなら、公式イメージへジョブのimageを差し替える方法もあります。

プラグインの自動インストールは止めるべきですか？

本番のパイプラインでは止めることを勧めます。自動インストールはコマンド実行時に未導入のプラグインを取得しに行くため、ビルド時間が読めなくなり、外部レジストリの障害がジョブの失敗に直結します。DISABLE_PLUGIN_AUTO_INSTALL=1を設定し、セットアップ工程でdatadog-ci plugin installを明示的に走らせてください。

バージョンはどこまで固定すべきですか？

正確なバージョンまで固定してください。公式READMEも、破壊的変更とサプライチェーン攻撃の両面から推奨しています。実例として4.0から5.0では、Node.js 18が対象外になり、lambda instrumentの既定値が変わりました。npmならロックファイル、バイナリならリリースタグ付きURL、イメージならタグ指定で固定します。

CLIから設定変更まで任せてよいですか？

恒久的な設定は別経路に残すことを勧めます。datadog-ciが得意なのは、ビルドごとに発生する成果物のアップロードとイベントの記録です。存在し続けるモニターやダッシュボードの定義は、Terraformなどの宣言的管理に置くほうが差分を追えます。instrument系はその中間で、CLIから適用するなら引数を明示してください。

関連記事

• Datadog Agent導入の実装手順：CLIのもう一方の系統である、常駐Agent側の配置方法を扱っています。
• TerraformでDatadogを管理する方法：CLIに任せない恒久的な定義を、コードで管理する経路です。
• Datadog運用のベストプラクティス：CLIが送るデータの前提となるタグ設計と監視対象の絞り込みを整理しています。
• Datadog APM導入の実装手順：パイプラインから送るデータと突き合わせる、アプリ側のトレース計装を扱っています。
• Datadogの料金体系と費用が膨らむ課金単位：アップロードしたテスト結果やスパンが乗る課金単位を整理しています。