OpenAPI仕様
Telemetry は機械可読ファイルを公開します OpenAPI 3.1仕様 文書化された HTTP API の場合。これを使用して、エンドポイント コントラクトを検査したり、開始点として型指定されたクライアントを生成したり、API エクスプローラーを構成したり、CI でのサンプル リクエストを検証したりできます。
仕様の内容は次のとおりです。
- 構造化されたイベントの取り込み
POST /log; - 同期 SQL と
POST /query; - 非同期 JSON および Parquet エクスポート
POST /query/asyncそしてGET /query/async/{job_id}; - テーブルのリスト、スキーマの検査、保持、パーティション列、および削除。
- ダッシュボードのリスト、作成、置換更新、および削除。
- アラートのリスト、作成、部分的な更新、および削除。
- 非推奨としてマークされた従来の行削除エンドポイント。
仕様をダウンロードする
curl -fsS https://telemetry.sh/openapi.json -o telemetry-openapi.json
文書で使用されているのは、 https://api.telemetry.sh サーバーとしてサポートされており、サポートされている両方の認証ヘッダー形式について説明します。
Authorization: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
実際の API キーを仕様、ソース管理、生成されたドキュメント、サンプル、ログ、またはリポジトリにコミットされたクライアント設定に含めないでください。
文書を検証する
OpenAPI 3.1 互換のバリデーターを使用します。たとえば、ローカルにインストールされた Redocly CLI の場合は次のようになります。
npx @redocly/cli lint telemetry-openapi.json
ツールのアップグレードによってリリース動作が予期せず変更されないように、バリデーターのバージョンを CI に固定します。あいまいなスキーマに関する警告を自動的に抑制するのではなく、レビュー項目として扱います。
慎重にクライアントを生成する
生成されたクライアントは足場であり、エンドポイント ガイドの代わりとなるものではありません。本番環境で使用する前に:
- 認証と API キーのスコープを確認します。
- 接続と応答のタイムアウトを構成します。
- 限界のある指数バックオフとジッターを伴う一時的な失敗のみを再試行します。
- 取り込みを再試行するときにイベント識別子を保持します。
- 非同期クエリ ジョブに合計ポーリング期限を課します。
- テレメトリ障害によるアプリケーション ワーカーの疲労を防ぎます。
- 破壊的なテーブルと行削除メソッドを個別に確認してください。
OpenAPI スキーマは、フィールドがイベント コントラクトと SQL プロジェクションに依存するため、柔軟なイベント ペイロードとクエリ結果行を意図的にオープンエンドのままにします。 1 つのグローバル イベント形状を想定するのではなく、アプリケーション内のペイロードのドメイン タイプを生成します。
真実の情報源の境界
この仕様は、このリポジトリ内の公開 API ドキュメントを反映しています。人間が読めるページは、操作ガイダンス、正規化動作、例、および障害モードのソースとして残ります。
プラン固有のクォータは変更される可能性があり、仕様ではグローバルな数値レートとしてエンコードされません。現在のアカウントの制限については、製品と請求の設定を確認してください。 OpenAPI 文書とライブ API 応答が一致しない場合は、最小限の安全な複製をキャプチャし、それを報告してください。 [email protected];認証情報やプライベート ペイロードをログに記録することで不一致を回避しないでください。