알림

알림 (Alerts)

Alerts는 비용과 품질 문제가 사용자에게 영향을 미치기 전에 잡을 수 있게 해줘요. Slack으로 알림을 받거나, GitHub Actions를 트리거하거나, 자체 웹훅(Webhook)을 호출할 수 있어요.

출처: 문서

본문

이 기능은 어디서 사용할 수 있나요?

  • Hobby: 사용 가능
  • Core: 사용 가능
  • Pro: 사용 가능
  • Enterprise: 사용 가능
  • Self Hosted: Langfuse v4+

Langfuse Cloud에서 조직당 alert 수는 플랜에 따라 달라져요: 2 (Hobby), 20 (Core), 50 (Pro), 100 (Enterprise). Langfuse v4를 실행하는 셀프호스팅 배포에는 alert 제한이 없어요.

Alerts는 비용과 품질 문제가 사용자에게 영향을 미치기 전에 잡을 수 있게 해줘요.

Slack으로 알림을 받거나, GitHub Actions를 트리거하거나, 자체 웹훅을 호출할 수 있어요.

Alerts list showing severity, name, and tags for each alert

알림 만들기 (Create an alert)

프로젝트의 Alerts로 이동해 New Alert를 클릭하세요.

메트릭 구성하기 (Configure the metric)

알림이 측정할 데이터를 선택하세요.

Field Description
Data source Observations, Scores (numeric), Scores (categorical), 또는 Scores (boolean)
Metric 집계 + 측정 방식 — 예: avg latency, count, p95 cost
Filters 데이터셋 좁히기 (모델 이름, 태그, 사용자 ID, 환경, 불리언 값 등)

불리언 점수의 경우 평균값이 true인 점수의 비율이에요. 정책 검사 통과율이나 탐지된 환각 비율 같은 비율에 대한 알림에 사용하세요.

알림 조건 설정하기 (Set alert conditions)

메트릭 값이 어느 범위에 속할 것으로 기대하는지 선택하세요.

Field Description
Operator >, ≥, <, ≤, =, ≠ — 알림 조건의 방향
Alert threshold 필수. 이 값을 넘으면 심각도가 ALERT로 설정돼요.
Warning threshold 선택 사항. 이 값(alert threshold 이전)을 넘으면 심각도가 WARNING으로 설정돼요.
Window 각 평가가 얼마나 과거를 보는지 (예: 1시간, 1일, 1주)

고급 설정 구성 (원하는 경우) (Configure advanced settings (optional))

데이터가 없거나 알림이 오래 해결되지 않은 채 남아 있는 경우의 엣지 케이스에 대한 특별 처리를 선택하세요.

데이터 없음 처리 — 쿼리가 데이터를 반환하지 않을 때:

Mode Behavior
Treat missing data as 0 (기본값) null을 0으로 취급하고 임계값과 비교
Keep the previous severity 이전 심각도 유지; 알림 전송 안 함
Show severity NO_DATA NO_DATA 심각도 기록; 알림 전송 안 함
Notify after sustained NO_DATA NO_DATA 심각도 기록; 구성 가능한 지연 후 알림 전송

재알림(Renotify) — 심각도가 높게 유지되는 동안 재알림 여부:

Mode Behavior
Off (기본값) 각 심각도 전환 시 한 번 알림
Every N minutes 심각도가 지속되는 동안 N분마다 재알림 (1–10,080분)

알림 채널 선택하기 (Select a notification channel)

Automations 패널에서 하나 이상의 자동화를 선택하세요. 알림이 발생하면 Langfuse가 각 선택된 자동화로 이벤트를 게시하고, 자동화가 구성된 액션(Slack 메시지, 웹훅 등)을 실행해요.

여기에 연결하기 전에 액션을 설정하려면 Automations를 참고하세요.

이름 지정 및 저장 (Name and save)

알림에 설명적인 이름(최대 200자)과 선택적 태그를 지정한 뒤 Save를 클릭하세요. 제목을 비워두면 알림 구성에서 자동 생성할 수도 있어요. 알림은 즉시 ACTIVE가 되고 첫 평가를 예약해요.

알림 상태 (Alert states)

각 알림은 매 평가 후 갱신되는 심각도를 가져요.

Severity Meaning
UNKNOWN 초기 상태 — 아직 평가되지 않음
OK 메트릭이 범위 내에 있음
WARNING 메트릭이 warning 임계값을 넘음
ALERT 메트릭이 alert 임계값을 넘음
NO_DATA 쿼리가 데이터를 반환하지 않았고 no-data 모드가 Show severity NO_DATA 또는 Notify after sustained NO_DATA임
PAUSED 알림이 일시정지됨; 평가 실행 안 함

