알림 & 모니터링

알림 & 모니터링 (Alerting & Monitoring)

LiteLLM 프록시의 알림 기능은 LLM 성능, 예산/지출, 시스템 건강 상태 등 다양한 항목에 대해 Slack, Discord, Microsoft Teams 등의 채널로 자동 알림을 보내요. 여기서는 알림 채널 설정부터 세부 알림 유형 제어, 다이제스트 모드까지 단계별로 살펴봐요.

출처: 문서

본문

다음과 같은 항목에 대해 알림을 받을 수 있어요:

카테고리	알림 유형
LLM 성능	응답이 멈춘 API 호출, 느린 API 호출, 실패한 API 호출, 모델 장애 알림
예산 & 지출	키/사용자별 예산 추적, 소프트 예산 알림, 팀/태그별 주간·월간 지출 리포트
시스템 건강	실패한 데이터베이스 읽기/쓰기
일일 리포트	가장 느린 LLM 배포 5개, 실패 요청이 가장 많은 LLM 배포 5개, 팀/태그별 주간·월간 지출

다음 채널에서 동작해요:

• Slack
• Discord
• Microsoft Teams

빠른 시작 (Quick Start)

프록시로부터 알림을 받을 Slack 알림 채널을 설정해 봐요.

1단계: 환경에 Slack Webhook URL 추가

https://api.slack.com/messaging/webhooks 에서 slack webhook url을 얻으세요. Discord Webhooks도 사용할 수 있어요 (여기 참고).

프록시 환경에서 Slack 알림을 활성화하려면 SLACK_WEBHOOK_URL을 설정하세요.

export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/<>/<>/<>"

SLACK_WEBHOOK_URL이 설정되지 않았다면, ALERTING_WEBHOOK_URL이 공급자 중립적인 대체값으로 읽혀요. 이를 사용하면 Rocket.Chat이나 Mattermost처럼 Slack 호환 수신 웹훅에 동일한 Slack 형식 알림을 보낼 수 있어요.

2단계: 프록시 설정 (Setup Proxy)

general_settings:
  alerting: ["slack"]
  alerting_threshold: 300 # requests hang 5분 이상, responses 5분 이상이면 알림 전송
  spend_report_frequency: "1d" # [선택] 1d, 2d, 30d ... 으로 설정. 지출 리포트 전송 주기 지정
  # [선택적 알림 인자]
  alerting_args:
    daily_report_frequency: 43200  # 12시간(초)
    report_check_interval: 3600    # 1시간(초)
    budget_alert_ttl: 86400        # 24시간(초)
    outage_alert_ttl: 60           # 1분(초)
    region_outage_alert_ttl: 60    # 1분(초)
    minor_outage_alert_threshold: 5
    major_outage_alert_threshold: 10
    max_outage_alert_list_size: 1000
    log_to_console: false

프록시 시작:

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

3단계: 테스트!

curl -X GET 'http://0.0.0.0:4000/health/services?service=slack' \
-H "Authorization: Bearer ***"

고급 (Advanced)

알림에서 메시지 가리기 (Redacting Messages from Alerts)

기본적으로 알림에는 LLM에 전달된 메시지/입력값이 표시돼요. 이 값을 slack 알림에서 가리고 싶다면 콘피그에 다음 설정을 추가하세요.

general_settings:
  alerting: ["slack"]
  alert_types: ["spend_reports"]
litellm_settings:
  redact_messages_in_exceptions: True

가상 키에 대한 소프트 예산 알림 (Soft Budget Alerts for Virtual Keys)

키/팀의 예산이 곧 소진될 때 알림을 보내는 데 사용해요.

1단계. 소프트 예산이 있는 가상 키 생성

soft_budget을 0.001로 설정하세요.

curl -X 'POST' \
  'http://localhost:4000/key/generate' \
  -H 'accept: application/json' \
  -H 'x-goog-api-key: sk-<yo...ey>' \
  -H 'Content-Type: application/json' \
  -d '{
  "key_alias": "prod-app1",
  "team_id": "113c1a22-e347-4506-bfb2-b320230ea414",
  "soft_budget": 0.001}'

2단계. 가상 키로 프록시에 요청 전송

curl http://0.0.0.0:4000/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
  "model": "openai/gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "this is a test request, write a short poem"
    }
  ]}'

