✨ 감사 로그

✨ 감사 로그 (Audit Logs)

프록시 관리자로서 엔티티(키, 팀, 사용자, 모델)가 언제, 어떻게 생성·업데이트·삭제·재생성됐는지, 그리고 누가 그 작업을 수행했는지 확인할 수 있어요. 감사와 컴플라이언스에 유용해요.

LiteLLM은 다음 엔티티와 작업에 대한 변경을 추적해요:

엔티티: 키(Keys), 팀(Teams), 사용자(Users), 모델(Models)
작업: 생성(Create), 업데이트(Update), 삭제(Delete), 재생성(Regenerate)

출처: 문서

본문

프록시 관리자로서 엔티티(키, 팀, 사용자, 모델)가 생성·업데이트·삭제·재생성됐는지, 언제, 그리고 누가 그 작업을 수행했는지 확인할 수 있어요. 감사와 컴플라이언스에 유용해요.

LiteLLM은 다음 엔티티와 작업의 변경을 추적해요:

엔티티: 키, 팀, 사용자, 모델
작업: 생성, 업데이트, 삭제, 재생성

Enterprise 기능이에요.

이 기능은 LiteLLM Enterprise 라이선스가 필요해요. 무료 30일 체험을 시작하거나 데모를 예약하세요. Enterprise가 포함하는 것을 확인하세요.

사용법 (Usage)

1. 감사 로그 켜기

Enterprise 라이선스가 있으면 감사 로그는 기본적으로 켜져 있어서 구성할 것이 없어요. 다른 요금제이거나 명시적으로 설정하고 싶다면 litellm config.yaml에 store_audit_logs를 추가하고 프록시를 시작하세요.

    litellm_settings:
      store_audit_logs: true

Enterprise 라이선스에서 감사 로그를 끄려면 명시적으로 false로 설정하세요. 기본값보다 우선해요. LITELLM_STORE_AUDIT_LOGS는 config 설정과 같은 방식으로 동작하며, config가 store_audit_logs를 설정하지 않았을 때 읽혀요.

    litellm_settings:
      store_audit_logs: false

2. 엔티티를 변경하기

이 예제에서는 키를 삭제할 거예요.

    curl -X POST 'http://0.0.0.0:4000/key/delete' \
        -H "Authorization: Bearer ***" \
        -H 'Content-Type: application/json' \
        -d '{
            "key": "d5265fc73296c8fea819b4525590c99beab8c707e465afdf60dab57e1fa145e4"
        }'

3. LiteLLM UI에서 감사 로그 보기

LiteLLM UI에서 Logs -> Audit Logs로 이동하세요. 키 삭제에 대한 감사 로그를 볼 수 있어요.

감사 로그를 외부 저장소로 내보내기

감사 로그를 데이터베이스에 저장하는 것 외에 외부 저장소 백엔드(예: S3)로 내보낼 수 있어요. 로그는 배치되어 비동기로 업로드되므로 프록시 요청을 막지 않아요.

S3 예제

litellm_settings에 audit_log_callbacks와 s3_callback_params를 추가하세요:

    litellm_settings:
      store_audit_logs: true
      audit_log_callbacks: ["s3_v2"]
      s3_callback_params:
        s3_bucket_name: my-audit-logs-bucket     # AWS Bucket Name
        s3_region_name: us-west-2                # AWS Region
        s3_aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
        s3_aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
        s3_path: litellm-audit                   # [OPTIONAL] prefix path in the bucket

감사 로그는 JSON 파일로 다음 위치에 기록돼요:

    s3://<bucket>/audit_logs/<YYYY-MM-DD>/<HH-MM-SS>_<audit-log-id>.json
    # or, when s3_path is set:
    s3://<bucket>/<s3_path>/audit_logs/<YYYY-MM-DD>/<HH-MM-SS>_<audit-log-id>.json

info

audit_log_callbacks는 감사 로깅이 활성화된 동안에만 발화해요. 기본적으로 Enterprise 라이선스에서 켜져 있고, 그 외에는 store_audit_logs: true가 필요해요.

감사 로그를 별도 S3 버킷으로 보내기

callbacks: ["s3_v2"]로 일반 요청/응답 로그도 S3로 보낸다면, 기본적으로 두 스트림은 s3_callback_params를 공유해 같은 버킷에 들어가요. 감사 로그를 다른 버킷(예: 더 엄격한 접근 제어나 더 긴 보존이 있는 컴플라이언스 전용 버킷)으로 보내려면 s3_audit_callback_params 블록을 추가하세요. 이 블록은 s3_callback_params와 같은 필드를 받으며 감사 로그에만 적용돼요.

    litellm_settings:
      store_audit_logs: true
      callbacks: ["s3_v2"]                       # normal request logs
      audit_log_callbacks: ["s3_v2"]             # audit logs

      s3_callback_params:                        # used for normal logs
        s3_bucket_name: my-llm-logs-bucket
        s3_region_name: us-west-2
        s3_aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
        s3_aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
        s3_path: litellm-logs

      s3_audit_callback_params:                  # used for audit logs only
        s3_bucket_name: my-audit-logs-bucket
        s3_region_name: us-east-1                # different region OK
        s3_aws_access_key_id: os.environ/AWS_AUDIT_ACCESS_KEY_ID  # different creds OK
        s3_aws_secret_access_key: os.environ/AWS_AUDIT_SECRET_ACCESS_KEY
        s3_path: litellm-audit