알림이 발화되는 시점:

  • 위반 (Breach, UNKNOWN | OK → WARNING | ALERT): 항상 알림.
  • 복구 (Recovery, WARNING | ALERT → OK): 항상 알림.
  • 데이터 없음 (No data, NO_DATA ↔ WARNING | ALERT | OK | UNKNOWN): no-data 모드가 Notify after sustained NO_DATA일 때만 알림.
  • 지속 심각도 (Sustained severity, WARNING → WARNING, ALERT → ALERT): Renotify가 활성화된 경우에만 알림.

알림 일시정지, 재개, 삭제 (Pause, resume, or delete an alert)

알림 목록이나 상세 페이지에서 행 액션 메뉴로 알림을 Pause하거나 Resume할 수 있어요. 일시정지된 알림은 모든 평가를 건너뛰고 심각도가 PAUSED로 고정돼요. 재개하면 ACTIVE로 돌아가고 다음 평가를 예약해요.

알림을 영구히 제거하려면 상세 페이지를 열고 휴지통 아이콘을 클릭한 뒤 Delete alert를 확인하세요. 이 작업은 되돌릴 수 없어요.

자동화 (Automations)

Automations는 알림을 외부 시스템으로 라우팅해요. 각 자동화는 트리거(알림 심각도 변경)와 액션(외부 시스템으로 보내는 알림)을 짝지어요.

세 가지 알림 채널을 사용할 수 있어요:

Action What it does
Slack 포맷된 alert 메시지를 Slack 채널에 게시
Webhook HMAC 서명된 JSON 페이로드로 엔드포인트에 HTTP POST
GitHub Actions GitHub 저장소에서 workflow_dispatch 이벤트 발화

다른 채널이 추가되길 원한다면 GitHub discussions에 요청을 남겨주세요.

알림 자동화 만들기 (Create an alert automation)

  1. Automations로 이동해 Create Automation을 클릭하세요.
  2. 이벤트 소스로 Alert를 선택하세요.
  3. 액션 타입(Slack, Webhook, 또는 GitHub Actions)을 선택하세요.
  4. 액션을 구성하세요: Slack 채널, 웹훅 엔드포인트 URL, 또는 GitHub 저장소 dispatch URL·이벤트 유형·personal access token을 제공하세요.
  5. 자동화에 이름을 지정하고 Save를 클릭하세요. 알림을 만들거나 편집할 때 Automations 패널에 나타나요.

알림을 자동화에 연결하기 (Link an alert to an automation)

  1. 새 alert automation을 만들거나 기존 것을 편집하세요.
  2. 새 알림을 만들거나 기존 것을 편집하세요.
  3. 알림 편집기의 notifications 섹션에 있는 Automations 패널에서 자동화를 선택하세요.
  4. Save를 클릭해 알림을 선택한 자동화에 연결하세요.

알림은 심각도가 전환될 때마다 연결된 모든 자동화를 발화해요 (Alert states 참고).

배달에 5번 연속 실패하면 Langfuse가 자동으로 해당 자동화의 트리거를 비활성화해요. 엔드포인트가 복구되면 Automations 페이지에서 다시 활성화하세요.

웹훅 페이로드 (Webhook payload)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-07-10T10:30:00Z",
  "type": "monitor-alert",
  "apiVersion": "v1",
  "payload": {
    "monitorId": "monitor_abc123",
    "projectId": "proj_xyz789",
    "permalink": "https://cloud.langfuse.com/project/proj_xyz789/monitors/monitor_abc123",
    "message": {
      "title": "avg latency crossed alert threshold",
      "body": "avg latency is 1234 ms (threshold: 1000 ms) over the last 1 hour"
    },
    "severity": "ALERT",
    "timestamp": "2024-07-10T10:30:00Z",
    "fromTimestamp": "2024-07-10T09:30:00Z",
    "toTimestamp": "2024-07-10T10:30:00Z",
    "view": "observations",
    "filters": [],
    "window": "1h"
  }
}

엔드포인트는 서명된 JSON 본문을 받아요.

페이로드는 레거시 monitor 명명(type, monitorId, permalink)을 유지해 기존 통합이 변경 없이 계속 동작해요.

서명 검증은 프롬프트 웹훅과 동일하게 동작해요 — HMAC 검증 코드는 Webhooks를 참고하세요.

평가기에서 알림 만들기 (Create alerts from evaluators)

평가기 페이지에서 직접 score 및 cost 알림을 만들 수 있어요. Langfuse가 메트릭과 필터를 미리 채우고, 평가기 테스트 run을 제외하며, 평가기에 이미 연결된 알림을 보여줘요.

지원되는 알림 유형, 기본값, 평가기 워크플로는 Monitor evaluator results를 참고하세요.

GitHub Discussions

더 알아보기 (Learn more)