イベント取り込みのトラブルシューティング

イベントが予期した場所に表示されない場合は、リクエストの配信、認証、ペイロードの検証、スキーマの互換性、およびクエリの鮮度を分離します。アプリケーション操作が成功しても、テレメトリの取り込みが成功したことは証明されません。また、HTTP リクエストが受け入れられたとしても、後のクエリが同じテーブルと時間範囲を参照していることは証明されません。

診断中に、一意の安全な識別子を持つ合成イベントを使用します。 本番ペイロードをログ、チケット、コマンド履歴にコピーしないでください.

1.実際のHTTP結果をキャプチャします。

一時的に cURL を使用して 1 つのイベントを送信し、応答ステータスと本文を確認できるようにします。

curl -i -X POST https://api.telemetry.sh/log \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "table": "ingestion_diagnostics",
    "data": {
      "event_id": "diagnostic-2026-07-28-01",
      "source": "manual_check",
      "status": "expected"
    }
  }'

API キーを環境変数に保存します。診断の収集中​​に、これをペイロードに貼り付けたり、印刷したりしないでください。

再試行する前にステータスを解釈します。

• 400 JSON、テーブル名、タイムスタンプ、データ形状、またはフィールド タイプを変更する必要があることを意味します。同じボディを再試行しても修復されません。
• 401 キーが欠落している、形式が間違っている、無効である、または取り消されていることを意味します。
• 403 これは、キーに操作の書き込みスコープがないことを意味します。
• 429 現在のリクエストレートまたはクォータを超えたことを意味します。尊重する Retry-After 指定されている場合はそれに従い、ジッター付き指数バックオフを上限付きで使用します.
• 5xx 有効なリクエストに対するサーバー側の障害を表します。メイン アプリケーションを無期限にブロックすることなく、限られた回数だけ再試行します。

読む レート制限と API エラー 完全なクライアント ポリシーについては、

2. 宛先テーブルを確認する

ログ API は、要求されたテーブル名を正規化します。スペースはアンダースコアになり、文字は小文字になります。正規化後は、小文字の ASCII 文字、数字、アンダースコアのみが有効になります。

たとえば、 Checkout Events になる checkout_events。次のような推測された名前をクエリする CheckoutEvents 同じ目的地を検査することはありません。

診断中に、リクエストで単純な明示的な名前を使用し、Telemetry のテーブル リストまたはスキーマを検査します。 2 つのサービスが 1 つのテーブルに書き込む必要がある場合は、両方が同じ正規化された名前とフィールド タイプを使用していることを確認してください。

3. 受け入れられたデータ形式を検証する

の data プロパティは次のとおりです。

• 1 つの JSON オブジェクト
• JSON オブジェクトの配列
• オブジェクトにデコードされる JSON 文字列
• オブジェクトと、それぞれがオブジェクトにデコードされる JSON 文字列を含む配列

最上位の数値、ブール値、 null、それらの値にデコードされる文字列は拒否されます。配列には任意のスカラー値を含めることはできません。文書化された制限を超えて深くネストされたペイロードも拒否されます。

失敗したイベントを 3 つの無害なフィールドに減らします。リクエストが再び失敗するまで、小さなグループにフィールドを追加し直します。これにより、元の顧客ペイロードを公開することなく、無効な形状が分離されます。

4. タイムスタンプの動作を確認する

Telemetry は UTC を追加します timestamp 欠落しているか null の場合。 Unix タイムスタンプの整数と数値文字列は、サポートされている範囲内にある場合、Unix 秒として解釈され、RFC 3339 に正規化されます。クライアントが提供する timestamp_utc このフィールドはクエリ レイヤーによって管理されているため、削除されます。

新しいイベントがクエリ ウィンドウの外側に表示された場合:

1. カスタムを削除する timestamp 新しい合成イベントを送信します
2. 生成されたクエリによる timestamp_utc
3. アプリケーションのクロック、ソースのタイムスタンプ、クエリのタイムゾーンを比較します。
4. 元のタイムスタンプが誤って秒ではなくミリ秒だったかどうかを確認します

使用する タイムスタンプの操作 元のイベント時刻を受信時刻とは別に保持する必要がある場合.

5. スキーマの互換性を検査する

最初に受け入れられたイベントによってフィールド タイプが確立されます。新しいオプション フィールドの追加は、既存のフィールドを数値から文字列、ブール値、タイムスタンプ、またはネストされたオブジェクトに変更することとは異なります。

テーブル スキーマを検査し、失敗したペイロードをフィールドごとに比較します。一般的なドリフトには次のようなものがあります。

• あるプロデューサーからは整数として送信され、別のプロデューサーからは文字列として送信される識別子
• 1 つのリリースで数値として送信される期間、および "842ms" 別のところで
• スカラーに置き換えられたネストされたオブジェクト
• 整数のセントと小数の通貨単位の間で変化する金銭の価値
• SDK は enum を異なる方法でシリアル化するため、ステータス変更タイプ

概念によってタイプまたは単位が実際に変更される場合は、バージョン管理されたフィールド名を追加し、クエリを意図的に移行します。読む イベントのデータ型とNull可能性 そして スキーマの進化.

6. 一括障害を分離する

拒否されたバッチの場合は、小さな合成サブセットを使用して再現します。必要に応じて、互換性のない品目が特定されるまでバッチを分割します。馬小屋を保存する event_id 同じ論理イベントを再試行するときも維持し、重複配信を測定できるようにします.

すべてのネットワーク試行に黙って新しい識別子を割り当てないでください。これにより、1 つの結果が複数の行に分割され、再試行の回復、請求合計、ファネルの信頼性が低くなります。重複を監査する 重複したイベント ID SQL レシピ.

7. SQL でイベントを確認します。

正確な診断識別子と十分な UTC 範囲をクエリします。

SELECT
  event_id,
  source,
  status,
  timestamp_utc
FROM ingestion_diagnostics
WHERE event_id = 'diagnostic-2026-07-28-01'
  AND timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC;

行は存在するがダッシュボードが空の場合は、ダッシュボードのテーブル、フィルター、時間範囲、および予期されるフィールド タイプを比較します。ソース全体から新しい行が表示されない場合は、 取り込み鮮度のレシピ 隙間を見えるようにするためです。

予防チェックリスト

• サーバー側のキーをブラウザーのバンドルから除外し、必要な操作に範囲を限定します。
• 安全なステータス、エンドポイント、リクエストID、取り込み失敗のエラーカテゴリをキャプチャします。
• 安定したテーブル名、イベント名、フィールドタイプ、および明示的な単位を使用する
• 運用前に合成チェックまたはステージング チェックを通じてスキーマの変更を送信する
• テレメトリによって従業員が疲弊したり、完了した顧客応答が変更されたりすることがないように、再試行回数を制限します。
• ビジネス ダッシュボードとは別に鮮度と重複した識別子を監視します

を参照してください。 ログ API 正確な正規化ルールと 構造化されたロギングガイド より安全なイベント契約設計のために。