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

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

始める前に

ホームページの設定プロンプトをコピー済みなら、その anon_… キーでアカウントなしでイベントを送信し、クエリできます。

アカウントがある場合は、チーム設定 → API キーで read-and-write キーを作成します。次の手順でイベントを読み取るためです。送信のみのアプリは ingest キーを使えます。

キーはローカルの環境変数かシークレットマネージャーに保存します。

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

匿名キー、読み取り専用キー、読み書きキーは非公開にしてください。ブラウザーやモバイルアプリからのイベント送信には Ingest only キーを使えます。このキーではデータのクエリや管理はできません。ただし、コピーして不要なイベントを送信することは可能です。使用状況を確認し、悪用された場合は無効にしてください。権限とキーの更新については 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": "telemetry_quickstart",
    "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("telemetry_quickstart", {
  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 秒とミリ秒を混在させるのではなく。

成功とは何か

匿名クエリは最初のイベントから24時間利用できます。7日以内にアカウントを作成すると、イベントと同じキーを保持できます。同じブラウザーでは登録時に試用を検出します。別のブラウザーでは、匿名 API キーをお持ちですか？を選び、キーを貼り付けてデータを探すを押してから登録します。既存ユーザーはデータを保持でキーを復元してからログインできます。イベントのない試用は作成から7日で期限切れになります。

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

この例は架空のデータであり、API への送信経路を確認するためのものです。アプリの連携を完了するには、実際の処理が完了する地点でイベントを記録し、その処理を実行して、保存されたイベントをクエリで確認してください。telemetry_quickstart の行だけでは設定完了にはなりません。

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