最初の構造化イベントを送信する

このチュートリアルでは、1 つの合成 API 結果を Telemetry に送信します。目標は賞品を受け取ることだけではありません 200 応答。これは、SQL、ダッシュボード、アラートをサポートできるイベント コントラクトから始まり、その後、生のリクエスト ペイロードを収集せずにデバッグを行うことになります。

始める前に

チームを作成し、 write-スコープ付きキー入力 チーム設定 → API キー。値をローカル環境変数またはシークレット マネージャーに保持します。

export TELEMETRY_API_KEY="replace-with-your-key"

ブラウザー JavaScript、モバイル アプリケーション、パブリック リポジトリ、またはスクリーンショットでチーム キーを公開しないでください。参照 APIキーと認証 範囲と回転のガイダンス用。

完了したワークフローを 1 つ選択してください

アプリケーションが結果を認識している境界から開始します。良い最初のイベントには次のようなものがあります。

• api_request_completed
• background_job_completed
• webhook_processing_completed
• checkout_completed
• agent_run_completed

次のような一般的なメッセージよりも、完了した結果を優先します。 something_happened。安定したイベント名では、すべてのプロデューサーとクエリに同じ粒度が与えられます。

この例では、合成 API リクエストを使用します。

{
  "route_template": "/api/reports/:report_id",
  "method": "POST",
  "status": "success",
  "status_code": 200,
  "latency_ms": 184,
  "release": "local-demo",
  "environment": "development",
  "request_id": "req_demo_001"
}

URL は、識別子を含む生の URL ではなく、ルート テンプレートです。イベントには、分類された結果フィールドと安全な相関識別子が含まれますが、リクエスト本文、認可ヘッダー、Cookie、または顧客コンテンツは含まれません。

cURL でイベントを送信します

curl https://api.telemetry.sh/log \
  -H "Authorization: Bearer $TELEMETRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "table": "api_request_completed",
    "data": {
      "route_template": "/api/reports/:report_id",
      "method": "POST",
      "status": "success",
      "status_code": 200,
      "latency_ms": 184,
      "release": "local-demo",
      "environment": "development",
      "request_id": "req_demo_001"
    }
  }'

に文書化されている正確なリクエスト形式を使用してください。 ログ API SDK または API のバージョンがこの例と異なる場合。

JavaScript から同じイベントを送信します

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

await telemetry.log("api_request_completed", {
  route_template: "/api/reports/:report_id",
  method: "POST",
  status: "success",
  status_code: 200,
  latency_ms: 184,
  release: "local-demo",
  environment: "development",
  request_id: "req_demo_001"
});

信頼できるサーバー側コードで SDK を初期化します。サービス間でフィールド名と単位の一貫性を保ちます。たとえば、期間は常に次のように保存されます。 latency_ms 秒とミリ秒を混在させるのではなく。

成功とは何か

送信が成功した場合は、API がイベントを受け入れたことのみが証明されます。続けて イベント取り込みの検証 テーブル名、推論されたタイプ、生成されたタイムスタンプ、および正確な行を確認します。最初のイベント コントラクトがクエリ可能で安全になるまで、それ以上のワークフローをインストルメントしないでください。

より大きなスキーマについては、以下を参照してください。 イベントスキーマの設計。機密フィールドの場合は、次を使用します 機密データの編集.