엔드포인트 활동

엔드포인트 활동 (Endpoint Activity)

대시보드에서 직접 API 엔드포인트 사용량을 추적하고 시각화해요. 엔드포인트 수준 활동 분석, 지출 분석, 성능 지표를 모니터링해 어떤 엔드포인트가 가장 많은 트래픽을 받고 어떻게 수행하는지 이해할 수 있어요.

출처: 문서

본문

개요 (Overview)

Endpoint Activity는 개별 API 엔드포인트의 지출과 사용량을 자동으로 추적할 수 있게 해줘요. LiteLLM 프록시를 통해 엔드포인트를 호출할 때마다 활동이 자동으로 추적·집계돼요. 이를 통해:

엔드포인트별 지출 자동 추적
Admin UI에서 엔드포인트 수준 사용 분석 보기
엔드포인트별 토큰 소비 모니터링
엔드포인트별 성공/실패율 분석
가장 활동이 많은 엔드포인트 식별
시간에 따른 엔드포인트 사용 추세 데이터 보기

Endpoint Activity 동작 방식

LiteLLM 프록시를 통해 API 호출을 할 때마다 엔드포인트 활동이 자동 추적돼요. 추가 구성이 필요 없어요. 평소처럼 엔드포인트를 호출하면 활동이 추적돼요.

API 호출 예시

어떤 엔드포인트에 요청을 하면 활동이 자동 기록돼요:

# /chat/completions: 👈 ENDPOINT AUTOMATICALLY TRACKED
# Authorization: *** YOUR PROXY KEY
curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ***" \
  --data '{
    "model": "gpt-5.6-luna",
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ]
  }'

엔드포인트(/chat/completions)는 다음으로 자동 추적돼요:

토큰 수 (prompt tokens, completion tokens, total tokens)
요청 지출
요청 상태 (성공 또는 실패)
타임스탬프 및 기타 메타데이터

Endpoint Activity 보기 (How to View Endpoint Activity)

Admin UI에서 Endpoint Activity 탭으로 이동해 엔드포인트 수준 분석을 보세요:

1. Endpoint Activity 접근

Admin UI의 Usage 페이지로 가서(PROXY_BASE_URL/ui/?login=success&page=new_usage) Endpoint Activity 탭을 클릭하세요.

2. 엔드포인트 분석 보기

Endpoint Activity 대시보드는 다음을 제공해요:

엔드포인트 사용 테이블: 집계 지표와 함께 모든 엔드포인트 보기:
- 총 요청 (성공과 실패)
- 성공률 백분율
- 총 토큰 소비
- 엔드포인트별 총 지출
성공 vs 실패 요청 차트: 엔드포인트별 요청 성공/실패율 시각화
사용 추세: 일일 추세 데이터로 시간에 따른 엔드포인트 활동 변화 보기

3. 엔드포인트 지표 이해

각 엔드포인트는 다음 지표를 표시해요:

Successful Requests - 성공적으로 완료된 요청 수
Failed Requests - 오류를 만난 요청 수
Total Requests - 성공과 실패 요청의 합
Success Rate - 성공 요청의 백분율
Total Tokens - 프롬프트와 completion 토큰의 합
Spend - 그 엔드포인트의 모든 요청의 총 비용

게이트웨이 요청 수 (Gateway Request Counts)

Usage 페이지의 Successful Requests와 Failed Requests 타일과 그 아래 Gateway Requests by Endpoint 차트는 지출 로그에서 파생되지 않고 프록시 자체가 집계해요. LiteLLM의 request-metrics 미들웨어는 ASGI 엣지에 있어 각 수신 LLM, MCP, A2A 호출을 분류하고, 게이트웨이가 반환한 상태를 기록해요. 그 집계는 날짜, 카테고리, 라우트별 키가 정해진 LiteLLM_DailyGatewayRequests 테이블로 접혀요. 키는 호출자가 공급한 어떤 것도, 키/사용자/배포 차원도 담지 않으므로, 테이블은 배포가 서빙하는 라우트 클래스 수와 실행 기간에 따라 커지며 트래픽과는 무관하게 커져요.

엣지에서 집계하는 것은 숫자의 의미를 바꿔요. 요청은 LiteLLM의 로깅 콜백에 도달했는지와 무관하게 기록되므로, 인증 거부, 요율 제한 응답, 제공자 오류는 사라지는 대신 실패 열에 들어가요. 모든 상태가 집계되며 2xx만이 아니에요. 또한 수신 요청 하나는 LiteLLM이 서빙하기 위해 만든 업스트림 호출 수와 무관하게 정확히 한 번 집계되므로, 라우터 재시도, 폴백, 내부 팬아웃이 총계를 부풀리지 않아요.

