StandardLoggingPayload 스펙

StandardLoggingPayload는 LiteLLM이 표준 로깅 페이로드를 구성했을 때 성공·실패 터미널 콜백 이벤트에 kwargs["standard_logging_object"]로 포함되는 구조예요. 커스텀 로깅 콜백은 원시 litellm_params 메타데이터가 아니라 kwargs["standard_logging_object"]["metadata"]에서 요청 신원(identity)을 읽어야 해요. 선택적 신원 필드는 없으면 null이에요. 중간 스트리밍 이벤트와 페이로드 구성이 실패한 콜백에서는 standard_logging_object가 생략될 수 있어요.

이 페이지는 페이로드의 모든 필드와 타입, 비용 계산·가드레일·프롬프트 관리·MCP 도구 호출 등 하위 객체의 구조를 정리해요. 커스텀 로깅 콜백이나 분석 파이프라인을 만들 때 참고하세요.

출처: 문서

본문

터미널 성공·실패 콜백 이벤트에는 LiteLLM이 표준 페이로드를 구성했을 때 kwargs["standard_logging_object"]가 포함돼요. 커스텀 로깅 콜백은 원시 litellm_params 메타데이터가 아니라 kwargs["standard_logging_object"]["metadata"]에서 요청 신원을 읽어야 해요. 선택적 신원 필드는 사용할 수 없으면 null이에요. 중간 스트리밍 이벤트와 페이로드 구성이 실패하는 콜백은 standard_logging_object를 생략할 수 있어요.

StandardLoggingPayload

필드	타입	설명
`id`	`str`	고유 식별자
`trace_id`	`str`	같은 전체 요청에 속한 여러 LLM 호출을 추적
`session_id`	`str`	`litellm_session_id`에서 가져온 end-user/대화 세션 id. `trace_id`와 독립적이며, `litellm_settings.request_correlation_in_logs`가 켜져 있을 때만 채워짐. 추가 문서
`call_type`	`str`	호출 유형
`response_cost`	`float`	USD($) 기준 응답 비용
`cost_breakdown`	`Optional[CostBreakdown]`	상세 비용 분해 객체
`response_cost_failure_debug_info`	`StandardLoggingModelCostFailureDebugInformation`	비용 추적 실패 시 디버그 정보
`zero_cost_diagnostic`	`Optional[StandardLoggingZeroCostDiagnostic]`	청구 가능한 요청이 $0로 책정된 이유. 비용이 0이 아니거나 모델이 무료·미매핑이거나 요청에 usage가 없으면 `None`. 추가 문서
`status`	`StandardLoggingPayloadStatus`	페이로드 상태
`status_fields`	`StandardLoggingPayloadStatusFields`	필터링·분석을 쉽게 하는 타입화된 상태 필드
`total_tokens`	`int`	총 토큰 수
`prompt_tokens`	`int`	프롬프트 토큰 수
`completion_tokens`	`int`	완성 토큰 수
`startTime`	`float`	호출 시작 시각
`endTime`	`float`	호출 종료 시각
`completionStartTime`	`float`	스트리밍 요청의 첫 토큰까지 걸린 시간
`response_time`	`float`	총 응답 시간. 스트리밍이면 첫 토큰까지의 시간
`model_map_information`	`StandardLoggingModelInformation`	모델 매핑 정보
`model`	`str`	요청에 보낸 모델 이름
`model_id`	`Optional[str]`	사용된 디플로이먼트의 모델 ID
`model_group`	`Optional[str]`	요청에 사용된 `model_group`
`api_base`	`str`	LLM API 기본 URL
`metadata`	`StandardLoggingMetadata`	메타데이터 정보
`cache_hit`	`Optional[bool]`	캐시 적중 여부
`cache_key`	`Optional[str]`	선택적 캐시 키

Cost Breakdown

cost_breakdown 필드는 완성(completion) 요청의 상세 비용 분해를 CostBreakdown 객체로 제공해요:

input_cost : 캐시 생성 토큰을 포함한 입력/프롬프트 토큰 비용
output_cost : 출력/완성 토큰 비용 (해당 시 reasoning 토큰 포함)
tool_usage_cost : 내장 도구 사용 비용 (예: 웹 검색, 코드 인터프리터)
total_cost : 입력 + 출력 + 도구 사용의 총 비용
reasoning_cost : reasoning 토큰 비용으로, output_cost의 하위 집합으로 보고됨 (모델이 reasoning 토큰을 반환할 때 채워짐, 예: gemini-3.8-flash, o3)
cache_read_cost : 캐시 읽기 토큰 비용으로, input_cost의 하위 집합으로 보고됨 (응답에 캐시된 토큰이 있으면 채워짐)
cache_creation_cost : 캐시 생성 토큰 비용으로, input_cost의 하위 집합으로 보고됨 (프롬프트 캐싱 사용 시 채워짐, 예: Anthropic 모델)

