Supabase .NET OpenTelemetry 설정: ASP.NET 요청·오류·지연시간 추적

Supabase .NET OpenTelemetry에서 수집하는 신호

SDK는 System.Diagnostics로 trace와 metric을 내보내고 클라이언트별 ActivitySource·Meter를 제공합니다. 애플리케이션에서 이를 구독하며 SDK 자체는 OpenTelemetry 패키지에 의존하지 않습니다. 근거: .NET 계측 발표

Storage의 전송 지연 metric 전체 이름은 supabase.storage.transfer.duration입니다. 요청 단위 시간과 전체 전송 시간을 섞어 비교하지 마세요. 또한 Functions는 HTTP 상태가 성공이어도 relay 오류를 실패 span으로 기록할 수 있습니다. 근거: 클라이언트별 span·metric

ASP.NET 요청 계측과 SDK 계측을 함께 등록하는 이유

들어오는 HTTP 요청은 ASP.NET instrumentation이, 요청 중 실행한 Supabase 호출은 SDK source가 관측합니다. 한쪽만 설정하면 진입 요청만 보이거나 SDK 호출만 보일 수 있습니다. 앱의 전체 지연과 특정 외부 호출의 지연을 나눠 확인하는 것이 진단의 시작입니다.

OpenTelemetry의 AddAspNetCoreInstrumentation은 요청 시간·HTTP 메서드·경로·상태 등의 trace를 제공합니다. 근거: ASP.NET Core 시작 안내 Supabase의 source 이름은 SourceNames로 trace·metric에 함께 등록할 수 있습니다. 근거: .NET SDK README

1단계: 패키지 준비

별도 ASP.NET Core 예제 프로젝트를 만들거나 기존 프로젝트에서 작업하세요. 아래 Supabase 8.0.0과 OTel hosting·OTLP 1.19.1은 출시 공지에 제시된 버전입니다. 기존 프로젝트와 호환되는지 확인하고 나머지 패키지도 복원된 버전을 기록합니다.

dotnet new web -o SupabaseOtelDemo
cd SupabaseOtelDemo
dotnet add package Supabase --version 8.0.0
dotnet add package OpenTelemetry.Extensions.Hosting --version 1.19.1
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol --version 1.19.1
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.Exporter.Console

hosting·exporter 설치는 Supabase 공지, ASP.NET instrumentation·console exporter는 OTel 시작 문서를 참고했습니다. SDK의 대상 프레임워크와 앱의 지원 런타임 정책은 별개로 확인하세요.

2단계: Program.cs에 trace와 metric 등록

using System.Diagnostics;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using Supabase;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("supabase-api-demo"))
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddSource(SupabaseDiagnostics.SourceNames.ToArray())
        .AddConsoleExporter())
    .WithMetrics(metrics => metrics
        .AddMeter(SupabaseDiagnostics.SourceNames.ToArray())
        .AddConsoleExporter());

var app = builder.Build();
app.MapGet("/health", () => Results.Ok(new {
    ok = true,
    traceId = Activity.Current?.TraceId.ToString()
}));
// Add your existing endpoints that call the Supabase SDK here.
app.Run();

Program.cs 예제 다운로드. health 경로는 ASP.NET 진입 요청을 확인하기 위한 것이며 Supabase SDK를 호출하지 않습니다. SDK span과 metric을 확인하려면 기존 Auth·Postgrest·Storage·Functions 호출이 있는 테스트 경로를 실행해야 합니다.

dotnet build
dotnet run
# 실행 로그에 표시된 주소로 바꿔 요청
curl --fail 'http://localhost:[port]/health'

목표는 traceId와 ASP.NET 요청 span의 연결 확인입니다. 이 글에는 실제 출력이나 측정된 응답시간을 제시하지 않습니다. Console exporter로 먼저 관측하면 수집기 연결 문제와 앱 계측 문제를 분리하기 쉽습니다.

3단계: Console에서 OTLP 수집기로 전환

