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

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 de ámbito de escritura y lectura independientes 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;

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

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:

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

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, status, latency_ms, error_type
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.