Ruby HTTP 統合
Telemetry の HTTP API は、Ruby の標準ライブラリで動作します。これにより、タイムアウト、再試行、および耐久性のポリシーがアプリケーションの制御下に残りながら、依存関係の表面が小さく保たれます。
イベントを設定して送信する
require "json"
require "net/http"
require "uri"
api_key = ENV.fetch("TELEMETRY_API_KEY")
uri = URI("https://api.telemetry.sh/log")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = api_key
request["Content-Type"] = "application/json"
request.body = {
table: "api_request_completed",
data: {
event_id: "evt_request_101",
route_template: "/api/projects/:id",
method: "GET",
status_code: 200,
status: "success",
latency_ms: 184
}
}.to_json
response = Net::HTTP.start(
uri.hostname,
uri.port,
use_ssl: true,
open_timeout: 2,
read_timeout: 10
) { |http| http.request(request) }
unless response.is_a?(Net::HTTPSuccess)
raise "Telemetry log failed with HTTP #{response.code}"
end
Telemetry が追加 timestamp_utc。キーをサーバー側に保持し、資格情報、Cookie、ヘッダー、リクエスト パラメータ、生の例外メッセージ、またはプライベートな顧客コンテンツを送信しないでください。
バッチを送信する
セット data 配列に:
request.body = {
table: "job_completed",
data: [
{
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"
}
]
}.to_json
バッチを制限し、スキーマ互換性を維持します。アプリケーション所有のキューには、最大深さ、最大経過時間、オーバーフロー ルール、再試行バジェット、およびシャットダウン期限も必要です。
SQLを実行します
読み取りスコープのキーを使用します。
uri = URI("https://api.telemetry.sh/query")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = api_key
request["Content-Type"] = "application/json"
request.body = {
query: <<~SQL
SELECT
route_template,
COUNT(*) AS requests,
ROUND(AVG(latency_ms), 0) AS avg_latency_ms
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template
ORDER BY requests DESC;
SQL
}.to_json
response = Net::HTTP.start(
uri.hostname,
uri.port,
use_ssl: true,
open_timeout: 2,
read_timeout: 30
) { |http| http.request(request) }
raise "Telemetry query failed with HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
result = JSON.parse(response.body)
Array(result["data"]).each do |row|
# Validate expected keys and nulls before using the row.
end
を使用します。 非同期クエリ API 大規模な JSON または Parquet エクスポートの場合。
再試行および失敗ポリシー
Net::OpenTimeout 接続を確立できなかったことを意味します。 Net::ReadTimeout 応答が失われる前にサーバーが要求を受け入れた可能性があるため、あいまいです。
一時的なネットワーク障害のみを再試行します。 429, 502, 503、そして 504。論理イベントの再利用 event_id、ジッターを伴う指数バックオフを適用し、合計経過時間を制限します。変更されていない無効なリクエストを再試行しないでください。
通常の分析では、テレメトリの停止によって、完了した顧客対応が置き換えられるべきではありません。損失が許容できない場合は、アプリケーション所有の耐久性のある送信ボックスに請求イベントや承認された監査イベントを保持します。
確認とトラブルシューティングを行う
合成成功イベントと失敗イベントを送信し、最新の行をクエリし、検査します。 GET /tables/<table>/schema.
KeyError: サーバーまたはワーカー環境で API キーを構成します。401または403: キーを置き換えるか、そのスコープを修正してください。400: テーブルの命名、JSON の形状、およびフィールド タイプの互換性を検査します。- タイムアウト: ペイロードを出力せずに、ワークフローの文書化された再試行またはフォールバック ポリシーを適用します。
- プロセスのシャットダウン: 直接の HTTP 呼び出しにはフラッシュするバックグラウンド キューがありません。必要な呼び出しを追跡するか、最初にイベントを永続化します。
を参照してください。 Railsの統合, ログ API, イベント配信ガイド、そして 取り込みのトラブルシューティング.