Datadog APIの使い方

Datadog APIの紹介

DatadogのAPIは、プラットフォームの強力な監視および分析機能へのプログラムアクセスを提供します。このRESTful APIは、開発者がデータを送信し、視覚化を構築し、コードを通じてDatadogアカウントを管理できるようにします。カスタムアプリケーションの統合、自動化ワークフロー、Datadogの機能拡張に関わらず、APIを活用する方法を理解することは、プラットフォームの可能性を最大限に引き出すために不可欠です。

Datadog APIは、標準のHTTP応答コードを使用し、すべてのリクエストでJSONを受け入れ、返します。また、標準のHTTPメソッドを利用しています。これにより、RESTfulウェブサービスに慣れた開発者にとって直感的になります。APIの包括的な機能は、読み取りおよび書き込み操作を可能にし、監視データの取得だけでなく、Datadog環境のさまざまな側面を構成することもできます。

Datadog APIを習得することで、次のことができるようになります：

• プログラムによってダッシュボード、モニター、およびアラートを作成および管理する
• 任意のアプリケーションまたはインフラストラクチャコンポーネントからカスタムメトリクスを送信する
• インシデント管理ワークフローを自動化する
• CI/CDパイプラインと統合して継続的な監視を行う
• 監視データの周りにカスタムツールやソリューションを構築する

Datadog API認証の開始

APIの呼び出しを行う前に、Datadogリソースへの安全なアクセスを確保するために認証を適切に設定する必要があります。

Datadog APIおよびアプリケーションキーの取得

Datadog APIを使用するには、2種類のキーが必要です：

1. APIキー：これはあなたのDatadogアカウントを特定し、すべてのAPIリクエストに必要です。

• Datadogアカウントに移動します：組織設定 > APIキー
• "新しいキー"をクリックして新しいAPIキーを作成する
• その目的と使用法を示す意味のある名前を付ける
• キーは安全に保管してください。これはあなたのDatadogアカウントにアクセスする権限を与えます。

1. アプリケーションキー：多くの管理エンドポイントに必要で、追加の認証を提供し、アクセス権限を指定します。

• 組織設定 > アプリケーションキーに移動する
• "新しいキー"をクリックしてアプリケーションキーを生成する
• 意図された使用法に基づいて適切に命名する
• オプションで、特定のDatadogアプリケーションへのアクセスを制限する

Datadog API認証ヘッダーの設定

APIリクエストを行う際に、これらのキーをヘッダーとして含める必要があります：

• APIキーを次のようにヘッダーに含めます：DD-API-KEY: your_api_key_here
• 追加の認証を必要とするエンドポイントには、DD-APPLICATION-KEY: your_application_key_hereを含めます。

基本的な認証リクエストの例は次のとおりです：

curl -X GET "<https://api.datadoghq.com/api/v1/dashboard>" \\\\
-H "Content-Type: application/json" \\\\
-H "DD-API-KEY: your_api_key_here" \\\\
-H "DD-APPLICATION-KEY: your_app_key_here"

Datadog APIキーのセキュリティ管理

これらのキーが提供するアクセスは重要であり、セキュリティのベストプラクティスに従うことが重要です：

• キーは定期的にローテーションする、特にAPIキーは
• アプリケーションキーに適切な権限を設定する
• アプリケーションのソースコードにキーをハードコーディングしない
• 環境変数または安全なボールトを使用してキーを保存する
• APIキーの使用を定期的に監査する
• 未使用または潜在的に突破されたキーを直ちに無効にする

Datadog APIのコア概念

Datadog APIの基本的な概念を理解することで、その広範な機能をより効果的にナビゲートできるようになります。

Datadog APIエンドポイントの構造

Datadog APIは、プラットフォームの機能を反映した論理的な機能エリアに整理されています：

• メトリクスAPI：メトリクスデータを送信および照会するため、カスタムメトリクスを送信したり、過去のメトリクス値を取得したりできます。これらのエンドポイントは、アプリケーションおよびインフラストラクチャのパフォーマンスを監視する中心的なものです。
• イベントAPI：Datadogイベントストリームからイベントを投稿および取得するために使用します。イベントは、デプロイメント、アラート、または環境内の重要な出来事を表すことができます。
• モニターAPI：監視アラートのプログラムによる作成と管理を可能にし、通知設定やダウンタイムのスケジュールを構成することを含みます。
• ダッシュボードAPI：視覚化ダッシュボードを構築、修正、取得するためのAPIで、テンプレートまたはアプリケーションのニーズに基づいて自動的なダッシュボードの作成を可能にします。
• ログAPI：Datadogにログを直接送信、ログ処理パイプラインを構成し、ログアーカイブを管理するためのエンドポイントを提供します。
• 合成API：合成テストを管理し、テスト結果を取得し、テストのスケジュールを設定します。
• ユーザーおよび組織API：チームメンバー、権限、および組織設定の管理を可能にします。
• サービスレベル目標（SLO）API：サービスの信頼性を測定するためのSLOを作成および追跡します。

