クイックスタート
JSON イベントを Telemetry に送信し、SQL でクエリします。このクイックスタートでは、イベントを 1 件送信し、Telemetry が作成したテーブルを確認してクエリを実行します。
以下の例では、予約済みの telemetry_quickstart テーブルに架空のデータを送ります。送信とクエリの経路を確認するためのもので、アプリの連携を完了するには実際の処理を実行し、その処理で記録したイベントをクエリしてください。
Telemetry が内部でどのように動作するかについて詳しく知りたい場合は、こちらをご覧ください。 Telemetry アーキテクチャ ドキュメント 詳細な概要については、 API 呼び出しを計測することで OpenAI コストを追跡するなど、より詳細な使用例については、ガイドを参照してください。 OpenAI コストの追跡.
タスクごとのパスを短くしたいですか?フォローしてください:
API キーを取得する
ホームページの設定プロンプトから anon_… キーを取得します。アカウントなしでイベントを送信し、クエリできます。アカウントがある場合は、チーム設定 → API キーの read-and-write キーを使います。
匿名クエリは最初のイベントから24時間利用できます。7日以内にアカウントを作成すると、イベントと同じキーを保持できます。同じブラウザーでは登録時に試用を検出します。別のブラウザーでは、匿名 API キーをお持ちですか?を選び、キーを貼り付けてデータを探すを押してから登録します。既存ユーザーはデータを保持でキーを復元してからログインできます。イベントのない試用は作成から7日で期限切れになります。
Telemetryをインストールする
このチュートリアルでは JavaScript を使用します。Python SDK、Go SDK、Rust SDK、Ruby SDK、PHP SDK、または cURL も使用できます。
npm install telemetry-sh
いくつかのデータをログに記録する
Telemetry は、データが記録されるときにテーブルを自動的に作成します。次の例では、合成乗車データをテーブルという名前のテーブルに記録します。 telemetry_quickstart。 Telemetry はテーブルとそのスキーマを作成します。 city そして price;すべての行も受け取ります timestamp_utc.
import telemetry from "telemetry-sh";
telemetry.init("YOUR_API_KEY");
await telemetry.log("telemetry_quickstart", {
city: "paris",
price: 42
});
UI でデータを探索する
まず、登録せずにイベントをクエリして確認します。
const result = await telemetry.query("SELECT city, price FROM telemetry_quickstart WHERE city IS NOT NULL LIMIT 10");
console.log(result);
グラフ、ダッシュボード、アラートを使うには、アカウントを作成してデータを保持します。既存のキーは引き続き使え、登録後はイベントのあるワークスペースが開きます。アカウントがある場合は試用を連携します。
Telemetryの操作フロー図。テーブル、SQLクエリ、グラフから、共有ダッシュボードまたはアラートへ進みます。
この結果を保存する は、案内に表示されたダッシュボードにクエリ結果を保存します。その他の操作は、以下のダッシュボードとアラートの手順を参照してください。
探索ビュー
探検する タブでは、SQL を書かずにイベントを絞り込み、グラフや表を作成できます。
探索は 1 つのテーブルを対象にします。開く手順は次のとおりです。
- Goをあなたのチームに。
- 開く テーブル.
- テーブルを選択します。
- を開きます 探検する その表ページのタブをクリックします。
ルート形状:
/team/{team}/table/{table}?tab=explore
- グラフの種類を選択します (
Samples,Table,Line,Bar、またはStacked Area). - 時間範囲を設定し、1 つ以上のフィルターを追加します。
- 含める列を選択します(次のようなネストされたフィールドも含む:
data.toolName). - クリック 実行 実行して結果をレンダリングします。
ヒント: コントロールはドラフト状態です。クリックした場合にのみ結果が更新されます 実行.
仮説的なデータセットの例 (架空)
以下の Explore の例では、ログインしたことを前提としています。 総合テスト イベント (実際のユーザーデータはありません) 次のような構造になります。
{
"timestamp_utc": "2026-02-27T12:00:00.000Z",
"event": "tool_call",
"status": "success",
"data": {
"toolName": "smart_avantis_buy",
"args": {
"symbol": "BTC-USD",
"amountUsd": 2500
}
}
}
上の例は保存後の行を示しています。telemetry_quickstart にイベントを送信するときは timestamp_utc を省略してください。Telemetry は timestamp からこの列を生成します(省略した場合は現在の UTC 時刻が使われます)。上の日付は説明用です。過去のイベントを送信する場合は timestamp を設定し、Explore でその時刻を含む範囲を選択してください。Log API の正規化ルールを参照してください。
例 1: ツール呼び出しをフィルターし、生の行を検査する
上記の架空のスキーマを使用して、Explore でこれを試してください。
- グラフの種類を次のように設定します
Samples. - フィルターを追加します:
event = tool_call. - フィルターを追加します:
data.toolName = smart_avantis_buy. - クリック 実行.
URL テンプレート (プレースホルダーを置き換えます):
/team/{team}/table/telemetry_quickstart?tab=explore&graphType=samples&f=event:=:tool_call&f=data.toolName:=:smart_avantis_buy
例 2: チャート ビューとテーブル ビューの比較
同じフィルターを使用すると、次のようになります。
- 選択
Lineそしてクリックしてください 実行. - に切り替えます
Tableそしてクリックしてください 実行 またまた。
これにより、傾向と正確な値の両方を簡単に検証できます。
例 3: すべての列モードのネストされた列
保管するとき All columns Explore で選択すると、生成された SQL は列を明示的に列挙するため、ネストされたフィールドが含まれます。
生成された SQL 形状の例:
SELECT "timestamp_utc", "event", "data.toolName", "data.args.symbol"
FROM "your_table"
WHERE timestamp_utc >= now() - INTERVAL '7 days'
ORDER BY timestamp_utc DESC
LIMIT 200
ダッシュボード
ダッシュボードを使用すると、Explore チャート/テーブルとクエリ結果を 1 つの共有ビューに固定できます。
ダッシュボードを作成して使用するには:
- 任意のテーブルを開く 探検する または、保存されたクエリ結果を開きます。
- ダッシュボード名の保存ボタン、または この結果を保存する で直接保存します。
- ダッシュボードがない場合は スターター ダッシュボードを作成して保存する を使います。
- 複数のダッシュボードがある場合は ダッシュボードの選択 で保存先とウィジェットのタイトルを指定します。
ダッシュボードのルート形状:
/team/{team}/dashboard/{dashboardSlug}
ダッシュボードを使用して、チームの主要なシグナル (レイテンシー、エラー率、コスト、コンバージョン指標) を 1 か所にまとめます。
アラートの作成
グラフまたはクエリ結果を取得したら、それを Telemetry UI でアラートに変換できます。
- テーブルを開く 探検する またはクエリを実行します 結果/グラフ 見る。
- クリック モニター結果.
- 条件(集計、最後の N ポイント、比較、しきい値)を設定します。
- チェック間隔と 1 人以上の電子メール受信者を設定します。
- クリック アラートを作成 保存するために。にリダイレクトされます
/team/{team}/alert/{alertSlug}ステータスと履歴を監視します。
ヒント: 離れる 最後のデータポイントを無視する 最新のバケットは不完全であることが多いため、バケット化された時系列に対して有効になります。
完全なチュートリアルについては、を参照してください。 アラートガイド.
インタラクティブなインライン例
例 1: レイテンシースパイク検出器 (p95)
Explore でテーブル上でこれを試してください。 latency_ms:
- グラフの種類を次のように設定します
Line. - 集計を次のように設定します
p95メトリック付きlatency_ms. - クリック 実行をクリックしてから、 モニター結果.
- 状態:
p95 of last 5 data points is Greater than 850. - 間隔:
Every minute、受信者の電子メールを追加します。
URL テンプレート (プレースホルダーを置き換えます):
/team/{team}/table/{table}?tab=explore&graphType=line&agg=p95&metric=latency_ms&time=7d
例 2: エラーバースト検出器 (カウント)
数値型の status_code フィールドを持つ HTTP リクエストのイベントテーブルで、サーバーエラー(HTTP 5xx)を数えます。前のツール呼び出し例の status は文字列なので、このフィルターには使えません。
- Explore で
status_code >= 500とstatus_code < 600の両方を満たす行を抽出します。 - 集計を含む折れ線グラフを使用する
count. - クリック モニター結果.
- 状態:
Average of last 3 data points is Greater than 20.
これにより、単一の不良バケットからのノイズを回避しながら、短いエラー バーストを捕捉します。
例 3: 静かなトラフィック検出器 (しきい値を下回る)
これを cron ジョブ、キュー、または取り込みパイプラインに使用します。
- 時間の経過に伴うイベント量のクエリまたはグラフ。
- 比較を含むアラートを作成する
Less than. - 状態:
Sum of last 10 data points is Less than 50.
これがトリガーされる場合は、通常、顧客が気づく前にデータの流れが停止したことを意味します。
コードベースと統合する
クエリ API を使うと、この架空の乗車イベントをコードから取得できます。製品や社内ダッシュボードで使うときは、サンプルのテーブルを、実際に実行した処理で記録したイベントのテーブルに置き換えてください。
const results =
await telemetry.query(`
SELECT
city,
AVG(price)
FROM
telemetry_quickstart
WHERE city IS NOT NULL
GROUP BY
city
`);
閲覧する SQL レシピ ライブラリ APIエラー、レイテンシのパーセンタイル、ジョブの再試行、LLMコスト、コンバージョン、リテンション、ハートビート欠落を分析するとき.
これらのレシピの背後にあるアーキテクチャと分析モデルについては、次の手順に進みます。 可観測性とイベント分析のための SQL。 取り込みからSQL結果までの完全な合成ワークフローを実行するには、 エンドツーエンドの SaaS 可観測性デモ.