.NET HTTP 整合

Telemetry 不發布本機 .NET SDK。當 ASP.NET Core 服務、工作執行緒或計劃作業需要結構化事件引入時，透過應用程式擁有的 HttpClient 或 IHttpClientFactory 設定使用 HTTP API。

應用程式仍然負責連線重用、超時、重試、序列化、取消以及可觀測性故障是否可能影響客戶工作流程。

設定命名客戶端

builder.Services.AddHttpClient("telemetry", client =>
{
    client.BaseAddress = new Uri("https://api.telemetry.sh");
    client.Timeout = TimeSpan.FromSeconds(3);
});

從 IHttpClientFactory 解析客戶端，而不是為每個事件建置新的 HttpClient。將 Telemetry 金鑰儲存在服務的現有秘密管理器中，並使用單獨的寫入和讀取範圍金鑰，其中執行時支援攝取和查詢。

傳送一個結構化事件

在瞭解最終應用程式結果後，建置型別化、列入白名單的有效負載：

using System.Net.Http.Json;

var payload = new
{
    table = "api_request_completed",
    data = new
    {
        event_id = eventId,
        route_template = "/api/projects/:id",
        method = "POST",
        status_code = 201,
        status = "success",
        latency_ms = elapsed.TotalMilliseconds,
        request_id = requestId,
        release
    }
};

using var request = new HttpRequestMessage(HttpMethod.Post, "/log")
{
    Content = JsonContent.Create(payload)
};
request.Headers.TryAddWithoutValidation("Authorization", telemetryApiKey);

var client = httpClientFactory.CreateClient("telemetry");
using var response = await client.SendAsync(request, cancellationToken);

if (!response.IsSuccessStatusCode)
{
    RecordDeliveryFailure((int)response.StatusCode, eventId);
}

使用路由範本、穩定的內部識別符號和受控的錯誤類別。請勿序列化標頭、cookie、憑據、請求正文、繫結 SQL 值、堆疊追蹤、提示、生成的內容或不受限制的異常訊息。

執行SQL

使用更長的、單獨限定的查詢期限和讀取範圍的鍵：

var queryPayload = new
{
    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
        """
};

using var queryRequest = new HttpRequestMessage(HttpMethod.Post, "/query")
{
    Content = JsonContent.Create(queryPayload)
};
queryRequest.Headers.TryAddWithoutValidation(
    "Authorization",
    telemetryReadApiKey
);

using var queryResponse = await client.SendAsync(
    queryRequest,
    queryCancellationToken
);

檢查HTTP狀態以及回應status、data和key_order欄位。空結果是有效結果，不應被視為傳輸錯誤。

失敗和重試策略

僅重試有限的瞬時故障，例如連線錯誤、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;

確認每個邏輯結果的一個終端行、穩定欄位型別、預期單位、UTC 時間戳以及不存在敏感內容。在生產量啟用路徑之前，執行 Telemetry 超時和正常工作執行緒關閉。

繼續使用 .NET 和 Serilog 整合、日誌API、速率限制和錯誤 和 批次處理和關閉。