最初のDatadog API呼び出しを行う

一般的なユースケースから始めましょう：カスタムメトリクスを送信すること。この例では、タグ付きのシンプルなゲージメトリクスを送信する方法を示します：

import requests
import time
import json

api_key = "your_api_key_here"
current_time = int(time.time())

payload = {
    "series": [
        {
            "metric": "custom.application.performance",
            "points": [[current_time, 100]],
            "type": "gauge",
            "tags": ["environment:production", "application:web", "region:us-east"]
        }
    ]
}

headers = {
    "Content-Type": "application/json",
    "DD-API-KEY": api_key
}

response = requests.post("<https://api.datadoghq.com/api/v1/series>",
                        headers=headers,
                        data=json.dumps(payload))

print(f"Response Status Code: {response.status_code}")
print(f"Response Body: {response.json()}")

このコードスニペット：

• "custom.application.performance"というカスタムメトリクスのペイロードを作成します。
• 現在のタイムスタンプと100の値を設定します。
• より良い整理とフィルタリングのためにタグを追加します。
• メトリクスエンドポイントにデータを送信します。
• APIレスポンスを印刷します。

Datadog APIレスポンス形式の理解

Datadog APIのレスポンスは通常、一貫したJSON形式に従います：

{
  "status": "ok",
  "errors": [],
  "data": {
    "id": "abc-123-xyz",
    "name": "Example Resource",
    "created_at": "2023-06-01T12:00:00.000Z",
    "modified_at": "2023-06-02T15:30:00.000Z",
    ...
  }
}

主要なフィールドには：

• status：リクエストの成功または失敗を示します
• errors：リクエストが失敗した場合のエラーメッセージを含みます
• data：APIが返す実際のリソースデータです

一般的なDatadog APIのユースケースと例

Datadog APIの実用的なアプリケーションを、主要な機能をカバーする詳細な例を通じて探ります。

Datadog APIダッシュボード情報の取得

ダッシュボードはDatadogの視覚化機能の中心です。特定のダッシュボードの詳細を取得する方法は次のとおりです：

curl -X GET "<https://api.datadoghq.com/api/v1/dashboard/dashboard_id>" \\\\
-H "Content-Type: application/json" \\\\
-H "DD-API-KEY: your_api_key_here" \\\\
-H "DD-APPLICATION-KEY: your_app_key_here"

プログラムで新しいダッシュボードを作成するには：

import requests
import json

api_key = "your_api_key_here"
app_key = "your_app_key_here"

dashboard_payload = {
    "title": "API生成ダッシュボード",
    "description": "Datadog APIを介して作成",
    "widgets": [
        {
            "definition": {
                "type": "timeseries",
                "requests": [
                    {
                        "q": "avg:system.cpu.user{*} by {host}",
                        "display_type": "line"
                    }
                ],
                "title": "ホストごとのCPU使用率"
            }
        }
    ],
    "layout_type": "ordered"
}

headers = {
    "Content-Type": "application/json",
    "DD-API-KEY": api_key,
    "DD-APPLICATION-KEY": app_key
}

response = requests.post("<https://api.datadoghq.com/api/v1/dashboard>",
                        headers=headers,
                        data=json.dumps(dashboard_payload))

print(f"ダッシュボードが作成されました ID: {response.json().get('id')}")

Datadog APIでのモニターの作成

モニターは、積極的なアラートに不可欠です。CPU使用率がしきい値を超えたときにアラートを発信するモニターを作成する方法は次のとおりです：

import requests
import json

api_key = "your_api_key_here"
app_key = "your_app_key_here"