trace·metric 각각의 AddConsoleExporter를 AddOtlpExporter로 바꾸고 조직의 collector 주소·프로토콜·인증을 설정합니다. 기본 구독 구성은 공식 .NET SDK 예제를 따릅니다. 아래는 로컬 gRPC 수집기를 이미 준비한 경우의 실행 예시이며 collector 자체를 설치하는 명령은 아닙니다.

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 OTEL_EXPORTER_OTLP_PROTOCOL=grpc dotnet run

실제 수집기는 주소·프로토콜·수신 포트가 맞아야 합니다. 원격 전송은 조직의 HTTPS·인증 설정을 적용하세요. 환경변수를 설정했다는 사실만으로 수집 성공을 판단하지 말고 collector 수신과 저장 백엔드의 서비스 이름·시간 필터를 확인해야 합니다.

오류와 지연시간을 읽는 진단 순서

trace는 한 요청의 경로를 조사하고 metric은 여러 호출의 분포를 보는 데 활용하세요. 평균이 안정적이어도 일부 요청만 느릴 수 있으므로 같은 기간·작업·트래픽 조건에서 지연 분포와 오류를 함께 비교합니다. SDK 호출 span만으로 Postgres 실행 계획이나 내부 서버 처리를 확정할 수는 없습니다.

민감정보·중복 계측·샘플링 점검

발표는 SDK 태그에서 URL query string을 제거하고 토큰·자격증명·payload를 넣지 않는다고 설명합니다. 근거: SDK 태그 처리 이는 앱의 자체 로그·다른 instrumentation·예외 메시지까지 안전하게 만든다는 뜻은 아닙니다.

검증에는 테스트 계정과 무해한 데이터를 사용하세요. HTTP 자동 계측을 추가한 환경에서는 SDK span과 전송 span이 부모·자식인지 중복 수집인지 확인해야 합니다. 샘플링이 적용되면 특정 trace가 없을 수 있으므로 metric 값과 trace 건수가 항상 일치할 것이라 기대하지 마세요.

수집이 보이지 않을 때의 점검표

앱·Supabase·OTel 패키지 버전:
요청 경로 / traceId / 재현 시각:
지원 클라이언트 / SDK span / 오류 상태:
metric 이름·단위 / 집계 구간:
exporter / collector / 수신 결과:
조사한 원인 / 수정 / 같은 조건 재검증:

설정 완료 판단: health·SDK 호출·전송을 따로 확인하기

등록 코드만 붙여 넣은 뒤 수집이 끝났다고 판단하지 않도록 다음 네 단계를 구분하세요. 예제의 health는 Supabase 호출을 하지 않으므로 1단계만 확인할 수 있습니다. 이 표는 실제 출력이 아닌 예상 관측과 진단 순서입니다.

예를 들어 콘솔에서 SDK span을 확인했지만 백엔드에서 찾지 못했다면 소스 등록을 다시 바꾸기 전에 전송·저장·조회 조건을 조사하세요. 반대로 health만 보이고 SDK span이 없으면 실제 호출 여부와 지원 클라이언트·source 등록을 먼저 확인합니다.

지연시간 경보를 만들기 전 metric의 단위를 확인하세요. 초와 밀리초를 혼동하면 임계값이 달라집니다. 응답 크기·작업 종류가 다른 호출은 같은 평균 하나로 합치기보다 분리해서 비교하는 편이 원인 조사에 도움이 됩니다.

자주 묻는 질문

설정만 하면 Supabase 대시보드에 자동 표시되나요?

이 글은 .NET 앱의 계측과 exporter 연결입니다. 데이터를 저장·조회할 collector와 백엔드는 따로 준비하고 연결을 확인해야 합니다.

health 요청만으로 Supabase 계측까지 검증되나요?

아닙니다. 예제 health는 SDK 호출이 없습니다. 테스트 환경에서 지원 클라이언트 호출이 있는 경로를 실행하세요.

JavaScript tracePropagation 설정을 .NET에도 넣어야 하나요?

이 글의 .NET 방식은 ActivitySource·Meter 구독입니다. 다른 SDK의 설정 이름을 그대로 적용하지 말고 해당 언어 문서를 따르세요.

관련 장애·관측 안내

• Supabase 장애 알림 RSS·Slack 구독 확인
• Workers CPU·메모리 프로파일 해석