팀/키 기반 로깅

팀/키 기반 로깅 (Team/Key Based Logging)

각 키(key)나 팀이 각자 고유한 Langfuse 프로젝트나 커스텀 콜백을 사용하도록 로깅을 설정하는 방법을 알려드릴게요. 이렇게 하면 로깅을 세밀하게 제어하면서 컴플라이언스 요구사항도 잘 지킬 수 있어요.

출처: 문서

본문

개요 (Overview)

각 키/팀이 자신만의 Langfuse 프로젝트나 커스텀 콜백을 사용하도록 허용할 수 있어요. 이 덕분에 로깅을 세밀하게 제어하고 컴플라이언스 요구사항을 충족할 수 있죠.

사용 예시:

팀 기반 로깅

Team 1 -> Logs to Langfuse Project 1
Team 2 -> Logs to Langfuse Project 2
Team 3 -> Disabled Logging (for GDPR compliance)

지원되는 로깅 통합 (Supported Logging Integrations)

langfuse
gcs_bucket
langsmith
arize

[BETA] 팀 로깅 (Team Logging)

엔터프라이즈 기능 이 기능을 사용하려면 LiteLLM 엔터프라이즈 라이선스가 필요해요. 무료 30일 체험판 을 시작하거나 데모를 예약 하세요. 엔터프라이즈에 포함된 기능 을 확인해 보세요.

UI 사용법 (UI Usage)

로깅 설정이 있는 팀 만들기 "Ai Agents"라는 팀을 만드세요.
팀용 키 만들기 팀 "AI Agents"용 키를 만들게요. 팀 로깅 설정은 팀에 생성된 모든 키에 적용돼요.
테스트 LLM API 요청 보내기 새 키로 테스트 LLM API 요청을 보내면, 1단계에서 설정한 로깅 제공자에 로그가 보이는 걸 확인할 수 있어요.
로깅 제공자에서 로그 확인하기 설정한 로깅 제공자로 이동해서 2단계에서 로그를 받았는지 확인하세요.

API 사용법 (API Usage)

누가 호출할 수 있나요

프록시 관리자(proxy admin), 팀이 속한 조직의 org 관리자, 그리고 팀 자체의 관리자는 해당 팀의 콜백을 조회·설정·제거할 수 있어요. 그 외의 사람은 403 응답을 받고, 한 팀의 관리자는 다른 팀의 설정을 읽을 수 없어요. POST /team/{team_id}/disable_logging 은 예외로, 프록시 관리자만 호출할 수 있어요. 한 통합 기능을 끄고 싶은 팀 관리자는 DELETE /team/{team_id}/callback/{callback_name} 을 사용하면 돼요.

팀별 콜백 설정 (Set Callbacks Per Team)

1. 팀에 콜백 설정하기

다음 요청으로 팀에 콜백을 추가할 수 있어요: POST /team/{team_id}/callback

curl -X POST 'http:/localhost:4000/team/dbe2f686-a686-4896-864a-4c3924458709/callback' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ***" \
-d '{
  "callback_name": "langfuse",
  "callback_type": "success",
  "callback_vars": {
    "langfuse_public_key": "pk",
    "langfuse_secret_key": "sk_",
    "langfuse_host": "https://cloud.langfuse.com"
    }
}'

지원되는 값 (Supported Values)

Field	Supported Values	Notes
callback_name	"langfuse", "gcs_bucket"	Currently only supports "langfuse", "gcs_bucket"
callback_type	"success", "failure", "success_and_failure"
callback_vars	dict of callback settings
langfuse_public_key	string	Required for Langfuse
langfuse_secret_key	string	Required for Langfuse
langfuse_host	string	Optional for Langfuse (defaults to https://cloud.langfuse.com)
gcs_bucket_name	string	Required for GCS Bucket. Name of your GCS bucket
gcs_path_service_account	string	Required for GCS Bucket. Path to your service account json

2. 팀용 키 만들기

팀 dbe2f686-a686-4896-864a-4c3924458709 용으로 생성된 모든 키는 1단계. 팀에 콜백 설정 에서 지정한 langfuse 프로젝트로 로그를 보내요.

curl --location 'http://0.0.0.0:4000/key/generate' \
    --header "Authorization: Bearer ***" \
    --header 'Content-Type: application/json' \
    --data '{
        "team_id": "dbe2f686-a686-4896-864a-4c3924458709"
}'

3. 팀용 /chat/completion 요청 보내기

curl -i http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "user", "content": "Hello, Claude gm!"}
    ]
}'