monitor_payload = {
    "name": "高CPU使用アラート",
    "type": "メトリックアラート",
    "query": "avg(last_5m):avg:system.cpu.user{*} > 80",
    "message": "CPU使用率が過去5分間80％を超えています。 @slack-alerts-channel @email.address@example.com",
    "tags": ["app:web", "env:production", "team:infrastructure"],
    "priority": 3,
    "options": {
        "notify_no_data": True,
        "no_data_timeframe": 10,
        "new_host_delay": 300,
        "evaluation_delay": 60,
        "thresholds": {
            "critical": 80,
            "warning": 70
        },
        "include_tags": True,
        "notify_audit": False,
        "require_full_window": False
    }
}

headers = {
    "Content-Type": "application/json",
    "DD-API-KEY": api_key,
    "DD-APPLICATION-KEY": app_key
}

response = requests.post("<https://api.datadoghq.com/api/v1/monitor>",
                        headers=headers,
                        data=json.dumps(monitor_payload))

print(f"レスポンスステータス: {response.status_code}")
print(f"モニターが作成されました: {response.json()}")

この例では：

• メトリックアラートモニターを作成します
• 警告（70％）およびクリティカル（80％）のしきい値を設定します
• Slackとメールへの言及を含む通知設定を追加します
• 評価の遅延や新しいホストの遅延など、詳細な構成オプションを追加します

Datadog APIを使用してAWSと統合する

Datadogをクラウドサービスと接続することで監視能力が拡張されます。AWS統合を作成する方法は次のとおりです：

curl -X POST "<https://api.datadoghq.com/api/v1/integration/aws>" \\\\
-H "Content-Type: application/json" \\\\
-H "DD-API-KEY: your_api_key_here" \\\\
-H "DD-APPLICATION-KEY: your_app_key_here" \\\\
-d '{
  "account_id": "your_aws_account_id",
  "role_name": "DatadogAWSIntegrationRole",
  "access_key_id": "your_access_key",
  "secret_access_key": "your_secret_key",
  "filter_tags": ["env:production", "service:critical"],
  "host_tags": ["account:main", "region:us-east-1"],
  "account_specific_namespace_rules": {
    "auto_scaling": true,
    "opsworks": false,
    "elasticache": true
  },
  "excluded_regions": ["us-west-2", "ca-central-1"]
}'

この統合設定：

• 役割またはアクセスキーを使用してAWSアカウントに接続します
• 特定のリソースに焦点を当てるためのフィルタリングを構成します
• 監視対象のホストに自動的にタグを適用します
• 特定のAWSサービス名前空間を有効にします
• 監視したくないリージョンを除外します

Datadog APIを介してログを送信する

ログは、トラブルシューティングに重要な文脈情報を提供します。ログをDatadogに直接送信する方法は次のとおりです：

import requests
import json
import datetime

api_key = "your_api_key_here"

logs_payload = [{
    "ddsource": "python",
    "ddtags": "env:production,service:payment-processor,version:1.2.3",
    "hostname": "payment-service-01",
    "message": "注文#12345の支払いトランザクションが正常に完了しました",
    "service": "payment-service",
    "status": "info",
    "timestamp": datetime.datetime.now().isoformat(),
    "attributes": {
        "transaction_id": "tx_789012345",
        "amount": 99.95,
        "currency": "USD",
        "customer_id": "cust_123456",
        "payment_method": "credit_card"
    }
}]

headers = {
    "Content-Type": "application/json",
    "DD-API-KEY": api_key
}

response = requests.post("<https://http-intake.logs.datadoghq.com/v1/input>",
                        headers=headers,
                        data=json.dumps(logs_payload))

print(f"ログ送信レスポンス: {response.status_code}")

この例では：

• リッチメタデータを持つ構造化されたログを送信します
• ソース、サービス、および環境情報を含みます
• 特定のビジネスコンテキストのためのカスタム属性を追加します
• より良いフィルタリングと相関のためにタグを使用します

Datadog APIのレート制限での作業

Datadogは、プラットフォームの安定性と顧客間の公正使用を確保するためにレート制限を厳守しています。これらの制限を理解し、尊重することは、信頼できるAPI統合のために不可欠です。

Datadog APIレート制限の理解

異なるエンドポイントは、リソースの強度と典型的な使用パターンに基づいて異なるレート制限があります：

• 読み取り操作は、一般的に書き込み操作よりも高い制限があります
• 一部のエンドポイントは組織ごとの制限がある一方で、他のエンドポイントはキーごとの制限がある場合があります
• 複数のアプリケーションで共有されるAPIキーは、制限に達する可能性が高くなります

