JavaScript・TypeScript SDK

サーバー側の JavaScript または TypeScript では telemetry-sh パッケージを使います。ESM と CommonJS のどちらのビルドでも、log と query は呼び出し時にリクエストを送信します。バックグラウンドのイベントキューやフラッシュメソッドはありません。

以下の例ではサーバー側でパッケージを初期化します。匿名トライアル、read、read-and-write のキーをブラウザのバンドルに含めないでください。イベントを送信するだけのクライアントには Ingest only キーを使えます。公開ビルドに含める前に権限を確認してください。結果はダッシュボードで確認するか、信頼できるサーバーで別の読み取り用キーを使って確認してください。API キーと認証を参照してください。

以下の送信例は架空の値を使って SDK のデータ送信を確認します。telemetry_quickstart テーブルに保存してください。この例だけではアプリケーションの計装を確認できません。実際の利用では、選んだアプリケーション操作が完了した時点で観測値を記録し、その処理用のテーブルを使ってください。

インストールと初期化

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 つの構造化イベントを送信する

アプリケーションが配信の成功または失敗を監視する必要がある場合は、返された Promise を待ちます。

const eventId = crypto.randomUUID();

try {
  await telemetry.log("telemetry_quickstart", {
    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("telemetry_quickstart", [
  {
    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 telemetry_quickstart
  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 メソッドは対話型クエリのエンドポイントを呼び出します。非同期 JSON または Parquet エクスポートには、ドキュメントに記載された HTTP の手順を使ってください。SDK のオプションで非同期ジョブの作成やポーリングができると想定しないでください。

配信動作と再試行

現在のパッケージでは、fetch リクエストを log または query の呼び出しごとに一度送信します。SDK 独自のタイムアウト、自動再試行、永続キュー、フラッシュ処理はありません。

取り込みを再試行する場合:

1. 一時的なトランスポート障害のみを再試行します。 429, 502, 503、そして 504.
2. 論理イベントの再利用 event_id.
3. ジッターを伴う指数バックオフを適用します。
4. 試行回数と経過時間を制限します。
5. テレメトリがそのワークフローの永続性契約の一部として明示的に含まれていない限り、完了した顧客アクションを失敗にしないでください。

欠落を許容できない請求イベントや、記録が承認された監査イベントには、アプリケーションが管理する永続的な送信キューを使ってください。イベント配信と冪等性を参照してください。

統合を確認する

合成の成功イベントと失敗イベントを送信した後、次を実行します。

SELECT
  timestamp_utc,
  event_id,
  route_template,
  status,
  latency_ms
FROM telemetry_quickstart
ORDER BY timestamp_utc DESC
LIMIT 20;

テーブル名、フィールド タイプ、NULL 動作、UTC タイムスタンプ、および機密フィールドが存在しないことを確認します。次に、ダッシュボードまたはアラートを作成する前に、再試行、タイムアウト、シャットダウン ブランチをテストします。

トラブルシューティング

• API key is not initialized: 最初の SDK メソッドを使う前に telemetry.init を呼び出してください。
• 401: 欠落しているキー、無効なキー、または取り消されたキーを置き換えます。
• 403: 必要なスコープのキーを使用します。
• 400: テーブル名、JSON の形状、およびフィールド タイプの互換性を検査します。変更せずに再試行しないでください。
• 429 または 5xx: イベントを複数回安全に配信できる場合は、制限付き再試行ポリシーを使用します。
• プロセスは配信前に終了します。即時の呼び出しを追跡して待機するか、シャットダウン前に必要なイベントを保持します。 SDK フラッシュ キューはありません。

続けて、 ログ API, レート制限と API エラー、そして Node.js と Express の統合.

• Next.js App Router のレシピ