本文へ移動
Telemetry
ドキュメントを見る

APIリファレンス更新日: 2026年10月1日2 最小読み取り時間

コーディング エージェントでこのドキュメントを使用してください

Claude Code、Codex、Cursor、または別のコーディング エージェント用の集中プロンプト パックを開き、それをここで説明するワークフローに適応させます。

このページの内容
  1. 受け入れられるデータ形状
  2. サーバー側の正規化
  3. cURLでの使用例
  4. JavaScript SDK の使用
  5. 一括ロギング
  6. よくあるエラー

ログ

これらの例では、予約済みのサンプルテーブル telemetry_quickstart に架空のデータを使います。API の動作を確認するもので、アプリの計測が完了したことを示すものではありません。アプリでは処理に合ったテーブルを選び、実際の操作からイベントを送信してください。

ログ API は、イベントを Telemetry に取り込む方法です。アプリケーション イベント、ユーザー アクティビティ、メトリクス、または構造化ログに使用します。

Telemetry は保存前にテーブル名とタイムスタンプを正規化し、null 値、空のオブジェクト、空の配列を削除します。

投稿 https://api.telemetry.sh/log

ヘッダー

名前 タイプ 説明
コンテンツタイプ 文字列 アプリケーション/json
認可 文字列 API キー (生のキーまたは Bearer <key>

本体

名前 タイプ 説明
テーブル 文字列 宛先テーブル名。 空白はアンダースコアに変換され、英字は小文字になります。正規化後に使用できるのは、小文字のASCII英字、数字、および _ 許可されています。
データ JSON イベントペイロード。サポートされるシェイプは、JSON オブジェクト、JSON オブジェクトの配列、JSON オブジェクトにデコードされる JSON 文字列、または JSON オブジェクトとデコードされる JSON 文字列を混合した配列です。 JSON オブジェクト。

受け入れられるデータ形状

API は以下を受け入れます:

  • 単一の JSON オブジェクト
  • JSON オブジェクトの配列
  • それ自体が JSON オブジェクトに解析される JSON 文字列
  • JSON オブジェクトと、JSON オブジェクトに解析される JSON 文字列を含む配列

API は以下を拒否します。

  • 最上位の数値、ブール値、および null
  • 配列、数値、ブール値などの非オブジェクト値にデコードされる JSON 文字列 null
  • 非オブジェクト、非文字列項目を含む配列
  • 非オブジェクト値にデコードされる JSON 文字列を含む配列
  • JSON ペイロードが 64 レベルより深くネストされている
  • 空のイベントバッチ、data: []

サーバー側の正規化

いつ data JSON オブジェクトが含まれている場合、Telemetry は取り込み前に次のルールを適用します。

  • 追加します timestamp 現在の UTC 時刻がない場合はそれに置き換えます
  • もし timestamp です null、現在の UTC 時間に置き換えます
  • もし timestamp Unix タイムスタンプの整数または数値文字列であり、Unix 秒として解釈され、RFC 3339 に変換されます。
  • 削除します timestamp_utc 存在する場合
  • null、空のオブジェクト、空の配列を再帰的に削除します。""、0、false は保持します。

例:

  • Telemetry Events になる telemetry_events
  • timestamp: 1700000000 RFC 3339 タイムスタンプ文字列になります
  • { "user": "alice", "meta": null } なしで保存されます meta

cURLでの使用例

Uber 乗車データを という名前のテーブルに送信するには telemetry_quickstart cURL を使用すると、次のコマンドを使用できます。

curl -X POST https://api.telemetry.sh/log \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "table": "telemetry_quickstart",
    "data": {
      "city": "paris",
      "price": 42
    }
  }'

JavaScript SDK の使用

開発者エクスペリエンスを向上させるために、SDK を使用することをお勧めします。 JavaScript SDK の使用方法の例を次に示します。

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

await telemetry.log("telemetry_quickstart", {
  city: "paris",
  price: 42
});

一括ロギング

オブジェクトの配列を渡してイベントを一括取り込むこともできます。これは、API へのリクエストの数を制限するのに役立ちます。たとえば、次の代わりに:

await telemetry.log("telemetry_quickstart", { a: 1 })

次のことができます:

await telemetry.log("telemetry_quickstart", [{a: 1}, {a: 2}])

これにより、データが 2 行として取り込まれます。

よくあるエラー

  • 400 Bad Request JSON ボディが無効な場合
  • 400 Bad Request 正規化後にテーブル名に無効な文字が含まれている場合
  • 400 Bad Request もし data サポートされている形状ではありません
  • data が空の配列の場合は、400 Bad Request とエラーコード empty_batch を返します。少なくとも1件のイベントを送信してください。ペイロードを小さくしても解決しません。
  • 400 Bad Request JSON 文字列が入っている場合 data 非オブジェクト値にデコードします
  • 400 Bad Request Unix タイムスタンプがサポートされている範囲外の場合
  • 401 Unauthorized API キーが見つからないか無効な場合
  • 429 Too Many Requests API キーがゲートウェイのレート制限を超えた場合

関連機能

安定したイベント名、型指定されたフィールド、プライバシーがレビューされたコンテキストをキャプチャします。

ページの著者と参考資料

Telemetry 編集チームがこの説明を所有しています。製品チームは動作、例、境界をレビューします。

ドキュメントのレビュー方法