ログ

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

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

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

ヘッダー

本体

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

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 乗車データを という名前のテーブルに送信するには uber_rides cURL を使用すると、次のコマンドを使用できます。

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

JavaScript SDK の使用

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

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

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

一括ロギング

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

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

次のことができます:

telemetry.log("uber_rides", [{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 キーがゲートウェイのレート制限を超えた場合