Integración .NET HTTP

Telemetry no publica un .NET SDK nativo. Utilice HTTP API a través de una configuración HttpClient o IHttpClientFactory propiedad de la aplicación cuando un servicio, trabajador o trabajo programado de ASP.NET Core necesite una ingestión de eventos estructurados.

La aplicación sigue siendo responsable de la reutilización de la conexión, los tiempos de espera, los reintentos, la serialización, la cancelación y si una falla de observabilidad puede afectar el flujo de trabajo del cliente.

Configurar un cliente con nombre

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

Resuelva el cliente desde IHttpClientFactory en lugar de construir un nuevo HttpClient para cada evento. Almacene la clave Telemetry en el administrador secreto existente del servicio y use claves independientes de solo ingesta y de solo lectura donde el tiempo de ejecución admita tanto la ingesta como la consulta.

Enviar un evento estructurado

Cree una carga útil escrita y incluida en la lista de permitidos después de conocer el resultado final de la aplicación:

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 { }
}

Ejecuta este ejemplo después de completar la operación. Usa su ruta, método y estado HTTP reales. Los fallos de envío no reemplazan el resultado de la aplicación; el token de cancelación sigue cancelado. Envía una vez, no registra el cuerpo de la respuesta y no garantiza el almacenamiento. Verifica la entrega con SQL.

Utilice plantillas de ruta, identificadores internos estables y categorías de error controladas. No serialice encabezados, cookies, credenciales, cuerpos de solicitudes, valores SQL vinculados, seguimientos de pila, mensajes, contenido generado ni mensajes de excepción sin restricciones.

Ejecute SQL

Utilice una fecha límite de consulta más larga y delimitada por separado y una clave de ámbito de lectura:

Usa el cliente separado telemetry-query que aparece abajo. Su tiempo límite es de 15 segundos; el de ingestión sigue siendo de tres segundos. Un plazo de cancelación más corto del llamador tiene prioridad. No cambies el tiempo límite de un cliente compartido después de iniciar una solicitud.

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

Verifique el estado de HTTP y los campos de respuesta status, data y key_order. Un resultado vacío es un resultado válido y no debe tratarse como un error de transporte.

Política de error y reintento

Reintente solo fallas transitorias limitadas, como errores de conexión, 429, 502, 503 y 504. Aplique un retroceso exponencial con fluctuación, limite el tiempo total transcurrido, respete la cancelación de solicitudes y reutilice el mismo event_id. No vuelva a intentar un error de esquema sin cambios o una credencial incorrecta.

Para el análisis normal del producto, no convierta una operación exitosa del cliente en un error porque falló la entrega de telemetría. Para eventos de facturación o auditoría aprobados que requieren durabilidad, confirme un registro de bandeja de salida con la transacción comercial y entréguelo a través de un trabajador en segundo plano.

Verificar la integración

Envíe accesorios conocidos de éxito, fracaso, reintento, cancelación y tiempo de espera, luego inspeccione las filas recientes:

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

Confirme una fila terminal por resultado lógico, tipos de campos estables, unidades esperadas, marcas de tiempo UTC y la ausencia de contenido confidencial. Realice un tiempo de espera Telemetry y un cierre ordenado de los trabajadores antes de habilitar la ruta en el volumen de producción.

Continúe con Integración de .NET y Serilog, Registro API, límites de tasa y errores y procesamiento por lotes y apagado.