3단계. Slack에서 예상 알림 확인

알림에 메타데이터 추가하기 (Add Metadata to alerts)

디버깅을 위해 프록시 호출에 알림용 메타데이터를 추가해 봐요.

import openai
client = openai.OpenAI(
    api_key="anything",
    base_url="http://0.0.0.0:4000")
# litellm 프록시에 설정된 모델로 요청 전송, `litellm --model`
response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages = [],
    extra_body={
        "metadata": {
            "alerting_metadata": {
                "hello": "world"
            }
        }
    })

예상 응답 (Expected Response)

특정 알림 유형 선택하기 (Select specific alert types)

특정 알림 유형만 옵트인하려면 alert_types를 설정하세요. alert_types가 설정되지 않으면 모든 기본 알림 유형이 활성화돼요.

👉 모든 알림 유형은 여기에서 볼 수 있어요.

general_settings:
  alerting: ["slack"]
  alert_types: [
    "llm_exceptions",
    "llm_too_slow",
    "llm_requests_hanging",
    "budget_alerts",
    "spend_reports",
    "db_exceptions",
    "daily_reports",
    "cooldown_deployment",
    "new_model_added",
  ]

알림 유형에 Slack 채널 매핑하기 (Map slack channels to alert type)

알림 유형별로 특정 채널을 설정하고 싶다면 이 기능을 사용해요. 다음과 같이 할 수 있어요.

llm_exceptions -> go to slack channel #llm-exceptions
spend_reports -> go to slack channel #llm-spend-reports

config.yaml에 alert_to_webhook_url을 설정하세요.

알림당 1개 채널:

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/fake
      api_key: fake-key
      api_base: https://exampleopenaiendpoint-production.up.railway.app/
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  alerting: ["slack"]
  alerting_threshold: 0.0001 # (초) 알림 테스트를 위해 인위적으로 낮게 설정
  alert_to_webhook_url: {
    "llm_exceptions": "example-slack-webhook-url",
    "llm_too_slow": "example-slack-webhook-url",
    "llm_requests_hanging": "example-slack-webhook-url",
    "budget_alerts": "example-slack-webhook-url",
    "db_exceptions": "example-slack-webhook-url",
    "daily_reports": "example-slack-webhook-url",
    "spend_reports": "example-slack-webhook-url",
    "cooldown_deployment": "example-slack-webhook-url",
    "new_model_added": "example-slack-webhook-url",
    "outage_alerts": "example-slack-webhook-url",
  }
litellm_settings:
  success_callback: ["langfuse"]

특정 알림 유형에 여러 Slack 채널 제공:

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/fake
      api_key: fake-key
      api_base: https://exampleopenaiendpoint-production.up.railway.app/
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  alerting: ["slack"]
  alerting_threshold: 0.0001 # (초) 알림 테스트를 위해 인위적으로 낮게 설정
  alert_to_webhook_url: {
    "llm_exceptions": ["os.environ/SLACK_WEBHOOK_URL", "os.environ/SLACK_WEBHOOK_URL_2"],
    "llm_too_slow": ["https://webhook.site/7843a980-a494-4967-80fb-d502dbc16886", "https://webhook.site/28cfb179-f4fb-4408-8129-729ff55cf213"],
    "llm_requests_hanging": ["os.environ/SLACK_WEBHOOK_URL_5", "os.environ/SLACK_WEBHOOK_URL_6"],
    "budget_alerts": ["os.environ/SLACK_WEBHOOK_URL_7", "os.environ/SLACK_WEBHOOK_URL_8"],
    "db_exceptions": ["os.environ/SLACK_WEBHOOK_URL_9", "os.environ/SLACK_WEBHOOK_URL_10"],
    "daily_reports": ["os.environ/SLACK_WEBHOOK_URL_11", "os.environ/SLACK_WEBHOOK_URL_12"],
    "spend_reports": ["os.environ/SLACK_WEBHOOK_URL_13", "os.environ/SLACK_WEBHOOK_URL_14"],
    "cooldown_deployment": ["os.environ/SLACK_WEBHOOK_URL_15", "os.environ/SLACK_WEBHOOK_URL_16"],
    "new_model_added": ["os.environ/SLACK_WEBHOOK_URL_17", "os.environ/SLACK_WEBHOOK_URL_18"],
    "outage_alerts": ["os.environ/SLACK_WEBHOOK_URL_19", "os.environ/SLACK_WEBHOOK_URL_20"],
  }
