.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、速率限制和错误 和 批处理和关闭。