Datadog APIレート制限ヘッダーの監視

APIリクエストを行う際には、これらのレスポンスヘッダーをチェックして現在のレート制限ステータスを理解します：

• X-RateLimit-Limit：レート制限ウィンドウ内で許可されるリクエストの最大数
• X-RateLimit-Remaining：現在のレート制限ウィンドウで残っているリクエスト数
• X-RateLimit-Reset：レート制限がリセットされるまでの秒数
• X-RateLimit-Period：レート制限ウィンドウの長さ（秒）

Datadog API呼び出しでのレート制限処理の実装

以下は指数バックオフでレート制限を処理するための堅牢な実装の例です：

import requests
import time
import random

def make_api_request_with_backoff(url, headers, payload=None, max_retries=5):
    retries = 0
    while retries < max_retries:
        response = requests.post(url, headers=headers, json=payload) if payload else requests.get(url, headers=headers)

        if response.status_code == 429:  # リクエストが多すぎます
            # レート制限情報を抽出
            limit = response.headers.get('X-RateLimit-Limit', '不明')
            remaining = response.headers.get('X-RateLimit-Remaining', '不明')
            reset = int(response.headers.get('X-RateLimit-Reset', 60))

            print(f"レート制限に達しました： {remaining}/{limit} リクエストが残っています。 {reset} 秒後にリセットされます。")

            # ジッターを含むバックオフ時間を計算
            backoff_time = min(2 ** retries + random.uniform(0, 1), reset)
            print(f"{backoff_time:.2f} 秒間バックオフします")
            time.sleep(backoff_time)
            retries += 1
        else:
            return response

    raise Exception(f"レート制限により {max_retries} 回の再試行後に失敗しました")

Datadog APIクライアントライブラリの使用

便利さのために、Datadogは複数の言語で公式クライアントライブラリを提供しており、認証とリクエスト形式を簡素化します。

Python Datadog APIクライアント

公式のPythonクライアントは、Datadog APIに対してクリーンで慣用的なインターフェースを提供します：

pip install datadog-api-client

クライアントを使用してメトリクスを送信する例は次のとおりです：

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v1.api.metrics_api import MetricsApi
from datadog_api_client.v1.model.metrics_payload import MetricsPayload
from datadog_api_client.v1.model.metrics_series import MetricsSeries
from datadog_api_client.v1.model.point import Point
import time

configuration = Configuration()
configuration.api_key["apiKeyAuth"] = "your_api_key_here"
configuration.api_key["appKeyAuth"] = "your_app_key_here"

with ApiClient(configuration) as api_client:
    api_instance = MetricsApi(api_client)
    body = MetricsPayload(
        series=[
            MetricsSeries(
                metric="application.request.duration",
                points=[
                    Point([int(time.time()), 250.0])
                ],
                type="gauge",
                host="web-server-01",
                tags=["endpoint:login", "environment:staging"]
            )
        ]
    )
    response = api_instance.submit_metrics(body=body)
    print(f"メトリクス送信成功: {response}")

Ruby Datadog APIクライアント

Rubyアプリケーションの場合、公式クライアントライブラリはAPIの相互作用を簡素化します：

gem install datadog_api_client -v 2.31.1

モニターを作成するための使用例：

require 'datadog_api_client'

DatadogAPIClient.configure do |config|
  config.api_key = 'your_api_key_here'
  config.application_key = 'your_app_key_here'
end

api_instance = DatadogAPIClient::V1::MonitorsAPI.new
body = {
  'name' => 'APIテストモニター',
  'type' => 'メトリックアラート',
  'query' => 'avg(last_5m):avg:system.cpu.user{*} > 75',
  'message' => 'CPU使用率が高い',
  'tags' => ['test:api', 'monitor:automated'],
  'options' => {
    'thresholds' => {
      'critical' => 75,
      'warning' => 65
    }
  }
}

begin
  result = api_instance.create_monitor(body)
  puts "モニターが正常に作成されました ID: #{result['id']}"
rescue DatadogAPIClient::APIError => e
  puts "モニターの作成中にエラーが発生しました: #{e}"
end

Datadog API使用のベストプラクティス

これらのガイドラインに従うことで、Datadog APIとのより信頼性が高く、安全かつ効率的な統合を構築できます。

Datadog APIキーのセキュリティ確保

APIキーのセキュリティは非常に重要です：