litellm_settings:
  success_callback: ["langfuse"]

테스트 - 유효한 llm 요청을 보내고, llm_too_slow 알림이 전용 slack 채널에 오는지 확인하세요.

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!"}
    ]}'

MS Teams Webhooks

MS Teams는 알림에 사용할 수 있는 slack 호환 웹훅 URL을 제공해요.

빠른 시작 (Quick Start)

Microsoft Teams 채널의 웹훅 URL을 얻으세요.

.env에 추가:

SLACK_WEBHOOK_URL="https://berriai.webhook.office.com/webhookb2/...6901/IncomingWebhook/b55fa0c2a48647be8e6effedcd540266/e04b1092-4a3e-44a2-ab6b-29a0a4854d1d"

litellm 콘피그에 추가:

model_list:
  - model_name: "azure-model"
    litellm_params:
      model: "azure/gpt-5.6-luna"
      api_key: "my-bad-key" # 👈 bad key
general_settings:
  alerting: ["slack"]
  alerting_threshold: 300 # requests hang 5분 이상, responses 5분 이상이면 알림 전송

헬스 체크 실행! 프록시 /health/services 엔드포인트를 호출해 알림 연결이 제대로 설정됐는지 테스트하세요.

curl --location 'http://0.0.0.0:4000/health/services?service=slack' \
--header "Authorization: Bearer ***"

예상 응답 (Expected Response)

Discord Webhooks

Discord는 알림에 사용할 수 있는 slack 호환 웹훅 URL을 제공해요.

빠른 시작 (Quick Start)

Discord 채널의 웹훅 URL을 얻으세요.

Discord 웹훅에 /slack을 추가하세요. 다음과 같은 형태가 되면 돼요:

"https://discord.com/api/webhooks/1240030362193760286/cTLWt5ATn1gKmcy_982rl5xmYHsrM1IWJdmCL1AyOmU9JdQXazrp8L1_PYgUtgxj8x4f/slack"

litellm 콘피그에 추가:

model_list:
  - model_name: "azure-model"
    litellm_params:
      model: "azure/gpt-5.6-luna"
      api_key: "my-bad-key" # 👈 bad key
general_settings:
  alerting: ["slack"]
  alerting_threshold: 300 # requests hang 5분 이상, responses 5분 이상이면 알림 전송
environment_variables:
  SLACK_WEBHOOK_URL: "https://discord.com/api/webhooks/1240030362193760286/cTLWt5ATn1gKmcy_982rl5xmYHsrM1IWJdmCL1AyOmU9JdQXazrp8L1_PYgUtgxj8x4f/slack"

[BETA] 예산 알림용 웹훅 (Webhooks for Budget Alerts)

참고: 이는 베타 기능이라 스펙이 변경될 수 있어요.

예산 알림을 받을 웹훅을 설정해 봐요.

config.yaml 설정

환경에 url을 추가하세요. 테스트용으로 여기에서 링크를 사용할 수 있어요.

export WEBHOOK_URL="https://webhook.site/6ab090e8-c55f-4a23-b075-3209f5c57906"

config.yaml에 'webhook' 추가:

general_settings:
  alerting: ["webhook"] # 👈 KEY CHANGE

프록시 시작:

litellm --config /path/to/config.yaml
# RUNNING on http://0.0.0.0:4000

테스트!

curl -X GET --location 'http://0.0.0.0:4000/health/services?service=webhook' \
--header "Authorization: Bearer ***"

예상 응답 (Expected Response):

{
  "spend": 1, # the spend for the 'event_group'
  "max_budget": 0, # the 'max_budget' set for the 'event_group'
  "token": "example-api-key-123",
  "user_id": "default_user_id",
  "team_id": null,
  "user_email": null,
  "key_alias": null,
  "projected_exceeded_data": null,
  "projected_spend": null,
  "event": "budget_crossed", # Literal["budget_crossed", "threshold_crossed", "projected_limit_exceeded"]
  "event_group": "user",
  "event_message": "User Budget: Budget Crossed"
}

웹훅 이벤트 API 스펙 (API Spec for Webhook Event)