참고: 이 필드는 모든 호출 유형에 채워져요. 비완성(non-completion) 호출에서는 input_cost와 output_cost가 0일 수 있어요.

총 비용 관계는 response_cost = cost_breakdown.total_cost예요.

CostBreakdown 타입

    class CostBreakdown(TypedDict, total=False):
        input_cost: float           # Cost of input/prompt tokens in USD
        output_cost: float          # Cost of output/completion tokens in USD (includes reasoning)
        tool_usage_cost: float      # Cost of built-in tools usage in USD
        total_cost: float           # Total cost in USD
        reasoning_cost: float       # Cost of reasoning tokens in USD; subset of output_cost
        cache_read_cost: float      # Cost of cache-read tokens in USD; subset of input_cost
        cache_creation_cost: float  # Cost of cache-creation tokens in USD; subset of input_cost

StandardLoggingUserAPIKeyMetadata

필드	타입	설명
`user_api_key_hash`	`Optional[str]`	litellm 가상 키의 해시
`user_api_key_alias`	`Optional[str]`	API 키의 별칭
`user_api_key_org_id`	`Optional[str]`	키와 연결된 조직 ID
`user_api_key_team_id`	`Optional[str]`	키와 연결된 팀 ID
`user_api_key_user_id`	`Optional[str]`	키와 연결된 사용자 ID
`user_api_key_end_user_id`	`Optional[str]`	키와 연결된 end-user ID
`user_api_key_team_alias`	`Optional[str]`	키와 연결된 팀 별칭

StandardLoggingMetadata

StandardLoggingUserAPIKeyMetadata를 상속하고 다음을 추가해요:

필드	타입	설명
`spend_logs_metadata`	`Optional[dict]`	지출 로깅용 키-값 쌍
`requester_ip_address`	`Optional[str]`	요청자의 IP 주소
`requester_metadata`	`Optional[dict]`	추가 요청자 메타데이터
`vector_store_request_metadata`	`Optional[List[StandardLoggingVectorStoreRequest]]`	벡터 스토어 요청 메타데이터
`requester_custom_headers`	`Dict[str, str]`	클라이언트가 프록시에 보낸 커스텀(`x-`) 헤더
`prompt_management_metadata`	`Optional[StandardLoggingPromptManagementMetadata]`	프롬프트 관리·버전 관리 메타데이터
`mcp_tool_call_metadata`	`Optional[StandardLoggingMCPToolCall]`	MCP(Model Context Protocol) 도구 호출 정보와 비용 추적
`applied_guardrails`	`Optional[List[str]]`	적용된 가드레일 이름 목록
`usage_object`	`Optional[dict]`	LLM 공급자의 원시 usage 객체
`cold_storage_object_key`	`Optional[str]`	콜드 스토리지 조회용 S3/GCS 객체 키
`guardrail_information`	`Optional[list[StandardLoggingGuardrailInformation]]`	가드레일 정보

StandardLoggingVectorStoreRequest

필드	타입	설명
vector_store_id	Optional[str]	벡터 스토어의 ID
custom_llm_provider	Optional[str]	벡터 스토어와 연결된 커스텀 LLM 공급자 (예: bedrock, openai, anthropic)
query	Optional[str]	벡터 스토어에 보낸 쿼리
vector_store_search_response	Optional[VectorStoreSearchResponse]	OpenAI 형식 벡터 스토어 검색 응답
start_time	Optional[float]	벡터 스토어 요청 시작 시각
end_time	Optional[float]	벡터 스토어 요청 종료 시각

StandardLoggingAdditionalHeaders

필드	타입	설명
`x_ratelimit_limit_requests`	`int`	요청 수 제한
`x_ratelimit_limit_tokens`	`int`	토큰 수 제한
`x_ratelimit_remaining_requests`	`int`	남은 요청 수
`x_ratelimit_remaining_tokens`	`int`	남은 토큰 수

StandardLoggingHiddenParams

필드	타입	설명
`model_id`	`Optional[str]`	선택적 모델 ID
`cache_key`	`Optional[str]`	선택적 캐시 키
`api_base`	`Optional[str]`	선택적 API 기본 URL
`response_cost`	`Optional[str]`	선택적 응답 비용
`additional_headers`	`Optional[StandardLoggingAdditionalHeaders]`	추가 헤더
`batch_models`	`Optional[List[str]]`	Batches API 전용. 비용 계산에 쓰인 모델 목록
`litellm_model_name`	`Optional[str]`	요청에 보낸 모델 이름