집계는 메모리에 쌓이고 지출 배치 작성기와 같은 간격(proxy_batch_write_at, 기본 10초)으로 커밋되므로, 요청이 나타나는 데 몇 초 걸릴 수 있어요. 실패한 커밋은 버려지지 않고 병합되어 다음 플러시에서 재시도되며, 종료 중에 어큐뮬레이터가 한 번 더 비워져요. 이것은 엔터프라이즈 라이선스 뒤에 있지 않아요. 데이터베이스가 구성된 어떤 배포도 이 집계를 기록해요.

게이트웨이 수가 키별·모델별 분석과 일치하지 않는 이유 (Why gateway counts do not match the per-key and per-model breakdowns)

Usage 페이지의 키별, 모델별, 공급자별, 태그별 패널은 여전히 일일 지출 롤업을 읽는데, 이는 요청 완료 후 지출 로그에서 쓰여져요. 두 소스는 다른 질문에 답하며 정확히 맞아떨어질 것으로 기대되지 않아요.

지출 로그 행은 로그될 만큼 진행된 요청에만 존재하며, 그 요청을 서빙한 키, 팀, 모델을 담아요. 게이트웨이 수는 프록시가 응답한 모든 것에 존재하며, 키가 해석되거나 모델이 선택되기 전에 거부된 요청도 포함해요. 그래서 게이트웨이 테이블이 키나 사용자 차원을 전혀 담지 않아요. 드리프트는 양방향으로 흘러요: 게이트웨이 수는 분류된 추론, MCP, A2A 트래픽만 집계하고 내부 팬아웃을 한 행으로 접지만, 지출 롤업은 로그된 관리·패스스루 호출도 다루고 각 업스트림 시도를 따로 기록해요. 트래픽 볼륨에는 타일을, 지출 귀속에는 분석을 사용하세요.

/gateway/daily/activity

게이트웨이 수는 자체 엔드포인트로 서빙돼요. 기본 테이블이 키나 사용자 차원이 없는 배포 전체이므로, proxy_admin과 proxy_admin_viewer 역할로 제한되고 다른 호출자는 403을 받아요. Admin UI에서 비관리자는 타일의 지출 파생 수만 보고 게이트웨이 차트는 보지 못해요. 관리자도 배포가 아직 게이트웨이 수를 기록하지 않았다면 같은 폴백이 적용돼요.

start_date와 end_date는 모두 선택이며 YYYY-MM-DD를 받고, 생략하면 지난 30일을 반환해요.

게이트웨이 요청 수

curl -L -X GET 'http://localhost:4000/gateway/daily/activity?start_date=2026-07-28&end_date=2026-08-04' \
  -H "Authorization: Bearer ***"

게이트웨이 요청 수 응답

{
  "total_successful_requests": 1284,
  "total_failed_requests": 37,
  "by_date": [
    { "date": "2026-08-03", "successful_requests": 612, "failed_requests": 11 },
    { "date": "2026-08-04", "successful_requests": 672, "failed_requests": 26 }
  ],
  "by_route": [
    { "category": "llm", "route": "/chat/completions", "successful_requests": 1103, "failed_requests": 31 },
    { "category": "llm", "route": "/embeddings", "successful_requests": 141, "failed_requests": 4 },
    { "category": "mcp", "route": "/mcp", "successful_requests": 40, "failed_requests": 2 }
  ]
}

by_date는 오래된 것 먼저, by_route는 성공 요청이 많은 순으로 정렬돼요. category는 llm, mcp, a2a 중 하나이고, route는 분류기가 할당한 정규화된 라우트이며 원시 요청 경로가 아니에요. 그래서 /v1/chat/completions와 /chat/completions가 같은 행으로 접혀요. Admin UI의 차트는 상위 15개 라우트를 렌더링해요.

사용 사례 (Use Cases)

성능 모니터링 (Performance Monitoring)

엔드포인트 건강과 성능 모니터링:

실패율이 높은 엔드포인트 식별
가장 많은 트래픽을 받는 엔드포인트 추적
엔드포인트별 토큰 소비 패턴 모니터링
엔드포인트 사용 이상 감지

비용 최적화 (Cost Optimization)

엔드포인트 전반의 지출 분포 이해:

고비용 엔드포인트 식별
비싼 엔드포인트 최적화
엔드포인트 사용 기반 예산 할당
시간에 따른 비용 추세 추적

Customer Usage - 개별 고객의 지출과 사용량 추적
Cost Tracking - 비용 추적 및 분석
Spend Logs - 세부 요청 수준 지출 로그

엔드포인트 활동