• キーは環境変数または安全なボールトに保存し、決してコードリポジトリに保存しない
• キーのローテーションポリシーを実装し、APIキーを定期的に更新する
• 異なるアプリケーションや目的ごとに異なるAPIキーを使用する
• アプリケーションキーの権限を制限することにより、最小権限の原則を適用する
• 可能な場合はIPホワイトリストを使用して、既知のIPアドレスへのアクセスを制限する

Datadog API呼び出しでのタグの効果的な使用

タグは、Datadogデータを整理およびフィルタリングするための強力なメカニズムです：

• API実装を開始する前に、一貫したタグ付けの分類法を設計します
• すべてのメトリクスとログに環境、サービス、およびバージョンのタグを含める
• 階層的なタグ（例：region:us-east、availability-zone:us-east-1a）を使用する
• すべてのテレメトリ（メトリクス、ログ、トレース）にわたってタグが一貫していることを確認する
• メトリクスで高カーディナリティのタグを避ける（例：ユニークユーザーID）

Datadog APIリクエストのエラーハンドリングの実装

堅牢なエラーハンドリングは、統合が信頼性を保つことを確保します：

• HTTPステータスコードを確認し、異なるエラータイプを適切に処理する
• 詳細なエラー情報のためにエラー応答本文を解析する
• 一時的なエラーに対する指数バックオフを伴う再試行ロジックを実装する
• デバッグ用に十分なコンテキストで失敗したAPI呼び出しをログに記録する
• リクエストのハングを防ぐために合理的なタイムアウトを設定する

def send_to_datadog(endpoint, payload, headers):
    try:
        response = requests.post(endpoint,
                                json=payload,
                                headers=headers,
                                timeout=10)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.Timeout:
        print("リクエストがタイムアウトしました - Datadog APIが遅延している可能性があります")
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 400:
            print(f"不正なリクエスト: {e.response.json().get('errors', [])}")
        elif e.response.status_code == 403:
            print("認証エラー - APIおよびアプリケーションキーを確認してください")
        elif e.response.status_code == 429:
            print("レート制限に達しました - バックオフと再試行を実装してください")
        else:
            print(f"HTTPエラー: {e.response.status_code}")
    except requests.exceptions.RequestException as e:
        print(f"リクエストに失敗しました: {e}")

    return None

Datadog APIでのサンドボックス環境でのテスト

本番導入前に：

• Datadogに専用の開発/ステージング組織を作成する
• テストと本番用に別々のAPIキーを使用する
• 通知が開発チームにのみ向けられるテストモニターを作成する
• レート制限の影響を理解するために負荷テストをシミュレートする
• 将来の参照のためにAPIの使用パターンを文書化する

Datadog API使用の監視

API使用状況を追跡して早期に問題を検出します：

• API呼び出しのボリュームとエラー率を視覚化するダッシュボードを作成する
• 過剰なAPIエラーや近づくレート制限の監視を設定する
• 適切な詳細ですべてのAPI操作のログを実装する
• Datadogの監査ログを通じてAPIキーの使用を定期的に監査する
• APIを通じて送信されたカスタムメトリクスのコスト影響を追跡する

結論：Datadog APIをマスターする

Datadog APIは、監視および分析プラットフォームを拡張およびカスタマイズするための強力な機能を提供します。このガイドに概説されている認証プロセス、コア概念、ベストプラクティスを理解することで、Datadogをアプリケーションに統合し、ワークフローを自動化する準備が整います。

カスタムメトリクスを送信したり、モニターを作成したり、複雑なダッシュボードを構築したりする際に、APIはDatadogを特定のニーズに合わせてカスタマイズする柔軟性を提供します。使用が進むにつれて、次のようなより高度なパターンを実装することを検討してください：

• 新しいサービス用のテンプレートベースのダッシュボード生成
• 自動化されたモニターのメンテナンスと調整
• 内部ツールおよびシステムとのカスタム統合
• スケジュールされたレポート作成およびデータ抽出ワークフロー
• 重要なビジネスプロセスの合成モニタリング

Datadog APIによって提供されるプログラムによる機能により、インフラストラクチャに合わせてスケールし、組織のユニークな要件に適応する監視エコシステムを構築できます。

新しいエンドポイントや機能が頻繁に追加されるため、Datadogの公式APIドキュメントを定期的にチェックしてください。このガイドから得た知識を持って、Datadogの可観測プラットフォームの完全な力量を活用した洗練された自動化された監視ソリューションを構築する準備が整いました。