이 요청이 1단계. 팀에 콜백 설정 에서 지정한 langfuse 프로젝트에 기록되는 걸 확인할 수 있어요.

팀 로깅 비활성화 (Disable Logging for a Team)

특정 팀의 로깅을 비활성화하려면 다음 엔드포인트를 사용하세요: POST /team/{team_id}/disable_logging 이 엔드포인트는 해당 팀의 모든 success/failure 콜백을 제거해서 로깅을 효과적으로 비활성화해요. 단일 통합만 제거하고 다른 콜백은 그대로 두고 싶다면 아래에 설명된 DELETE /team/{team_id}/callback/{callback_name} 를 사용하세요.

1단계. 팀 로깅 비활성화

curl -X POST 'http://localhost:4000/team/YOUR_TEAM_ID/disable_logging' \
    -H 'Authorization: Bearer ***'

YOUR_TEAM_ID를 실제 팀 ID로 바꾸세요.

응답 (Response) 성공적인 요청은 다음과 같은 응답을 반환해요:

{
    "status": "success",
    "message": "Logging disabled for team YOUR_TEAM_ID",
    "data": {
        "team_id": "YOUR_TEAM_ID",
        "success_callbacks": [],
        "failure_callbacks": []
    }
}

2단계. 테스트 - /chat/completions

팀 = team_id 용으로 생성된 키를 사용하면, 설정한 success 콜백(예: Langfuse)에 로그가 보이지 않는 것을 확인할 수 있어요.

curl -i http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "user", "content": "Hello, Claude gm!"}
    ]
}'

디버깅 / 문제 해결 (Debugging / Troubleshooting)

GET /team/{team_id}/callback 으로 팀의 활성 콜백 확인하기 이것으로 team= team_id 의 활성 success/failure 콜백을 확인할 수 있어요.

curl -X GET 'http://localhost:4000/team/dbe2f686-a686-4896-864a-4c3924458709/callback' \
        -H "Authorization: Bearer ***"

팀에서 단일 콜백 제거 (Remove a Single Callback from a Team)

다른 콜백은 계속 실행하면서 한 통합만 등록 해제하려면 다음을 사용하세요: DELETE /team/{team_id}/callback/{callback_name} 해당 callback_name 으로 등록된 모든 항목이 콜백 타입과 무관하게 제거돼요. 즉, success 와 failure 둘 다로 등록된 통합도 한 번의 호출로 등록 해제돼요. 응답에는 남아 있는 콜백 목록이 표시되고, 팀이 등록하지 않은 callback_name 을 요청하면 아무것도 바꾸지 않고 404 를 반환해요.

팀 로깅 엔드포인트 (Team Logging Endpoints)

POST /team/{team_id}/callback: 팀에 success/failure 콜백 추가
GET /team/{team_id}/callback: 팀의 success/failure 콜백과 변수 조회
DELETE /team/{team_id}/callback/{callback_name}: 팀에서 단일 콜백 제거
POST /team/{team_id}/disable_logging: 팀에서 모든 콜백 제거

팀 로깅 - config.yaml

특정 팀 ID에 대해 로깅과 캐싱을 켜거나 끌 수 있어요. 이 섹션은 팀 범위에서만 적용돼요: litellm_settings.default_team_settings 는 특정 팀 ID에 속한 모든 키의 콜백을 설정해요. 개별 가상 키를 선언하는 config.yaml 인터페이스는 없으며, 키별 콜백은 /key/generate 나 /key/update API를 통해 프로비저닝돼요. 자세한 내용은 키 기반 로깅 문서를 참고하세요. config.yaml 은 신뢰할 수 있는 운영자가 제어하는 설정이므로 os.environ/... 참조가 여기서 지원되고, 시작 시 프록시 환경에서 해석돼요. 같은 참조를 관리 API로 보내면 거부돼요 ( API로 프로비저닝된 콜백의 시크릿 처리 참고).

예시: 이 설정은 팀 ID에 따라 langfuse 로그를 서로 다른 2개의 langfuse 프로젝트로 보내요.

litellm_settings:
  default_team_settings:
    - team_id: "dbe2f686-a686-4896-864a-4c3924458709"
      success_callback: ["langfuse"]
      langfuse_public_key: os.environ/LANGFUSE_PUB_KEY_1 # Project 1
      langfuse_secret: os.environ/LANGFUSE_PRIVATE_KEY_1 # Project 1
    - team_id: "06ed1e01-3fa7-4b9e-95bc-f2e59b74f3a8"
      success_callback: ["langfuse"]
      langfuse_public_key: os.environ/LANGFUSE_PUB_KEY_2 # Project 2
      langfuse_secret: os.environ/LANGFUSE_SECRET_2 # Project 2