• spend float: event_group의 현재 지출 금액.
• max_budget float 또는 null: event_group에 허용된 최대 예산. 설정되지 않으면 null.
• token str: 키의 해시된 값. 인증 또는 식별 목적으로 사용.
• customer_id str 또는 null: 이벤트와 연결된 고객의 ID (선택).
• internal_user_id str 또는 null: 이벤트와 연결된 내부 사용자의 ID (선택).
• team_id str 또는 null: 이벤트와 연결된 팀의 ID (선택).
• user_email str 또는 null: 이벤트와 연결된 내부 사용자의 이메일 (선택).
• key_alias str 또는 null: 이벤트와 연결된 키의 별칭 (선택).
• projected_exceeded_date str 또는 null: 예산이 초과될 것으로 예상되는 날짜. 키에 soft_budget이 설정된 경우 반환 (선택).
• projected_spend float 또는 null: 예상 지출 금액. 키에 soft_budget이 설정된 경우 반환 (선택).
• event Literal["budget_crossed", "threshold_crossed", "projected_limit_exceeded"]: 웹훅을 트리거한 이벤트 유형. 가능한 값:
  • "spend_tracked": 고객 id에 대해 지출이 추적될 때마다 전송.
  • "budget_crossed": 지출이 최대 예산을 초과했음을 나타냄.
  • "threshold_crossed": 지출이 임계값을 넘었음을 나타냄 (현재 예산의 85%와 95% 도달 시 전송).
  • "projected_limit_exceeded": "key"에만 해당 - 예상 지출이 소프트 예산 임계값을 초과할 것으로 예상됨을 나타냄.
• event_group Literal["customer", "internal_user", "key", "team", "proxy"]: 이벤트와 연결된 그룹. 가능한 값:
  • "customer": 특정 고객과 관련된 이벤트.
  • "internal_user": 특정 내부 사용자와 관련된 이벤트.
  • "key": 특정 키와 관련된 이벤트.
  • "team": 팀과 관련된 이벤트.
  • "proxy": 프록시와 관련된 이벤트.
• event_message str: 이벤트의 사람이 읽을 수 있는 설명.

다이제스트 모드 (Digest Mode, 알림 노이즈 줄이기)

기본적으로 LiteLLM은 모든 알림 이벤트에 대해 별도의 Slack 메시지를 보내요. llm_requests_hanging이나 llm_too_slow처럼 빈도가 높은 알림 유형에서는 하루에 수백 개의 중복 메시지가 생길 수 있어요.

다이제스트 모드는 구성 가능한 시간 창 안에서 중복 알림을 집계하고, 총 개수와 시간 범위가 담긴 단일 요약 메시지를 보내요.

구성 (Configuration)

특정 알림 유형에 대해 다이제스트 모드를 활성화하려면 general_settings에서 alert_type_config를 사용하세요:

general_settings:
  alerting: ["slack"]
  alert_type_config:
    llm_requests_hanging:
      digest: true
      digest_interval: 86400  # 24 hours (default)
    llm_too_slow:
      digest: true
      digest_interval: 3600   # 1 hour
    llm_exceptions:
      digest: true      # uses default interval (86400 seconds / 24 hours)

파라미터	타입	기본값	설명
digest	bool	false	이 알림 유형에 다이제스트 모드 활성화
digest_interval	int	86400 (24h)	시간 창(초). 알림은 이 간격 안에서 집계됨

동작 방식 (How It Works)

• 다이제스트가 활성화된 유형의 알림이 발생하면 즉시 전송되지 않고 (alert_type, request_model, api_base)로 그룹화돼요.
• 카운터가 간격 안에 알림이 몇 번 발생했는지 추적해요.
• 간격이 만료되면 단일 요약 메시지가 전송돼요:

Alert type: `llm_requests_hanging` (Digest)
Level: `Medium`
Start: `2026-02-19 03:27:39`
End: `2026-02-20 03:27:39`
Count: `847`
Message: `Requests are hanging - 600s+ request time`
Request Model: `gemini-3.8-flash`
API Base: `None`

제한사항 (Limitations)

• 인스턴스별 (Per-instance): 다이제스트 상태는 프록시 인스턴스별로 메모리에 보관돼요. 여러 인스턴스를 실행하면(예: 자동 확장 중인 Cloud Run) 각 인스턴스가 고유한 다이제스트를 유지하고 고유한 요약을 내보내요.
• 지속성 없음 (Not durable): 다이제스트 간격이 만료되기 전에 인스턴스가 종료되면 해당 인스턴스의 집계된 알림은 유실돼요.

