イベントの取り込みとスキーマの検証
API リクエストが受け入れられただけでは、インストルメンテーション チェックは終了しません。イベントを他のルート、ワーカー、またはサービスにコピーする前に、結果のテーブルと行を確認してください。
このページは、合成ファイルを送信したことを前提としています。 telemetry_quickstart からのイベント 最初の構造化イベントを送信する.
匿名の anon_… キーを使う場合は、下のAPI で確認するに進みます。最初の送信から24時間は同じキーでイベントを読み取れます。チーム画面を使うにはアカウントを作成して試用を保持します。別のブラウザーでは、登録前に**匿名 API キーをお持ちですか？**からキーを入力します。
テーブルを探す
Telemetry チームを開き、選択します テーブル、開きます telemetry_quickstart。テーブルが存在しない場合:
- API リクエストが成功した応答を返したことを確認します。
- キーが目的のチームに属しており、書き込み可能なスコープがあることを確認します。
- 正規化後の正確なテーブル名を確認してください。
- 新しい合成素材で一度再試行してください
request_id. - フォローする イベント取り込みのトラブルシューティング スキーマを変更する前。
新しい識別子を使用せずに同じイベントを繰り返し送信することは避けてください。再試行すると、後のカウントが曖昧になる可能性があります。
推論されたスキーマを検査する
合成 API の例では、次のようなフィールドが公開されます。
| フィールド | 予想される分析タイプ | チェックする |
|---|---|---|
timestamp_utc |
タイムスタンプ | 一貫して追加され、UTC で保存されます |
route_template |
テキスト | 未加工の URL ではなく、制限されたルート テンプレートが含まれています |
status_code |
整数 | 数値比較をサポートできる |
latency_ms |
数値 | どこでもミリ秒を使用する |
status |
テキスト | 文書化された小さな語彙を使用する |
request_id |
テキスト | 秘密を暴露することなく関連イベントを接続します |
重要なフィールドのタイプが間違っている場合は、生産量を送信する前にプロデューサーを停止して修正してください。フィールドが数値から任意のテキストに変更されると、保存された SQL およびグラフの推論が難しくなる可能性があります。
正確な行を検査する
を使用します。 サンプル または テーブル 見て見つける request_id = req_demo_001。確認します:
- この行は、予想される環境およびリリースに属します。
latency_msです184ではありません0.184または184000.- ルートには実際のレポートやアカウント識別子は含まれません。
- 認証ヘッダー、Cookie、リクエスト本文、シークレット、プロンプト、またはプライベート顧客コンテンツは含まれていませんでした。
- 生成された時刻は送信ウィンドウと一致します。
期待される行は、イベント コントラクトが機能することを示す証拠です。これは、パフォーマンスのベンチマークや代表的な運用ディストリビューションではありません。
API を通じて検証する
以下の API チェックには、信頼できるサーバーかローカルのターミナルで読み取り権限のあるキーを使います。Ingest only キーはイベントを送信できますが、テーブルの一覧取得、スキーマの確認、クエリの実行はできません。読み取り権限のあるキーをブラウザーやモバイルアプリのコードに含めないでください。Ingest only キーで送信したイベントは、チーム画面で確認します。
テーブルとスキーマをプログラムで検査することもできます。
curl https://api.telemetry.sh/tables \
-H "Authorization: Bearer $TELEMETRY_API_KEY"
次に、テーブル スキーマをリクエストします。
curl https://api.telemetry.sh/tables/telemetry_quickstart/schema \
-H "Authorization: Bearer $TELEMETRY_API_KEY"
同じワークスペースの読み取り権限のあるキーで、送信したイベントを読み取ります。別の request_id を使った場合は、以下の req_demo_001 を置き換えてください。このクエリは直近24時間を対象に、条件に一致する行を最大10件返します。
curl https://api.telemetry.sh/query \
-H "Authorization: Bearer $TELEMETRY_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON'
{"query":"SELECT timestamp_utc, request_id, route_template, status_code, latency_ms, release, environment FROM telemetry_quickstart WHERE request_id = 'req_demo_001' AND timestamp_utc >= now() - INTERVAL '24 hours' ORDER BY timestamp_utc DESC LIMIT 10"}
JSON
status: "success" と、data 内の期待する行（latency_ms: 184 を含む）を確認してください。空の data 配列は取り込みの確認にはなりません。キー、テーブル、識別子、送信時刻を確認してください。同じ識別子の複数行は再試行による可能性があり、別々のアプリケーション操作とは限りません。サンプルの読み取り成功は、この模擬テストだけを検証します。次に、実際のアプリケーション操作を一つ計測し、その業務テーブルをクエリしてください。
検証の自動化には読み取り可能なキーを使用します。の テーブル API ページネーション、正規化、保持、およびスキーマ応答を文書化します。
契約を記録する
インストルメンテーションを拡張する前に、次のことを書き留めてください。
- イベント名と事業内容。
- 必須フィールドとオプションのフィールド。
- フィールドのタイプと単位。
- 許可されるステータスとエラーのカテゴリ。
- ID フィールドと相関フィールド。
- 禁止されているフィールド。
- 所有者と予定された保存期間。
続けて 最初の SQL クエリを作成する。スキーマ変更戦略については、を参照してください。 スキーマの進化.