이제 이 팀 ID에 대해 키 생성 하면

curl -X POST 'http://0.0.0.0:4000/key/generate' \
-H "Authorization: Bearer ***" \
-H 'Content-Type: application/json' \
-d '{"team_id": "06ed1e01-3fa7-4b9e-95bc-f2e59b74f3a8"}'

이 키들로 보내는 모든 요청 데이터는 각 팀 전용 로깅 설정에 기록돼요.

[BETA] 키 기반 로깅 (Key Based Logging)

/key/generate 나 /key/update 엔드포인트를 사용해 특정 키에 로깅 콜백을 추가할 수 있어요.

키 기반 로깅 동작 방식:

키에 콜백이 설정되어 있지 않으면 config.yaml 파일에 지정된 기본 콜백을 사용해요.
키에 콜백이 설정되어 있으면 해당 키에 지정된 콜백을 사용해요.

UI 사용법 (UI Usage)

로깅 설정이 있는 키 만들기 키를 만들 때 해당 키의 로깅 설정을 구성할 수 있어요. 이 로깅 설정은 이 키로 보내는 모든 요청에 적용돼요.
테스트 LLM API 요청 보내기 새 키로 테스트 LLM API 요청을 보내면 1단계에서 설정한 로깅 제공자에 로그가 보이는 걸 확인할 수 있어요.
로깅 제공자에서 로그 확인하기 설정한 로깅 제공자로 이동해서 2단계에서 로그를 받았는지 확인하세요.

API 사용법 (API Usage)

Langfuse / GCS Bucket / Langsmith

curl -X POST 'http://0.0.0.0:4000/key/generate' \
-H "Authorization: Bearer ***" \
-H 'Content-Type: application/json' \
-d '{
    "metadata": {
        "logging": [{
            "callback_name": "langfuse", # "otel", "gcs_bucket"
            "callback_type": "success", # "success", "failure", "success_and_failure"
            "callback_vars": {
                "langfuse_public_key": "pk-lf-...", # pass the resolved value, not an os.environ/ reference
                "langfuse_secret_key": "sk-lf-...", # pass the resolved value, not an os.environ/ reference
                "langfuse_host": "https://cloud.langfuse.com"
            }
        }]
    }
}'

각 키는 서로 다른 Langfuse 프로젝트를 가리킬 수 있어요. 프로젝트마다 하나씩 키를 생성하고, 해당 프로젝트의 자격 증명을 callback_vars 에 전달하세요.

API로 프로비저닝된 콜백의 시크릿 처리 (Secret handling for API-provisioned callbacks)

API로 전달되는 callback_vars 안의 os.environ/... 참조는 (v1.84부터) 거부돼요. 요청 본문에서 환경 변수 참조를 해석하게 하면, 키 관리 권한이 있는 호출자가 프록시 환경의 임의의 시크릿을 읽을 수 있게 되기 때문이에요. 그래서 이런 요청은 검증 오류로 실패해요. 요청에서 해석된 시크릿 값을 직접 전달하세요. LiteLLM은 프록시의 salt key를 이용해 저장 시점에 callback_vars 자격 증명을 암호화해요. 프록시가 자체 환경에서 자격 증명을 해석하도록 하려면 신뢰할 수 있는 config.yaml 에 콜백을 설정하세요 (전역으로는 litellm_settings 아래, 팀별로는 default_team_settings 를 통해).

특정 GCS Bucket에 로그를 보내는 가상 키 만들기 환경에 있는 GCS_SERVICE_ACCOUNT 에 서비스 계정 json 경로를 설정하세요.

export GCS_SERVICE_ACCOUNT=/path/to/service-account.json # GCS_SERVICE_ACCOUNT=/Users/ishaanjaffer/Downloads/adroit-crow-413218-a956eef1a2a8.json

curl -X POST 'http://0.0.0.0:4000/key/generate' \
-H "Authorization: Bearer ***" \
-H 'Content-Type: application/json' \
-d '{
    "metadata": {
        "logging": [{
            "callback_name": "gcs_bucket", # "otel", "gcs_bucket"
            "callback_type": "success", # "success", "failure", "success_and_failure"
            "callback_vars": {
                "gcs_bucket_name": "my-gcs-bucket", # Name of your GCS Bucket to log to
                "gcs_path_service_account": "/path/to/service-account.json" # path to the service account json, not an os.environ/ reference
            }
        }]
    }
}'

