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

모든 이벤트에 대해 새 HttpClient를 구성하는 대신 IHttpClientFactory에서 클라이언트를 해결합니다. 서비스의 기존 비밀 관리자에 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로 도착을 확인하세요.

경로 템플릿, 안정적인 내부 식별자 및 제어된 오류 범주를 사용합니다. 헤더, 쿠키, 자격 증명, 요청 본문, 바인딩된 SQL 값, 스택 추적, 프롬프트, 생성된 콘텐츠 또는 무제한 예외 메시지를 직렬화하지 마세요.

SQL 실행

더 길고 별도로 제한된 쿼리 기한과 읽기 범위 키를 사용합니다.

아래에서는 별도의 telemetry-query 클라이언트를 사용합니다. 제한 시간은 15초이며 수집 클라이언트는 3초를 유지합니다. 호출자의 취소 기한이 더 짧으면 그 기한이 우선합니다. 공유 클라이언트에서 요청을 시작한 뒤 제한 시간을 변경하지 마세요.

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, 속도 제한 및 오류 및 일괄 처리 및 종료를 계속 진행합니다.

코딩 에이전트와 함께 이 문서를 사용하세요.