コーディングエージェントでこのドキュメントを使用してください

Claude Code、Codex、Cursor、または別のコーディングエージェント用の集中プロンプトパックを開き、それをここで説明するワークフローに適応させます。

このページの内容

インストールと初期化
構造化されたイベントを送信する
クエリを実行する
生産輸送境界
再試行およびクリティカルパスポリシー
統合を確認する
トラブルシューティング

Go SDK

使用する telemetry-go Go サービスからの直接同期イベントおよびクエリ呼び出しの場合。公開されたクライアントは、メソッド呼び出しごとに HTTP リクエストを作成します。コンテキスト、カスタムを公開しません。 http.Client、SDK タイムアウト、自動再試行、バッチ処理、またはフラッシュキュー。

インストールと初期化

go get github.com/telemetry-sh/telemetry-go

import (
    "os"

    telemetry "github.com/telemetry-sh/telemetry-go"
)

telemetryClient := telemetry.NewTelemetry()
telemetryClient.Init(os.Getenv("TELEMETRY_API_KEY"))

アプリケーションの起動時に 1 つのクライアントを初期化します。取り込みには書き込みスコープのキーを使用し、クエリのみの自動化には読み取りスコープのキーを使用します。

構造化されたイベントを送信する

event := map[string]interface{}{
    "event_id":      eventID,
    "route_template": "/api/projects/:id",
    "method":         "POST",
    "status_code":    201,
    "status":         "success",
    "latency_ms":     float64(time.Since(startedAt).Microseconds()) / 1000,
    "request_id":     requestID,
    "release":        os.Getenv("APP_RELEASE"),
}

response, err := telemetryClient.Log("api_request_completed", event)
if err != nil {
    log.Printf("telemetry delivery failed event_id=%s error_type=transport_error", eventID)
}
_ = response

識別子、ヘッダー、Cookie、リクエスト本文、認証情報、または顧客のプライベートコンテンツを含む未加工のリクエストパスを送信しないでください。正規化されたルートパターンと制御されたエラーカテゴリを使用します。

Go SDK は 1 つを受け入れます map[string]interface{} あたり Log 電話する。アプリケーション所有のワーカーが一括取り込みを必要とする場合は、HTTP ログ API を直接使用します。

クエリを実行する

query := `
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
`

result, err := telemetryClient.Query(query)
if err != nil {
    return fmt.Errorf("query telemetry: %w", err)
}

rows, _ := result["data"].([]interface{})
fmt.Printf("rows=%d\n", len(rows))

応答では汎用のマップとスライスが使用されます。オートメーションで値を使用する前に、タイプ、欠落しているフィールド、API ステータス、および空の結果を確認してください。を使用します。非同期クエリ API 大規模な JSON または Parquet エクスポートの場合。

生産輸送境界

現在の SDK 構造 http.Client{} タイムアウトなしで。したがって、停止したネットワークリクエストは、HTTP ハンドラーまたはワーカーの待ち時間バジェットを超えて存続する可能性があります。制限されたタイムアウト、コンテキストのキャンセル、接続プールの構成、バルクペイロード、または明示的なステータス処理が必要な場合は、サービスの既存のコントラクトに Telemetry HTTP コントラクトをラップします。 http.Client.

同じイベントスキーマと認可ルールを維持します。

client := &http.Client{Timeout: 2 * time.Second}

そのクライアントを使用して、 POST https://api.telemetry.sh/log JSON ボディには以下が含まれます table そして data。レスポンスをデコードする前にHTTPステータスを確認してください.

再試行およびクリティカルパスポリシー

一時的な接続失敗のみを再試行します。 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;

テーブル名、フィールドタイプ、単位、機密コンテンツが含まれていないことを確認します。高トラフィックのハンドラーにインストルメンテーションを接続する前に、プロセスのシャットダウンとストールした Telemetry リクエストをテストします。

トラブルシューティング

初期化エラー: 最初のメソッド呼び出しの前に、サーバー側のキーが空でないことを確認してください。
リクエストがハングする: タイムアウトとリクエストコンテキストを使用して、クライアント経由で HTTP API を使用します。
成功しない応答はデータとして表示されます。返されたステータスフィールドを調べます。現在の SDK は、HTTP の成功を強制せずに、JSON 本体をデコードします。
スキーマの拒否: フィールドの型を安定させ、null またはサポートされていない形状を削除します。
再試行後の重複行: 保持 event_id と監査しますイベントレシピの重複.

続けて Go HTTP サーバー構造化ログ、ログ API、そしてレート制限と API エラー.

ページの著者と参考資料

Telemetry 編集チームがこの説明を所有しています。製品チームは動作、例、境界をレビューします。

ドキュメントのレビュー方法

OpenTelemetry ログデータモデル

コーディング エージェントでこのドキュメントを使用してください