고급 (Advanced)

관리 변경을 사용자에게 귀속시키기

사용자를 대신해 관리 엔드포인트를 호출하고, 감사 로그가 호출 키의 user_id 대신 그 사용자에게 변경을 귀속시키도록 해요. (프록시를 개발 플랫폼에 연결할 때 유용해요.)

v1.84.0부터 옵트인이 필요해요.

v1.84.0 이전에는 LiteLLM-Changed-By 헤더가 무조건 존중돼서 아무 호출자가 감사 귀속을 다시 쓸 수 있었어요. v1.84.0부터 프록시는 호출 키나 그 팀의 메타데이터에 allow_litellm_changed_by_header: true가 없으면 헤더를 무시해요. 옵트인이 없으면 changed_by는 호출 키의 user_id로 폴백돼요. master key는 저장된 메타데이터가 없어 옵트인할 수 없으므로, admin 가상 키로 헤더를 보내세요.

1. admin 키가 헤더를 설정하도록 허용하기

헤더를 보낼 admin 가상 키의 메타데이터에 allow_litellm_changed_by_header: true를 설정하세요. 키의 팀 메타데이터에 설정하면 해당 팀의 모든 키가 옵트인돼요.

    curl -X POST 'http://0.0.0.0:4000/key/update' \
        -H "Authorization: Bearer ***" \
        -H 'Content-Type: application/json' \
        -d '{
            "key": "«redacted:sk-…»",
            "metadata": {"allow_litellm_changed_by_header": true}
        }'

2. 요청 헤더에 `LiteLLM-Changed-By` 설정하기

관리 엔드포인트를 호출할 때 요청 헤더에 'user_id'를 설정하세요. 전체 목록 보기.

옵트인한 admin 키로 Team 예산을 업데이트해요.
변경을 '[email protected]'에 귀속시켜요.

핵심 변경: -H 'LiteLLM-Changed-By: [email protected]' 전달

    curl -X POST 'http://0.0.0.0:4000/team/update' \
        -H 'Authorization: Bearer ***' \
        -H 'LiteLLM-Changed-By: [email protected]' \
        -H 'Content-Type: application/json' \
        -d '{
            "team_id" : "8bf18b11-7f52-4717-8e1f-7c65f9d01e52",
            "max_budget": 2000
        }'

3. 생성된 감사 로그

    {
       "id": "bd136c28-edd0-4cb6-b963-f35464cf6f5a",
       "updated_at": "2024-06-08 23:41:14.793",
       "changed_by": "[email protected]", # 👈 CHANGED BY
       "changed_by_api_key": "example-api-key-123",
       "action": "updated",
       "table_name": "LiteLLM_TeamTable",
       "object_id": "8bf18b11-7f52-4717-8e1f-7c65f9d01e52",
       "before_value": {
         "spend": 0,
         "max_budget": 0,
       },
       "updated_values": {
         "team_id": "8bf18b11-7f52-4717-8e1f-7c65f9d01e52",
         "max_budget": 2000 # 👈 CHANGED TO
       },
     }

감사 로그의 API 스펙

`id`

타입: String
설명: 각 감사 로그 항목의 고유 식별자예요. 기본적으로 UUID로 자동 생성돼요.

`updated_at`

타입: DateTime
설명: 감사 로그 항목이 생성·업데이트된 타임스탬프를 저장해요. 기본적으로 현재 날짜와 시간으로 자동 설정돼요.

`changed_by`

타입: String
설명: 감사된 작업을 수행한 user_id예요. LiteLLM-Changed-By 헤더가 전달되고 호출 키나 그 팀의 메타데이터에 allow_litellm_changed_by_header: true가 있으면 changed_by=<LiteLLM-Changed-By 헤더로 전달된 값>이 돼요.

`changed_by_api_key`

타입: String
설명: 감사된 작업을 수행하는 데 사용된 해시된 API 키를 저장해요. 비워두면 빈 문자열로 기본 설정돼요.

`action`

타입: String
설명: 수행된 작업의 유형이에요. "create", "update", "delete" 중 하나예요.

`table_name`

타입: String
설명: 감사된 작업이 영향받은 테이블의 이름을 저장해요. LiteLLM_TeamTable, LiteLLM_UserTable, LiteLLM_VerificationToken 중 하나일 수 있어요.

`object_id`

타입: String
설명: 감사된 작업이 영향받은 객체의 ID를 저장해요. 키 ID, 팀 ID, 사용자 ID일 수 있어요.

`before_value`

타입: Json?
설명: 감사된 작업이 수행되기 전의 행 값을 저장해요. 선택적이며 null일 수 있어요.

`updated_values`

타입: Json?
설명: 감사된 작업이 수행된 후 업데이트된 행의 값을 저장해요.

더 알아보기 (Learn more)

Enterprise: Enterprise 라이선스가 포함하는 것
감사 로그 내보내기, LiteLLM-Changed-By 헤더 등 상세 설정