StandardLoggingModelInformation

필드	타입	설명
`model_map_key`	`str`	모델 맵 키
`model_map_value`	`Optional[ModelInfo]`	선택적 모델 정보

StandardLoggingModelCostFailureDebugInformation

필드	타입	설명
`error_str`	`str`	오류 문자열
`traceback_str`	`str`	트레이스백 문자열
`model`	`str`	모델 이름
`cache_hit`	`Optional[bool]`	캐시 적중 여부
`custom_llm_provider`	`Optional[str]`	선택적 커스텀 LLM 공급자
`base_model`	`Optional[str]`	선택적 베이스 모델
`call_type`	`str`	호출 유형
`custom_pricing`	`Optional[bool]`	커스텀 가격 책정 사용 여부

StandardLoggingZeroCostDiagnostic

필드	타입	설명
`reason`	`Literal["missing_pricing_key", "pricing_not_applied", "cost_calculation_error"]`	요청이 $0로 책정된 이유. `litellm_zero_cost_requests_total`의 `reason` 라벨과 같은 값
`pricing_model`	`str`	요청이 비교된 가격 항목. 디플로이먼트 id 또는 모델 비용 맵 키
`missing_pricing_keys`	`Tuple[str, ...]`	usage가 필요로 하지만 항목이 선언하지 않은 요금 키. `reason`이 `missing_pricing_key`일 때만 비어 있지 않음

StandardLoggingPayloadErrorInformation

필드	타입	설명
`error_code`	`Optional[str]`	선택적 오류 코드 (예: "429")
`error_class`	`Optional[str]`	선택적 오류 클래스 (예: "RateLimitError")
`llm_provider`	`Optional[str]`	오류를 반환한 LLM 공급자 (예: "openai")

StandardLoggingPayloadStatus

두 값을 갖는 리터럴 타입이에요:

"success"
"failure"

StandardLoggingGuardrailInformation

필드	타입	설명
`guardrail_name`	`Optional[str]`	가드레일 이름
`guardrail_provider`	`Optional[str]`	가드레일 공급자
`guardrail_mode`	`Optional[Union[GuardrailEventHooks, List[GuardrailEventHooks]]]`	가드레일 모드
`guardrail_request`	`Optional[dict]`	가드레일 요청
`guardrail_response`	`Optional[Union[dict, str, List[dict]]]`	가드레일 응답
`guardrail_status`	`Literal["success", "guardrail_intervened", "guardrail_failed_to_respond"]`	가드레일 실행 상태: `success` = 위반 없음, `blocked` = 정책 위반으로 콘텐츠 차단/수정, `failure` = 기술 오류 또는 API 실패
`start_time`	`Optional[float]`	가드레일 시작 시각
`end_time`	`Optional[float]`	가드레일 종료 시각
`duration`	`Optional[float]`	가드레일 지속 시간(초)
`masked_entity_count`	`Optional[Dict[str, int]]`	마스킹된 엔티티 수

StandardLoggingPayloadStatusFields

필터링과 분석을 쉽게 하는 타입화된 상태 필드예요.

필드	타입	설명
`llm_api_status`	`StandardLoggingPayloadStatus`	LLM API 호출 상태: 성공하면 `"success"`, 오류면 `"failure"`
`guardrail_status`	`GuardrailStatus`	가드레일 실행 상태 (아래 참고)

StandardLoggingPayloadStatus

두 값을 갖는 리터럴 타입이에요:

"success" - LLM API 요청이 성공적으로 완료됨
"failure" - LLM API 요청이 실패함

GuardrailStatus

네 값을 갖는 리터럴 타입이에요:

"success" - 가드레일이 실행되어 콘텐츠를 통과시킴 (위반 감지 없음)
"guardrail_intervened" - 가드레일이 정책 위반으로 콘텐츠를 차단하거나 수정함
"guardrail_failed_to_respond" - 가드레일에 기술 실패 또는 API 오류가 있었음
"not_run" - 이 요청에 실행된 가드레일이 없음

사용 예시

가드레일이 개입한 요청의 로그를 필터링:

    {
      "status_fields": {
        "guardrail_status": "guardrail_intervened"
      }
    }

가드레일 기술 실패 찾기:

    {
      "status_fields": {
        "guardrail_status": "guardrail_failed_to_respond"
      }
    }

성공한 LLM 요청 가져오기:

    {
      "status_fields": {
        "llm_api_status": "success"
      }
    }