리전 장애 알림 (Region-outage alerting, ✨ Enterprise 기능)

info

무료 2주 라이선스 받기

공급자 리전에 장애가 있을 때 알림을 설정해 봐요.

general_settings:
  alerting: ["slack"]
  alert_types: ["region_outage_alerts"]

기본적으로 한 리전의 여러 모델이 1분 안에 5+ 요청을 실패하면 트리거돼요. '400' 상태 코드 오류(즉 BadRequestErrors)는 집계되지 않아요.

임계값은 다음과 같이 제어하세요:

general_settings:
  alerting: ["slack"]
  alert_types: ["region_outage_alerts"]
  alerting_args:
    region_outage_alert_ttl: 60 # time-window in seconds
    minor_outage_alert_threshold: 5 # number of errors to trigger a minor alert
    major_outage_alert_threshold: 10 # number of errors to trigger a major alert

가능한 모든 알림 유형 (All Possible Alert Types)

👉 특정 알림 유형을 설정하는 방법은 여기를 보세요.

LLM 관련 알림 (LLM-related Alerts)

알림 유형	설명	기본 On
llm_exceptions	LLM API 예외 알림	✅
llm_too_slow	설정한 임계값보다 느린 LLM 응답 알림	✅
llm_requests_hanging	완료되지 않는 LLM 요청 알림	✅
cooldown_deployment	배포가 쿨다운에 들어가면 알림	✅
new_model_added	/model/new로 litellm 프록시에 새 모델이 추가되면 알림	✅
outage_alerts	특정 LLM 배포가 장애일 때 알림	✅
region_outage_alerts	특정 LLM 리전(예: us-east-1)이 장애일 때 알림	✅

예산 및 지출 알림 (Budget and Spend Alerts)

알림 유형	설명	기본 On
budget_alerts	예산 한도 또는 임계값 관련 알림	✅
spend_reports	팀이나 태그별 지출에 대한 주기적 리포트	✅
failed_tracking_spend	지출 추적 실패 시 알림	✅
daily_reports	일일 지출 리포트	✅
fallback_reports	LLM 폴백 발생에 대한 주간 리포트	✅

데이터베이스 알림 (Database Alerts)

알림 유형	설명	기본 On
db_exceptions	데이터베이스 관련 예외 알림	✅

관리 엔드포인트 알림 - 가상 키, 팀, 내부 사용자 (Management Endpoint Alerts)

알림 유형	설명	기본 On
new_virtual_key_created	새 가상 키가 생성되면 알림	❌
virtual_key_updated	가상 키가 수정되면 알림	❌
virtual_key_deleted	가상 키가 제거되면 알림	❌
new_team_created	새 팀 생성 알림	❌
team_updated	팀 상세가 수정되면 알림	❌
team_deleted	팀이 삭제되면 알림	❌
new_internal_user_created	새 내부 사용자 계정 알림	❌
internal_user_updated	내부 사용자 상세가 변경되면 알림	❌
internal_user_deleted	내부 사용자 계정이 제거되면 알림	❌

alerting_args 스펙 (alerting_args Specification)

파라미터	기본값	설명
daily_report_frequency	43200 (12시간)	배포 지연/실패 리포트 수신 빈도(초)
report_check_interval	3600 (1시간)	리포트를 보낼지 확인하는 주기(초, 백그라운드 프로세스)
budget_alert_ttl	86400 (24시간)	예산 초과 시 스팸 방지를 위한 예산 알림 캐시 TTL
outage_alert_ttl	60 (1분)	모델 장애 오류 수집 시간 창(초)
region_outage_alert_ttl	60 (1분)	리전 기반 장애 오류 수집 시간 창(초)
minor_outage_alert_threshold	5	사소한 장애 알림을 트리거하는 오류 수 (400 오류 미포함)
major_outage_alert_threshold	10	주요 장애 알림을 트리거하는 오류 수 (400 오류 미포함)
max_outage_alert_list_size	1000	모델/리전별 캐시에 저장할 최대 오류 수
log_to_console	false	true면 알림 페이로드를 console에 .warning 로그로 출력