JavaScript・TypeScript SDK
を使用します。 telemetry-sh サーバー側の JavaScript または TypeScript のパッケージ。現在のクライアントは即時公開します log そして query ESM ビルドと CommonJS ビルドの両方を介して呼び出します。バックグラウンド イベント キューを維持したり、フラッシュ メソッドを公開したりしません。
ブラウザ コードでパッケージを初期化しないでください。Telemetry API キーはチームへのアクセスを許可するものであり、クライアント バンドルに同梱してはなりません。
インストールと初期化
npm install telemetry-sh
ESモジュール:
import telemetry from "telemetry-sh";
telemetry.init(process.env.TELEMETRY_API_KEY);
共通JS:
const telemetry = require("telemetry-sh");
telemetry.init(process.env.TELEMETRY_API_KEY);
電話をかける init サーバーまたはワーカーの起動時に 1 回。取り込みのみのコードには書き込みスコープのキーを使用し、レポートまたはクエリのみの自動化には読み取りスコープのキーを使用します。
1 つの構造化イベントを送信する
アプリケーションが配信の成功または失敗を監視する必要がある場合は、返された Promise を待ちます。
const eventId = crypto.randomUUID();
try {
await telemetry.log("api_request_completed", {
event_id: eventId,
route_template: "/api/projects/:id",
method: "POST",
status_code: 201,
status: "success",
latency_ms: 184,
environment: process.env.APP_ENV,
release: process.env.APP_RELEASE,
});
} catch (error) {
console.error("Telemetry delivery failed", {
event_id: eventId,
error_type: "telemetry_delivery_failed",
});
}
生の URL、リクエスト本文、Cookie、認証ヘッダー、シークレット、プロンプト、および顧客のプライベート コンテンツをペイロードに含めないようにしてください。安定したルート テンプレート、内部識別子、および制御されたエラー カテゴリを使用します。
バッチを送信する
log 互換性のあるオブジェクトの配列を受け入れます。バッチによりリクエストのオーバーヘッドは軽減されますが、1 つの失敗したリクエストによって影響を受けるイベントの数は増加します。
await telemetry.log("job_completed", [
{
event_id: "evt_job_101",
job_name: "invoice_sync",
status: "success",
duration_ms: 912,
},
{
event_id: "evt_job_102",
job_name: "invoice_sync",
status: "failed",
duration_ms: 2401,
error_type: "provider_timeout",
},
]);
JavaScript クライアントは、指定された配列をすぐに送信します。呼び出しは内部バッチに収集されません。アプリケーションが独自のバッファを導入する場合は、「」で説明されているように、そのサイズ、経過時間、再試行バジェット、およびシャットダウン動作を制限します。 バッチ処理とバックプレッシャー.
型指定されたクエリを実行する
type ReliabilityRow = {
requests: number;
route_template: string;
};
const result = await telemetry.query<ReliabilityRow>(`
SELECT
route_template,
COUNT(*) AS requests
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template
ORDER BY requests DESC
`);
for (const row of result.data) {
console.log(row.route_template, row.requests);
}
ジェネリック型は、TypeScript の結果行を記述します。実行時には SQL の結果は検証されません。オートメーションでクエリを使用する前に、空の結果と予期しない null を確認してください。
SDK query メソッドは対話型クエリ エンドポイントを呼び出します。文書化された HTTP フローを使用して、 非同期 JSON または Parquet エクスポート SDK オプションが非同期ジョブを作成してポーリングすると仮定するのではなく、
配信動作と再試行
現在のパッケージは次のことを実行します。 fetch それぞれのリクエスト log または query 電話する。 SDK タイムアウト、自動再試行、永続キュー、フラッシュ ライフサイクルは追加されません。
取り込みを再試行する場合:
- 一時的なトランスポート障害のみを再試行します。
429,502,503、そして504. - 論理イベントの再利用
event_id. - ジッターを伴う指数バックオフを適用します。
- 試行回数と経過時間を制限します。
- テレメトリがそのワークフローの永続性契約の一部として明示的に含まれていない限り、完了した顧客アクションを失敗にしないでください。
削除できない請求イベントまたは承認された監査イベントには、アプリケーションが所有する耐久性のある送信ボックスを使用します。参照 イベント配信と冪等性.
統合を確認する
合成の成功イベントと失敗イベントを送信した後、次を実行します。
SELECT
timestamp_utc,
event_id,
route_template,
status,
latency_ms,
error_type
FROM api_request_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
テーブル名、フィールド タイプ、NULL 動作、UTC タイムスタンプ、および機密フィールドが存在しないことを確認します。次に、ダッシュボードまたはアラートを作成する前に、再試行、タイムアウト、シャットダウン ブランチをテストします。
トラブルシューティング
API key is not initialized: 電話をかけるtelemetry.init最初の SDK メソッドの前。401: 欠落しているキー、無効なキー、または取り消されたキーを置き換えます。403: 必要なスコープのキーを使用します。400: テーブル名、JSON の形状、およびフィールド タイプの互換性を検査します。変更せずに再試行しないでください。429または5xx: イベントを複数回安全に配信できる場合は、制限付き再試行ポリシーを使用します。- プロセスは配信前に終了します。即時の呼び出しを追跡して待機するか、シャットダウン前に必要なイベントを保持します。 SDK フラッシュ キューはありません。
続けて、 ログ API, レート制限と API エラー、そして Node.js と Express の統合.