.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);
});

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

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

傳送一個結構化事件

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

using System.Net.Http.Json;
using System.Text.Json;

var payload = new
{
    table = "api_request_completed",
    data = new
    {
        event_id = eventId,
        route_template = routeTemplate,
        method = requestMethod,
        status_code = completedStatusCode,
        status = completedStatusCode < 400 ? "success" : "error",
        latency_ms = elapsed.TotalMilliseconds,
        request_id = requestId,
        release
    }
};

try
{
    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)
    {
        RecordTelemetryDeliveryFailure("telemetry_delivery_rejected");
    }
}
catch (OperationCanceledException)
{
    RecordTelemetryDeliveryFailure("telemetry_delivery_cancelled");
}
catch (Exception error) when (error is HttpRequestException
    or JsonException or NotSupportedException
    or ArgumentException or InvalidOperationException)
{
    RecordTelemetryDeliveryFailure("telemetry_delivery_failed");
}

static void RecordTelemetryDeliveryFailure(string reason)
{
    // Diagnostics must not replace the already completed application result.
    try { Console.Error.WriteLine(reason); }
    catch { }
}

請在應用程式操作完成後執行此範例，並使用實際的路由範本、方法和 HTTP 狀態。傳送失敗不會覆蓋應用程式結果；取消權杖仍保持取消狀態。此範例只傳送一次，不記錄回應本文，也不保證資料已儲存。請透過 SQL 驗證送達。

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

執行SQL

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

下方使用獨立的 telemetry-query 用戶端。其逾時為 15 秒，資料攝取用戶端仍為三秒。呼叫端較短的取消期限仍優先生效。不要在共用用戶端已開始請求後更改其逾時。

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
);

var queryClient = httpClientFactory.CreateClient("telemetry-query");
using var queryResponse = await queryClient.SendAsync(
    queryRequest,
    queryCancellationToken
);

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

失敗和重試策略

僅重試有限的瞬時故障，例如連線錯誤、429、502、503 和 504。應用帶抖動的指數退避、限制總執行時間、尊重請求取消並重複使用相同的 event_id。不要重試未更改的架構錯誤或錯誤的憑據。

對於正常的產品分析，不要因為遙測交付失敗而將成功的客戶操作變成錯誤。對於需要永續性的計費或批准的稽核事件，請提交帶有業務事務的發件箱記錄並從後台工作人員交付。

驗證整合

傳送已知的成功、失敗、重試、取消和超時裝置，然後檢查最近的行：

SELECT timestamp_utc, event_id, route_template, method, status_code, status, latency_ms
FROM api_request_completed
ORDER BY timestamp_utc DESC
LIMIT 20;

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

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

讓程式設計代理使用這篇文件