가드레일이 개입 없이 성공한 요청 찾기:

    {
      "status_fields": {
        "guardrail_status": "success",
        "llm_api_status": "success"
      }
    }

가드레일이 실행되지 않은 요청 찾기:

    {
      "status_fields": {
        "guardrail_status": "not_run"
      }
    }

StandardLoggingPromptManagementMetadata

프롬프트 버전 관리·관리 정보 추적에 사용돼요.

필드	타입	설명
`prompt_id`	`str`	필수. 프롬프트 템플릿 또는 버전의 고유 식별자
`prompt_variables`	`Optional[dict]`	프롬프트 템플릿에 사용된 변수/파라미터 (예: `{"user_name": "John", "context": "support"}`)
`prompt_integration`	`str`	필수. 프롬프트를 관리하는 통합/시스템 (예: `"langfuse"`, `"promptlayer"`, `"custom"`)

StandardLoggingMCPToolCall

LiteLLM 요청 내 MCP(Model Context Protocol) 도구 호출을 추적하는 데 사용돼요. 외부 도구 통합에 대한 상세 로깅을 제공해요.

필드	타입	설명
`name`	`str`	필수. 호출되는 도구의 이름 (예: `"get_weather"`, `"search_database"`)
`arguments`	`dict`	필수. 도구에 전달된 키-값 쌍 인자
`result`	`Optional[dict]`	도구 실행이 반환한 응답/결과 (커스텀 로깅 훅이 채움)
`mcp_server_name`	`Optional[str]`	도구 호출을 처리한 MCP 서버 이름 (예: `"weather-service"`, `"database-connector"`)
`mcp_server_logo_url`	`Optional[str]`	MCP 서버 로고 URL (LiteLLM 대시보드 UI 표시용)
`namespaced_tool_name`	`Optional[str]`	서버 접두사가 포함된 완전한 도구 이름 (예: `"deepwiki-mcp/get_page_content"`, `"github-mcp/create_issue"`)
`mcp_server_cost_info`	`Optional[MCPServerCostInfo]`	도구 호출의 비용 추적 정보

MCPServerCostInfo

MCP 서버 도구 호출의 비용 추적 구조예요.

필드	타입	설명
`default_cost_per_query`	`Optional[float]`	이 MCP 서버에 대한 모든 도구 호출의 기본 비용(USD)
`tool_name_to_cost_per_query`	`Optional[Dict[str, float]]`	정밀 가격 책정을 위한 도구별 비용 매핑 (예: `{"search": 0.01, "create": 0.05}`)

사용법

    # Basic MCP tool call metadata
    mcp_tool_call = {
        "name": "search_documents",
        "arguments": {
            "query": "machine learning tutorials",
            "limit": 10,
            "filter": "type:pdf"
        },
        "mcp_server_name": "document-search-service",
        "namespaced_tool_name": "docs-mcp/search_documents",
        "mcp_server_cost_info": {
            "default_cost_per_query": 0.02,
            "tool_name_to_cost_per_query": {
                "search_documents": 0.02,
                "get_document": 0.01
            }
        }
    }

    # optional result field (via custom logging hooks)
    mcp_tool_call_with_result = {
        "name": "search_documents",
        "arguments": {
            "query": "machine learning tutorials",
            "limit": 10,
            "filter": "type:pdf"
        },
        "result": {
            "documents": [...],
            "total_found": 42,
            "search_time_ms": 150
        },
        "mcp_server_name": "document-search-service",
        "namespaced_tool_name": "docs-mcp/search_documents",
        "mcp_server_cost_info": {
            "default_cost_per_query": 0.02,
            "tool_name_to_cost_per_query": {
                "search_documents": 0.02,
                "get_document": 0.01
            }
        }
    }

StandardLoggingPayload 스펙

StandardLoggingPayload 스펙

본문

StandardLoggingPayload

Cost Breakdown

CostBreakdown 타입

StandardLoggingUserAPIKeyMetadata

StandardLoggingMetadata

StandardLoggingVectorStoreRequest

StandardLoggingAdditionalHeaders

StandardLoggingHiddenParams

StandardLoggingModelInformation

StandardLoggingModelCostFailureDebugInformation

StandardLoggingZeroCostDiagnostic

StandardLoggingPayloadErrorInformation

StandardLoggingPayloadStatus

StandardLoggingGuardrailInformation

StandardLoggingPayloadStatusFields

StandardLoggingPayloadStatus

GuardrailStatus

사용 예시

StandardLoggingPromptManagementMetadata

StandardLoggingMCPToolCall

MCPServerCostInfo

사용법

더 알아보기 (Learn more)