디버깅

디버깅 (Debugging)

2단계의 디버깅을 지원해요.

debug (info 로그 출력)
detailed debug (debug 로그 출력)

프록시는 json 로그도 지원해요. 여기를 보세요.

출처: 문서

본문

debug

cli로:

$ litellm --debug

env로:

os.environ["LITELLM_LOG"] = "INFO"

detailed debug

cli로:

$ litellm --detailed_debug

env로:

os.environ["LITELLM_LOG"] = "DEBUG"

디버그 로그 (Debug Logs)

상세 디버그 로그를 보려면 --detailed_debug로 프록시를 실행하세요:

litellm --config /path/to/config.yaml --detailed_debug

요청을 보내면 터미널 출력에서 LiteLLM이 LLM에 보낸 POST 요청을 볼 수 있어요:

POST Request Sent from LiteLLM:
curl -X POST \
https://api.openai.com/v1/chat/completions \
-H 'content-type: application/json' -H 'Authorization: Bearer sk-qnW...****' \
-d '{"model": "gpt-5.6-luna", "messages": [{"role": "user", "content": "this is a test request, write a short poem"}]}'

단일 요청 디버깅 (Debug single request)

요청 본문에 litellm_request_debug=True를 전달하세요.

curl -L -X POST 'http://0.0.0.0:4000/chat/completions' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ***" \
-d '{
     "model":"fake-openai-endpoint",
    "messages": [{"role": "user","content": "How many r in the word strawberry?"}],
    "litellm_request_debug": true
}'

이는 이 요청 하나에 대해 LiteLLM이 API 제공자에게 보낸 원시 요청과 API 제공자에게 받은 원시 응답만 로그에 출력해요.

INFO:     Uvicorn running on http://0.0.0.0:4000 (Press CTRL+C to quit)
20:14:06 - LiteLLM:WARNING: litellm_logging.py:938 - POST Request Sent from LiteLLM:
curl -X POST \
https://exampleopenaiendpoint-production.up.railway.app/chat/completions \
-H 'Authorization: ***' -H 'Content-Type: application/json' \
-d '{'model': 'fake', 'messages': [{'role': 'user', 'content': 'How many r in the word strawberry?'}], 'stream': False}'
20:14:06 - LiteLLM:WARNING: litellm_logging.py:1015 - RAW RESPONSE:
{"id":"chatcmpl-817fc08f0d6c451485d571dab39b26a1","object":"chat.completion","created":1677652288,"model":"gpt-3.5-turbo-0301","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"message":{"role":"assistant","content":"\n\nHello there, how may I assist you today?"},"logprobs":null,"finish_reason":"stop"}],"usage":{"prompt_tokens":9,"completion_tokens":12,"total_tokens":21}}
INFO:     127.0.0.1:56155 - "POST /chat/completions HTTP/1.1" 200 OK

JSON 로그 (JSON LOGS)

env에서 JSON_LOGS="True"를 설정하세요:

export JSON_LOGS="True"

또는 yaml에서 json_logs: true를 설정하세요:

litellm_settings:
  json_logs: true

프록시 시작:

$ litellm

이제 프록시는 모든 로그를 json 형식으로 출력해요.

요청 상관관계 ID (Request Correlation IDs)

request_correlation_in_logs: true를 설정하면 모든 로그 줄에 요청의 trace_id와 session_id를 찍어요. 이렇게 하면 각 호출 지점에 로깅 호출을 추가하지 않고도 로그 애그리게이터를 단일 요청에 묶인 모든 줄로, 또는 단일 최종 사용자 세션의 모든 요청으로 필터링할 수 있어요. 일반 텍스트와 JSON 로그 모두에서 동작해요.

litellm_settings:
  request_correlation_in_logs: true

trace_id는 x-litellm-trace-id 요청 헤더에서 오며(또는 헤더가 설정되지 않으면 요청별로 생성), session_id는 요청 본문의 litellm_session_id 또는 x-litellm-session-id 헤더에서 와요. 전체 해석 순서는 Request Headers 참고. 세션 id가 실제로 공급된 후에만 로그 줄에 추가돼요.

그 명시적 헤더 중 어느 것도 없으면, trace_id/session_id는 각각 표준 W3C Trace Context traceparent 헤더와 W3C Baggage baggage 헤더로 폴백해요. traceparent의 trace-id가 trace_id가 되고, baggage의 session.id 항목이 session_id가 돼요. 이렇게 하면 실제 OpenTelemetry trace 컨텍스트를 이미 지닌 요청이 별도의 litellm 헤더 없이 기존 관측성 백엔드의 같은 trace로 litellm 로그를 상관시켜요. 명시적 litellm 헤더는 있을 때 항상 우선해요.

json_logs: true일 때의 예시 로그 줄:

{"message": "...", "level": "INFO", "timestamp": "...", "trace_id": "2a5cbcfa-ccdf-493c-858b-eb8e9b07f32c", "session_id": "user-123-session-1"}

json 없을 때의 예시 로그 줄 (일반 텍스트):

15:30:43 - LiteLLM Proxy:ERROR: common_request_processing.py:848 - some log message [trace_id=2a5cbcfa-ccdf-493c-858b-eb8e9b07f32c session_id=user-123-session-1]

request_correlation_in_logs는 또한 StandardLoggingPayload(S3, Langfuse 같은 로깅 통합으로 전송)에 같은 방식으로 채워지는 독립적인 session_id 필드를 추가해요. StandardLoggingPayload 스펙 참고.

trace_id와 session_id 둘 다 저장 전에 정화돼요. 제어 문자(\r/\n 포함)가 제거되고 값이 256자로 캡되므로, 호출자가 공급한 litellm_session_id로 가짜 로그 줄을 조작하거나 로그 저장소를 부풀릴 수 없어요.

플래그는 기본적으로 false라서, 옵트인 전까지 기존 로그 출력은 영향을 받지 않아요.

이것은 현재 프록시가 처리하는 요청과 SDK를 통해 직접 이루어지는 litellm.acompletion() 호출에 적용돼요. 동기 SDK 호출(litellm.completion())은 아직 trace_id/session_id를 찍지 않아요. 그 경로 지원은 후속 작업으로 계획돼 있어요.

로그 출력 제어 (Control Log Output)

fastapi의 기본 'INFO' 로그 끄기 / 'json logs' 켜기

litellm_settings:
  json_logs: true

LITELLM_LOG를 'ERROR'로 설정

오류가 발생할 때만 로그를 얻어요.

LITELLM_LOG="ERROR"

프록시 시작:

$ litellm

예상 출력:

# no info statements

일반적인 오류 (Common Errors)

"No available deployments..."

No deployments available for selected model, Try again in 60 seconds. Passed model=claude-sonnet-5. pre-call-checks=False, allowed_model_region=n/a.

이것은 모든 모델이 요율 제한 오류를 맞아 쿨다운이 발동했기 때문에 발생할 수 있어요.

어떻게 제어할까?

쿨다운 시간 조정:

router_settings:
  cooldown_time: 0 # 👈 KEY CHANGE

쿨다운 비활성화 [비권장]:

router_settings:
  disable_cooldowns: True

이는 권장되지 않아요. 요청이 tpm/rpm 한도를 초과한 배포로 라우팅될 수 있기 때문이에요.