테스트 - /chat/completions 요청 3단계의 가상 키를 사용해 /chat/completions 요청을 보내세요. 성공적인 요청 시 GCS Bucket에서 로그를 확인할 수 있어요.

curl -i http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "fake-openai-endpoint",
    "messages": [
      {"role": "user", "content": "Hello, Claude"}
    ],
    "user": "hello",
  }'

특정 Langsmith 프로젝트에 로그를 보내는 가상 키 만들기

curl -X POST 'http://0.0.0.0:4000/key/generate' \
-H "Authorization: Bearer ***" \
-H 'Content-Type: application/json' \
-d '{
    "metadata": {
        "logging": [{
            "callback_name": "langsmith", # "otel", "gcs_bucket"
            "callback_type": "success", # "success", "failure", "success_and_failure"
            "callback_vars": {
                "langsmith_api_key": "lsv2_pt_...", # resolved Langsmith API key, not an os.environ/ reference
                "langsmith_project": "pr-brief-resemblance-72", # project name on langsmith
                "langsmith_base_url": "https://api.smith.langchain.com"
            }
        }]
    }
}'

테스트 - /chat/completions 요청 3단계의 가상 키를 사용해 /chat/completions 요청을 보내세요. 성공적인 요청 시 Langsmith 프로젝트에서 로그를 확인할 수 있어요.

curl -i http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "fake-openai-endpoint",
    "messages": [
      {"role": "user", "content": "Hello, Claude"}
    ],
    "user": "hello",
  }'

이 기능을 개선하고 싶다면 여기서 티켓을 제출 해 주세요.

키 콜백이 올바르게 설정됐는지 확인 - /key/health

/key/health 에 키를 넣어 호출하면 콜백 설정이 올바른지 확인할 수 있어요. 요청 헤더에 키를 전달하세요.

curl -X POST "http://localhost:4000/key/health" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json"

키가 올바르게 설정된 경우의 응답 / 잘못 설정된 경우의 응답

로깅 콜백이 올바르게 설정되면 키는 healthy 상태예요.

{
  "key": "healthy",
  "logging_callbacks": {
    "callbacks": [
      "gcs_bucket"
    ],
    "status": "healthy",
    "details": "No logger exceptions triggered, system is healthy. Manually check if logs were sent to ['gcs_bucket']"
  }
}

로깅 콜백이 올바르게 설정되지 않으면 키는 unhealthy 상태예요.

{
  "key": "unhealthy",
  "logging_callbacks": {
    "callbacks": [
      "gcs_bucket"
    ],
    "status": "unhealthy",
    "details": "Logger exceptions triggered, system is unhealthy: Failed to load vertex credentials. Check to see if credentials containing partial/invalid information."
  }
}

메시지 redaction 비활성화/활성화 (Disable/Enable Message redaction)

전역적으로 비활성화된 상태에서도 특정 키에 대해 프롬프트 로깅을 활성화할 수 있어요.

전역적으로 프롬프트 로깅(메시지 redaction)이 비활성화된 config.yaml 예시

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: gpt-5.6-terra
litellm_settings:
  callbacks: ["datadog"]
  turn_off_message_logging: True # 👈 Globally logging prompt / response is disabled

키에 대해 프롬프트 로깅 활성화 프롬프트 로깅을 활성화하려는 키에 대해 turn_off_message_logging 을 false 로 설정하세요. 이 값은 전역 turn_off_message_logging 설정을 덮어써요.

curl -X POST 'http://0.0.0.0:4000/key/generate' \
-H "Authorization: Bearer ***" \
-H 'Content-Type: application/json' \
-d '{
    "metadata": {
        "logging": [{
            "callback_name": "datadog",
            "callback_vars": {
                "turn_off_message_logging": false # 👈 Enable prompt logging
            }
        }]
    }
}'

/key/generate 의 응답

{
    "key_alias": null,
    "key": "sk-9v6...OKgQ",
    "metadata": {
        "logging": [
            {
                "callback_name": "datadog",
                "callback_vars": {
                    "turn_off_message_logging": false
                }
            }
        ]
    },
    "token_id": "a53a33db8c3cf832ceb28565dbb034f19f0acd69ee7f03b7bf6752f9f804081e"
}

/chat/completions 요청에 키 사용하기 이 키는 요청에 지정된 콜백에 프롬프트를 기록해요.

curl -i http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "user", "content": "hi my name is ishaan what key alias is this"}
    ]
  }'

팀/키 기반 로깅