Rust SDK
の telemetry-sh crate は、イベントの取り込みとインタラクティブなクエリ用の小さなブロック クライアントを提供します。各メソッドはブロッキングを構築します。 reqwest クライアントにアクセスし、1 つの HTTP リクエストを送信します。クレートは、非同期クライアント、構成可能なタイムアウト、再試行ポリシー、バッチ キュー、またはフラッシュ メソッドを公開しません。
インストールと初期化
[dependencies]
telemetry-sh = "1.0.0"
serde_json = "1.0"
uuid = { version = "1", features = ["v4"] }
use std::env;
use telemetry_sh::Telemetry;
let mut telemetry = Telemetry::new();
telemetry.init(env::var("TELEMETRY_API_KEY")?);
キーをサーバー側の構成に保持します。取り込み専用サービスには書き込みスコープのキーを使用し、レポートまたはクエリ自動化には読み取りスコープのキーを使用します。
構造化されたイベントを送信する
use serde_json::json;
use uuid::Uuid;
let event_id = Uuid::new_v4().to_string();
let event = json!({
"event_id": event_id,
"job_name": "invoice_sync",
"status": "success",
"duration_ms": 912,
"attempt": 1,
"release": env::var("APP_RELEASE").ok(),
});
match telemetry.log("job_completed", &event) {
Ok(response) => println!("telemetry response: {response}"),
Err(error) => eprintln!(
"telemetry delivery failed event_id={} error_type=transport_error: {}",
event_id,
error
),
}
認証情報、ヘッダー、Cookie、生のリクエスト本文、プロンプト、例外テキスト、および顧客のプライベート コンテンツは避けてください。管理されたカテゴリと安定した内部識別子を好みます。
SDK は 1 つを受け入れます serde_json::Value。 配列値はLog APIの一括ペイロードを表せますが、バッチ処理を本番配信契約に含める前に、使用するcrateとAPIの正確な動作をテストしてください.
SQLを実行します
let query = r#"
SELECT
status,
COUNT(*) AS jobs
FROM job_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY status
ORDER BY jobs DESC
"#;
let result = telemetry.query(query)?;
let rows = result
.get("data")
.and_then(|value| value.as_array())
.cloned()
.unwrap_or_default();
println!("query rows: {}", rows.len());
結果は動的 JSON になります。オートメーションで値を使用する前に、タイプ、null、API ステータス、および空の結果を検証してください。を使用します。 非同期クエリ API 長時間実行される JSON または Parquet エクスポートの場合は直接。
ブロッキングとタイムアウトの動作
どちらのクレートメソッドも使用します reqwest::blocking。ブロッキング作業を分離せずに、非同期実行スレッドまたは遅延の影響を受けやすい要求パスでこれらを直接呼び出さないでください。
公開されたクレートは、HTTP クライアントを公開したり、タイムアウトを構成したりしません。サービスでコンテキストのキャンセル、接続の再利用、固定タイムアウト、ステータス固有の再試行、または永続キューが必要な場合は、文書化された HTTP リクエストをアプリケーション所有の reqwest::Client 代わりに。
トランスポート ポリシーを制限して、テレメトリの停止によってワーカー スレッドが使い果たされないようにします。
再試行およびシャットダウンポリシー
一時的な接続失敗のみを再試行します。 429, 502, 503、そして 504。ジッターのある指数関数的バックオフを使用し、合計時間を制限し、同じ時間を保持します event_id。変更されていない無効なリクエストを再試行しないでください。
SDK には、フラッシュするバックグラウンド キューがありません。成功した log return は、即時のリクエストがデコード可能な応答を生成したことを意味します。 1 回限りの保存を保証するものではありません。プロセスがシャットダウンする前に、必要な呼び出しを追跡したり、永続的なイベントをアプリケーション所有の送信ボックスに保持したりできます。
通常の分析では、テレメトリが利用できないために、完了した顧客アクションを失敗にしないでください。レビュー イベント配信と冪等性.
統合を確認する
既知の成功フィクスチャと失敗フィクスチャを送信し、クエリを実行します。
SELECT timestamp_utc, event_id, job_name, status, duration_ms, error_type
FROM job_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
テーブルの名前、フィールドの種類、単位、NULL の動作、重複したイベント ID、機密データの境界を確認します。アラートのイベントに依存する前に、接続タイムアウトと正常なシャットダウンを実行してください。
トラブルシューティング
- キー不足エラー: 空ではないサーバー側環境値からクライアントを初期化します。
- ランタイムの停止: ブロッキング コールを非同期エグゼキューター スレッドから移動するか、アプリケーション所有の非同期 HTTP クライアントを使用します。
- エラー応答は JSON としてデコードされます。返されたステータスとメッセージを検査します。クレートは呼びません
error_for_status. - 重複行: 保持
event_idネットワーク全体の試行と監視 重複したID. - 大規模なエクスポート: HTTP 非同期クエリの開始、ステータス、ダウンロード フローを使用します。
続けて、 ログ API, 取り込みのトラブルシューティング、そして 生産計測チェックリスト.