LangSmith의 경고

LangSmith의 경고 (Alerts)

LLM 애플리케이션의 효과적인 관측성은 실패, 성능 저하, 회귀를 사전에 감지해야 해요. LangSmith의 경고 기능은 API 속도 제한 위반, 지연 시간 증가, 사용자 경험에 영향을 주는 피드백 점수 변화, 예상치 못한 비용 급증 같은 주요 문제를 식별하는 데 도움을 줍니다.

출처: 문서

참고: 자체 호스팅 버전 요구 사항: 경고 접근에는 Helm 차트 버전 0.10.3 이상이 필요합니다.

본문

LLM 애플리케이션의 효과적인 관측성은 실패, 성능 저하, 회귀를 사전에 감지해야 합니다. LangSmith의 경고 기능은 다음과 같은 주요 문제를 식별하는 데 도움이 됩니다:

  • 모델 제공자의 API 속도 제한 위반.
  • 애플리케이션의 지연 시간 증가.
  • 최종 사용자 경험을 반영하는 피드백 점수를 바꾸는 애플리케이션 변경.
  • LLM 사용으로 인한 예상치 못한 비용 급증.

LangSmith의 경고는 프로젝트 범위이며, 모니터링되는 각 프로젝트에 대해 별도 구성이 필요합니다.

팁: 경고는 Slack, PagerDuty, Dynatrace 또는 웹훅을 통한 어떤 HTTP 엔드포인트로든 라우팅할 수 있습니다. Webhook 탭에는 Microsoft Teams, 이메일, 자체 호스팅 배포의 Slack, Google Chat(미들웨어 필요)용 예시 레시피가 포함됩니다.

경고를 구성하려면 다음 단계를 따르세요.

1단계: 경고 생성으로 이동

UI에서 경고를 구성할 Tracing 프로젝트로 이동합니다. 페이지 오른쪽 상단의 Alerts 아이콘을 클릭해 해당 프로젝트의 기존 경고를 보고 새 경고를 설정합니다.

2단계: 메트릭 유형 선택

LangSmith는 다음 메트릭에 임계값 기반 경고를 제공합니다:

메트릭 유형 설명 사용 사례
런 개수 (Run Count) 시간 창에 걸친 총 런 수를 추적합니다. 파이프라인이 예상 볼륨으로 런을 생성하는지 모니터링하고 예상치 못하게 떨어지면 경고.
비용 (Cost) 시간 창에 걸친 런의 총 비용을 추적합니다. 비용이 예상 임계값을 초과하면 경고하도록 LLM 지출을 모니터링합니다. 비용 추적 구성이 필요합니다.
오류 (Errors) 오류 상태의 런을 추적합니다. 총 오류 수 또는 오류 비율(전체 런 중 오류 런 비율)에 경고합니다. 애플리케이션의 실패를 모니터링하거나 오류율이 허용 임계값을 초과하면 경고.
피드백 점수 (Feedback Score) 평균 피드백 점수를 측정합니다. 최종 사용자 피드백 또는 온라인 평가 결과를 추적해 회귀에 경고.
지연 시간 (Latency) 평균 런 실행 시간을 측정합니다. 애플리케이션의 지연 시간을 추적해 급증과 성능 병목에 경고.

또한 Errors와 Latency에 대해 필터 빌더를 사용해 Status, Run Type, Tag, Error 같은 필드에 조건을 쌓을 수 있습니다. 예를 들어 오류 경고를 Status가 error, Run Type이 llm, Tag가 support_agent, Error가 RateLimitExceeded와 일치하는 런으로 범위를 지정할 수 있습니다.

3단계: 경고 조건 정의

경고 조건은 여러 구성 요소로 구성됩니다:

  • 집계 방법 (Aggregation Method): 평균(Average), 백분율(Percentage), 또는 개수(Count).
  • 비교 연산자 (Comparison Operator): >=, <=, 또는 임계값 초과.
  • 임계값 (Threshold Value): 경고를 트리거하는 숫자 값.
  • 집계 창 (Aggregation Window): 메트릭 계산 시간 범위 (5분 또는 15분 중 선택).
  • 피드백 키 (Feedback Key): (피드백 점수 경고 전용) 모니터링할 특정 피드백 메트릭.

Alert Condition Configuration

예시: 스크린샷의 구성은 지난 5분 내 런의 5% 이상이 오류로 끝나면 경고를 생성합니다.

역사적 시간 창에 걸쳐 경고 동작을 미리 보면 선택한 임계값에서 얼마나 많은 데이터 포인트가, 어느 것이 경고를 트리거했을지(빨간색으로 표시) 이해할 수 있습니다. 예를 들어 프로젝트에 평균 지연 시간 임계값 60초를 설정하면 다음 스크린샷과 같이 잠재적 경고를 시각화할 수 있습니다.

Alert Metrics

4단계: 알림 채널 구성

Slack

LangSmith의 네이티브 Slack 통합을 사용해 경고 알림을 Slack 채널로 직접 보냅니다. 커스텀 웹훅이나 Slack 앱 구성이 필요하지 않습니다.

참고: 네이티브 Slack 알림 유형은 LangSmith Cloud에서만 제공됩니다. 자체 호스팅 배포의 경우 Webhook 탭의 웹훅 Slack 레시피를 사용하세요.

사전 준비 사항

  • LangSmith 조직에 연결된 Slack 워크스페이스. 아직 연결하지 않았다면, 이 알림 유형을 구성할 때 LangSmith가 인라인으로 연결하라는 메시지를 표시합니다.

  1. Slack 알림 구성

    1. 경고 설정의 Notification Settings 섹션에서 Slack을 선택합니다.
    2. 채널 선택기를 클릭합니다. 연결된 Slack 워크스페이스가 없으면 Connect Slack을 클릭하고 OAuth 흐름을 완료해 LangSmith를 인증합니다.
    3. 드롭다운에서 워크스페이스와 채널을 선택합니다. 채널이 즉시 나타나지 않으면 새로고침 아이콘을 클릭합니다.
    4. Save를 클릭해 알림 구성을 저장합니다.

    LangSmith가 선택한 공개 채널에 자동으로 참여합니다. 비공개 채널에 게시하려면 먼저 Slack에서 @LangSmith 앱을 해당 채널에 초대하세요.

  2. 통합 테스트 Send Test Notification을 클릭해 LangSmith가 채널에 도달할 수 있는지 확인합니다. 테스트 메시지가 채널에 있는지 확인합니다.

알림 형식

경고가 트리거되면 LangSmith가 구조화된 Slack 메시지를 게시합니다. 여기에는 다음이 포함됩니다:

  • 제목 (Headline): 경고 이름과 LangSmith 워크스페이스 이름.
  • 세부 라인 (Detail line): 메트릭 속성, 트리거된 값, 비교 연산자, 구성된 임계값, 집계 방법, 시간 창 — 예: Total Cost: $12.50 ≥ $5.00 · avg · 30 min.
  • 액션 버튼: View Alert(LangSmith의 경고 미리보기 링크) 및 View Runs(경고를 트리거한 필터된 런 링크).

PagerDuty

PagerDuty의 Events API v2를 사용해 PagerDuty를 알림 채널로 구성합니다. 이 통합은 중요한 LLM 애플리케이션 문제가 PagerDuty 인시던트를 트리거하게 해, 확립된 인시던트 관리 워크플로우를 통해 빠른 대응을 가능하게 합니다.

사전 준비 사항

  • 관리자 접근 권한이 있는 활성 PagerDuty 계정
  • PagerDuty의 적절한 서비스 수준 권한

LangSmith 커스텀 배포를 사용한다면 LangSmith 서비스의 이그레스 트래픽을 차단하는 방화벽 설정이 없는지 확인하세요.

  1. PagerDuty에서 서비스 만들기
    1. PagerDuty 계정에 로그인
    2. Services > Service Directory로 이동
    3. + New Service 클릭
    4. 다음 필드를 완료:
      • Name: 설명적 이름 제공 (예: "LangSmith Monitoring")
      • Description: 모니터링되는 애플리케이션에 대한 세부 정보 추가
      • Escalation Policy: 적절한 팀 에스컬레이션 정책 선택
      • Integration Type: "Events API V2" 선택
    5. Add Service 클릭해 서비스 생성
  2. 통합 키 얻기 서비스 생성 후 Integration Key를 가져옵니다:
    1. Service Directory에서 새로 만든 서비스를 찾아 클릭
    2. Integrations 탭 선택
    3. "Events API V2" 통합 찾기
    4. Integration Key(32자 영숫자 문자열) 복사
  3. PagerDuty로 LangSmith 경고 구성

    참고: 트리거 후 한 시간 내에 같은 경고를 다시 받으려면 PagerDuty에서 경고가 만든 활성 인시던트를 해결(resolve)해야 합니다.

    1. LangSmith 경고 설정의 알림 섹션에서 PagerDuty 선택
    2. 키 아이콘을 클릭해 Integration Key를 Workspace 시크릿으로 저장하거나 기존 시크릿을 선택. 모범 사례로, Integration Key를 직접 추가하지 않고 Workspace Secret으로 저장하는 것을 권장합니다. 이렇게 하면 워크스페이스의 여러 경고에서 같은 키를 재사용할 수 있습니다.
    3. 추가 알림 옵션 구성:
      • Severity: PagerDuty 인시던트 우선순위에 매핑
    4. Send Test Alert 클릭해 테스트 경고 보내기
    5. PagerDuty가 인시던트를 트리거하고 관련 LangSmith 경고 정보를 포함하는지 확인 문제 해결 PagerDuty에서 인시던트가 생성되지 않으면:
    • LangSmith에 Integration Key가 올바르게 입력되었는지 확인
    • PagerDuty 서비스가 활성 상태이고 유지보수 모드가 아닌지 확인
    • PagerDuty 계정에 Events API v2가 활성화되었는지 확인
    • PagerDuty에서 경고 트리거가 누락된 것 같으면, 같은 경고 규칙의 이전 트리거 후 1시간 내에 예상 트리거가 발생했는지, 이전 경고가 만든 인시던트가 아직 열려있는지 확인
    • LangSmith 인스턴스가 방화벽 뒤에 있으면 네트워크 연결 검토

Dynatrace

Dynatrace의 Events API v2를 사용해 Dynatrace를 알림 채널로 구성합니다. 이 통합은 LangSmith 경고 이벤트를 Dynatrace 환경으로 보내 더 넓은 인프라 모니터링과 상관시킬 수 있게 합니다.

사전 준비 사항

  • 활성 Dynatrace 환경(SaaS 또는 Managed).
  • events.ingest 범위가 있는 Dynatrace API 접근 토큰.

LangSmith 커스텀 배포를 사용한다면 LangSmith 서비스의 이그레스 트래픽을 차단하는 방화벽 설정이 없는지 확인하세요.

  1. Dynatrace에서 API 토큰 만들기
    1. Dynatrace 환경에 로그인
    2. Access Tokens로 이동
    3. Generate new token 클릭
    4. 설명적 이름 제공 (예: "LangSmith Alerts")
    5. Scopes 아래에서 events.ingest(Ingest events) 검색해 활성화
    6. Generate token 클릭
    7. 생성된 토큰을 복사해 안전하게 보관. 토큰은 한 번만 표시됩니다.
  2. Dynatrace 환경 URL 얻기 Dynatrace 환경 URL은 다음 형식을 따릅니다: 
    https://{your-environment-id}.live.dynatrace.com
    Dynatrace에 로그인했을 때 브라우저 URL 바에서 환경 ID를 찾을 수 있습니다.
  3. Dynatrace로 LangSmith 경고 구성
    1. LangSmith 경고 설정의 Notifications Settings에서 Dynatrace 선택
    2. Dynatrace 환경 URL 입력
    3. 키 아이콘을 클릭해 API 토큰을 workspace 시크릿으로 저장하거나 기존 시크릿 선택. 모범 사례로 API 토큰을 직접 추가하지 않고 workspace 시크릿으로 저장하세요. 이렇게 하면 워크스페이스의 여러 경고에서 같은 토큰을 재사용할 수 있습니다.
    4. 추가 알림 옵션 구성:
      • Event Type: Dynatrace 이벤트 유형 선택 (예: CUSTOM_ALERT, ERROR_EVENT)
    5. Send Test Notification 클릭해 테스트 경고 보내기
    6. 이벤트가 Dynatrace 환경에 나타나는지 확인 문제 해결 Dynatrace에 이벤트가 나타나지 않으면:
    • API 토큰에 events.ingest 범위가 있고 만료되지 않았는지 확인
    • 환경 URL이 올바르고 환경 ID를 포함하는지 확인
    • Authorization 헤더 형식이 Api-Token(Bearer 아님)을 사용하는지 확인
    • Dynatrace 환경이 활성 상태이고 접근 가능한지 확인
    • LangSmith 인스턴스가 방화벽 뒤에 있으면 네트워크 연결 검토

Webhook

웹훅은 경고 조건이 트리거되면 HTTP POST 요청을 보내 커스텀 서비스 및 타사 플랫폼과의 통합을 가능하게 합니다. 웹훅을 사용해 경고 데이터를 티켓팅 시스템, 채팅 애플리케이션 또는 커스텀 모니터링 솔루션으로 전달하세요.

사전 준비 사항

  • HTTP POST 요청을 받을 수 있는 엔드포인트
  • 수신 서비스에 대한 적절한 인증 자격 증명 (필요한 경우)
  1. 수신 엔드포인트 준비 LangSmith에서 웹훅을 구성하기 전에 수신 엔드포인트가:
    • HTTP POST 요청을 받을 수 있는지
    • JSON 페이로드를 처리할 수 있는지
    • 외부 서비스에서 접근 가능한지
    • 적절한 인증 메커니즘이 있는지(필요한 경우) 확인 LangSmith 커스텀 배포를 사용한다면 LangSmith 서비스의 이그레스 트래픽을 차단하는 방화벽 설정이 없는지 확인하세요.
  2. 웹훅 매개변수 구성 LangSmith UI의 Alerts 탭에 있는 Monitoring 섹션에서 + Alert를 클릭해 새 경고를 만듭니다. Notification Settings 섹션에서 다음 매개변수로 웹훅 구성을 완료하세요. 필수 필드
    • URL: 수신 엔드포인트의 전체 URL
      • 예: https://api.example.com/incident-webhook 선택 필드
    • Headers: 웹훅 요청과 함께 보내는 JSON 키-값 쌍
      • 일반적인 헤더:
        • Authorization: 인증 토큰용
        • Content-Type: 보통 application/json(기본값)
        • X-Source: 소스를 LangSmith로 식별
      • 헤더가 없으면 {} 사용
    • Request Body Template: 엔드포인트로 보내는 JSON 페이로드 커스터마이즈
      • 기본값: LangSmith는 아래 정의된 페이로드와 다음 추가 키-값 쌍을 페이로드에 추가해 보냅니다:
        • project_name: 경고가 범위로 지정된 LangSmith 프로젝트 이름.
        • workspace_name: LangSmith 워크스페이스 이름.
        • alert_rule_id: LangSmith 경고를 식별하는 UUID. 웹훅 서비스에서 중복 제거 키로 사용할 수 있습니다.
        • alert_rule_name: 경고 규칙 이름.
        • alert_rule_description: 경고 규칙 설명 (설정하지 않으면 빈 문자열).
        • alert_rule_type: 경고 유형 (2025년 4월 1일 기준 모든 경고는 threshold 유형).
        • alert_rule_attribute: 경고 규칙과 관련된 속성 - error_count, feedback_score, latency 또는 cost.
        • alert_rule_url: LangSmith에서 경고 규칙에 대한 직접 링크.
        • runs_url: LangSmith에서 경고를 트리거한 런에 대한 직접 링크.
        • triggered_metric_value: 임계값이 트리거된 시점의 메트릭 값.
        • triggered_threshold: 경고를 트리거한 임계값.
        • timestamp: 경고를 트리거한 타임스탬프.

    참고: LangSmith는 요청 본문에 템플릿 치환을 수행하지 않습니다. 위의 자동 채워진 필드는 구성하는 본문과 함께 최상위 키로 나가는 JSON에 병합됩니다. {alert_rule_name} 같은 자리 표시자 구문은 수신 서비스에 그대로 전송됩니다. 수신자가 들어오는 JSON에서 필드를 추출할 수 있는 경우에만(Power Automate Workflow, AWS Lambda, 커스텀 HTTP 핸들러 등) 실제 값으로 해석됩니다.

  3. 웹훅 테스트 Send Test Alert 클릭해 알림이 의도대로 작동하는지 웹훅 알림을 보냅니다. 문제 해결 웹훅 알림이 전달되지 않으면:
    • 웹훅 URL이 올바르고 접근 가능한지 확인
    • 인증 헤더가 올바르게 형식화되었는지 확인
    • 수신 엔드포인트가 POST 요청을 받는지 확인
    • 받았지만 거부된 요청에 대한 엔드포인트 로그 검토
    • 커스텀 페이로드 템플릿이 유효한 JSON 형식인지 확인

    경고: Send Test Alert은 다운스트림 응답을 검증하지 않습니다. 수신 엔드포인트가 오류(예: 400 또는 422 거부)를 반환해도 UI는 구성이 올바르게 작동하고 테스트 알림이 전달되었습니다라고 보고합니다. LangSmith 성공 메시지에만 의존하지 말고 수신자 측에서 수신을 항상 확인하세요. 엔드포인트 로그나 대상 플랫폼의 메시지 기록을 확인하세요. 보안 고려 사항

    • 웹훅 엔드포인트에 HTTPS 사용
    • 웹훅 엔드포인트에 인증 구현
    • 웹훅 소스를 검증하도록 헤더에 공유 시크릿 추가 고려
    • 처리 전에 들어오는 웹훅 요청 검증

예시 레시피

웹훅으로 Slack 알림 구성 chat.postMessage API를 사용해 LangSmith 경고를 Slack 채널로 보내도록 구성하는 예시입니다.

사전 준비 사항

  • Slack 워크스페이스 접근.
  • 경고를 설정할 LangSmith 프로젝트.
  • Slack 앱을 만들 권한.

1단계: Slack 앱 만들기

  1. Slack API Applications 페이지 방문
  2. Create New App 클릭
  3. From scratch 선택
  4. App Name 제공 (예: "LangSmith Alerts")
  5. 앱을 설치할 워크스페이스 선택
  6. Create App 클릭

2단계: 봇 권한 구성

  1. Slack 앱 구성의 왼쪽 사이드바에서 OAuth & Permissions 클릭
  2. Scopes 아래 Bot Token Scopes로 스크롤하고 Add an OAuth Scope 클릭
  3. 다음 범위 추가:
    • chat:write (앱으로 메시지 보내기)
    • chat:write.public (앱이 없는 채널로 메시지 보내기)
    • channels:read (기본 채널 정보 보기)

3단계: 앱을 워크스페이스에 설치

  1. OAuth & Permissions 페이지 상단으로 스크롤
  2. Install to Workspace 클릭
  3. 권한 검토 후 Allow 클릭
  4. 나타나는 Bot User OAuth Token 복사 (xoxb-로 시작)

4단계: 봇을 Slack 채널에 추가 경고를 받을 특정 채널에 봇을 추가합니다. 메시지 필드에서 봇을 언급(예: @botname)해 Slack 채널에 추가할 수 있습니다. 또한 LangSmith에서 웹훅 경고를 구성하려면 채널 ID가 필요합니다. 채널 세부 정보 > About을 열어 채널 ID를 찾을 수 있습니다.

5단계: LangSmith에서 웹훅 경고 구성

  1. LangSmith에서 프로젝트로 이동
  2. Alerts > Create Alert 선택
  3. 경고 메트릭과 조건 정의
  4. 알림 섹션에서 Webhook 선택
  5. 다음 설정으로 웹훅 구성: Webhook URL
https://slack.com/api/chat.postMessage

Headers

참고: «redacted:xox…»를 봇의 User OAuth Token으로 교체하세요.

{
  "Content-Type": "application/json",
  "Authorization": "Bearer «redacted:xox…»"
}

Request Body Template

참고: 4단계에서 찾은 값으로 {channel_id}를 채우는 것이 필요합니다. 나머지 필드인 alert_name, project_name, project_url은 경고 메시지에 추가 컨텍스트를 선택적으로 추가합니다. project_url은 브라우저 URL 바에서 찾을 수 있습니다. 쿼리 매개변수를 제외한 부분까지 복사하세요.

{
  "channel": "{channel_id}",
  "text": "{alert_name} triggered for {project_name}",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "🚨{alert_name} has been triggered"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Please check the following link for more information:"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "<{project-url}|View in LangSmith>"
      }
    }
  ]
}
  1. Save 클릭해 웹훅 구성 활성화

6단계: 통합 테스트

  1. LangSmith 경고 구성에서 Test Alert 클릭
  2. 지정한 Slack 채널에서 테스트 알림 확인
  3. 메시지에 예상 경고 정보가 포함되었는지 확인

(선택) 7단계: 요청 본문에서 경고 미리보기 연결 경고를 만든 후 선택적으로 웹훅의 요청 본문에서 그 미리보기로 링크할 수 있습니다. 이를 구성하려면:

  1. 경고 저장
  2. 경고 테이블에서 저장된 경고를 찾아 클릭
  3. 표시된 URL 복사
  4. "Edit Alert" 클릭
  5. 기존 프로젝트 URL을 복사한 경고 미리보기 URL로 교체

웹훅으로 Microsoft Teams 알림 구성 Workflows 앱(Power Automate)을 사용해 LangSmith 경고를 Microsoft Teams 채널로 보내도록 구성하는 예시입니다. 이 접근 방식은 흐름 내에서 들어오는 JSON에서 필드를 추출하므로, 자동 채워진 LangSmith 경고 필드가 Teams 메시지에서 올바르게 렌더링됩니다.

참고: Microsoft의 레거시 Office 365 Incoming Webhook 커넥터는 폐지되고 있습니다. 새 통합에는 Workflows 앱을 사용하세요.

사전 준비 사항

  • Workflows를 추가할 권한이 있는 Microsoft Teams 워크스페이스 접근.
  • 경고를 설정할 LangSmith 프로젝트.

1단계: Teams에서 Workflow 만들기

  1. Microsoft Teams에서 경고를 받을 채널로 이동
  2. 채널 이름 옆의 ... (More options) 메뉴 클릭
  3. Workflows 선택
  4. Post to a channel when a webhook request is received 템플릿 검색해 선택
  5. 연결을 확인하도록 로그인한 후 Next 클릭
  6. 경고가 게시될 팀과 채널 확인 후 Add workflow 클릭
  7. 생성된 HTTP POST URL 복사 — LangSmith에서 사용

2단계: Power Automate에서 메시지 커스터마이즈 (선택) 기본 워크플로우는 원시 JSON 본문을 카드로 게시합니다. 경고 세부 정보를 포맷하려면 Power Automate에서 흐름을 편집합니다:

  1. Power Automate 포털을 열고 만든 워크플로우 편집
  2. Post card in a chat or channel 동작 클릭
  3. Adaptive Card 필드에서 triggerOutputs()?['body/alert_rule_name'], triggerOutputs()?['body/project_name'], triggerOutputs()?['body/triggered_metric_value'], triggerOutputs()?['body/triggered_threshold'], triggerOutputs()?['body/timestamp'], triggerOutputs()?['body/alert_rule_url']를 사용해 들어오는 필드 참조
  4. 흐름 저장

3단계: LangSmith에서 웹훅 경고 구성

  1. LangSmith에서 프로젝트로 이동
  2. Alerts > Create Alert 선택
  3. 경고 메트릭과 조건 정의
  4. 알림 섹션에서 Webhook 선택
  5. 다음 설정으로 웹훅 구성: Webhook URL Teams Workflow의 HTTP POST URL을 붙여넣기:
https://prod-XX.westus.logic.azure.com:443/workflows/.../triggers/manual/paths/invoke?...

Headers

{
  "Content-Type": "application/json"
}

Request Body Template LangSmith는 자동 채워진 경고 필드(alert_rule_name, project_name, triggered_metric_value, triggered_threshold, timestamp, alert_rule_url 등)를 요청 본문의 최상위 JSON 키로 자동 병합합니다. Power Automate는 들어오는 페이로드에서 이 필드를 직접 읽으므로 빈 본문으로 충분합니다:

{}
  1. Save 클릭해 웹훅 구성 활성화

4단계: 통합 테스트

  1. LangSmith 경고 구성에서 Send Test Alert 클릭
  2. 지정한 Teams 채널에서 테스트 알림 확인
  3. 카드에 예상 경고 정보가 포함되었는지 확인

참조 구현 LangSmith 웹훅 페이로드(임계값 경고, 런 규칙, 일반 이벤트)를 형식화된 Teams Adaptive Card로 변환하는 작동 예시는 langsmith-teams-webhook 샘플 저장소를 참고하세요. 이 샘플은 Teams Workflow URL 앞에서 작은 Python 서비스로 실행되며, Power Automate 흐름 자체를 커스터마이즈할 필요가 없습니다.

웹훅으로 이메일 알림 구성 SendGrid의 Mail Send API를 사용해 LangSmith 경고가 이메일 알림을 보내도록 구성하는 예시입니다. HTTP API를 노출하는 어떤 트랜잭션 이메일 제공자(Mailgun, Amazon SES, Postmark 등)든 사용할 수 있습니다.

사전 준비 사항

  • 검증된 발신자 정체성(sender identity)이 있는 SendGrid 계정.
  • Mail Send 권한이 있는 SendGrid API 키.
  • 경고를 설정할 LangSmith 프로젝트.

1단계: SendGrid API 키 만들기

  1. SendGrid 대시보드에 로그인
  2. Settings > API Keys로 이동
  3. Create API Key 클릭
  4. Restricted Access 선택하고 Mail Send > Full Access 활성화
  5. Create & View 클릭, 키 복사 후 안전하게 보관

2단계: 발신자 이메일 검증

  1. SendGrid에서 Settings > Sender Authentication으로 이동
  2. 보내려는 주소에 대해 Domain Authentication(권장) 또는 Single Sender Verification 완료

3단계: LangSmith에서 웹훅 경고 구성

  1. LangSmith에서 프로젝트로 이동
  2. Alerts > Create Alert 선택
  3. 경고 메트릭과 조건 정의
  4. 알림 섹션에서 Webhook 선택
  5. 다음 설정으로 웹훅 구성: Webhook URL
https://api.sendgrid.com/v3/mail/send

Headers

참고: «redacted:SG…»를 SendGrid API 키로 교체하세요.

{
  "Content-Type": "application/json",
  "Authorization": "Bearer «redacted:SG…»"
}

Request Body Template

참고: [email protected]을 검증된 발신자 주소로, [email protected]을 수신자 주소로 교체하세요. SendGrid는 임의의 최상위 JSON 키에서 필드를 추출하지 않으므로 이 예시는 고정 제목과 본문을 사용합니다. 이메일에 경고별 값을 포함하려면 들어오는 페이로드를 읽고 SendGrid 요청을 렌더링하는 미들웨어(Power Automate 흐름, AWS Lambda, Zapier 웹훅 등)를 통해 LangSmith 웹훅을 라우팅하세요.

{
  "personalizations": [
    {
      "to": [
        {
          "email": "[email protected]"
        }
      ],
      "subject": "LangSmith alert triggered"
    }
  ],
  "from": {
    "email": "[email protected]",
    "name": "LangSmith Alerts"
  },
  "content": [
    {
      "type": "text/plain",
      "value": "A LangSmith alert was triggered. Open your LangSmith workspace to view the alert details, including the project, metric value, threshold, and timestamp."
    }
  ]
}
  1. Save 클릭해 웹훅 구성 활성화

4단계: 통합 테스트

  1. LangSmith 경고 구성에서 Send Test Alert 클릭
  2. 수신자 받은 편지함에서 테스트 알림 확인
  3. 이메일에 예상 경고 정보가 포함되었는지 확인

다른 이메일 제공자 사용 정적 인증 헤더를 받는 다른 트랜잭션 이메일 API에도 같은 패턴이 작동합니다. 제공자에 맞게 Webhook URL과 Headers를 변경합니다:

제공자 Webhook URL 인증 헤더 형식
Mailgun https://api.mailgun.net/v3/{your-domain}/messages Authorization: Basic <base64>
Postmark https://api.postmarkapp.com/email X-Postmark-Server-Token: <token>

각 제공자의 예상 페이로드 형식에 맞게 Request Body Template을 조정하세요. Amazon SES는 SES API가 요청별 AWS SigV4 서명을 요구하므로 직접 호환되지 않으며, 정적 헤더로 표현할 수 없습니다. SES를 사용하려면 미들웨어(예: HTTP 트리거가 있는 Lambda 함수)를 통해 라우팅하세요.

웹훅으로 Google Chat 알림 구성 (미들웨어 필요) Google Chat의 인커밍 웹훅 API(spaces.messages.create)는 최상위 수준에서 text 필드만 허용합니다. LangSmith는 12개의 경고 메타데이터 키를 모두 요청 본문의 최상위 필드로 병합하므로, Google Chat은 모든 요청을 400 오류로 거부합니다:

Invalid JSON payload received. Unknown name "project_name" at 'message': Cannot find field.

이를 피하는 Request Body Template은 없습니다. {"text": "hello", "project_name": "x"} 같은 최소 본문도 실패합니다. 이메일 레시피의 Amazon SES 메모와 유사하게 변환 계층(미들웨어)이 필요합니다.

옵션 A: Cloud Run 또는 Cloud Functions 미들웨어 (권장) 이 접근 방식은 LangSmith 웹훅을 받아 관련 필드를 추출하고 정리된 {"text": "..."} 페이로드를 Google Chat space 웹훅 URL로 전달하는 작은 HTTP 핸들러를 사용합니다.

사전 준비 사항

  • 인커밍 웹훅이 구성된 Google Chat space. Google Chat에서 space를 열고 Apps & integrations > Add webhooks로 이동해 웹훅을 만들고 URL을 복사하세요.
  • Cloud Run 또는 Cloud Functions가 활성화된 Google Cloud 프로젝트, 또는 이에 상응하는 호스팅.

1단계: 핸들러 배포 다음 Python 함수를 Cloud Run 서비스 또는 Cloud Function으로 배포합니다:

import json
import os
import re
import urllib.request
from urllib.parse import urlparse

ALLOWED_LINK_HOSTS = {"smith.langchain.com"}

def build_text(payload):
    def safe(v):
        # Strip angle brackets to prevent <url|label> link injection
        return re.sub(r"[<>]", "", str(v if v is not None else ""))

    parsed = urlparse(str(payload.get("runs_url") or ""))
    trusted = parsed.scheme == "https" and parsed.hostname in ALLOWED_LINK_HOSTS
    return (
        f"*{safe(payload.get('alert_rule_name'))}* triggered for "
        f"`{safe(payload.get('project_name'))}`\n"
        f"{safe(payload.get('alert_rule_attribute'))}: "
        f"{safe(payload.get('triggered_metric_value'))} "
        f"(threshold {safe(payload.get('triggered_threshold'))})"
        + (f"\n<{parsed.geturl()}|View runs>" if trusted else "")
    )

def handler(request):
    if request.headers.get("X-Webhook-Secret") != os.environ["LANGSMITH_SHARED_SECRET"]:
        return ("forbidden", 403)
    payload = request.get_json(silent=True) or {}
    urllib.request.urlopen(
        urllib.request.Request(
            os.environ["GCHAT_WEBHOOK_URL"],
            data=json.dumps({"text": build_text(payload)}).encode(),
            headers={"Content-Type": "application/json"},
            method="POST",
        ),
        timeout=10,
    )
    return ("ok", 200)

배포된 함수에 다음 환경 변수를 설정합니다:

  • GCHAT_WEBHOOK_URL: Google Chat space 웹훅 URL.
  • LANGSMITH_SHARED_SECRET: 선택한 시크릿 문자열(LangSmith에서 들어오는 요청 인증용).

2단계: LangSmith에서 웹훅 경고 구성 LangSmith 웹훅을 배포된 핸들러 URL로 지정합니다. Webhook URL

https://<your-cloud-run-service-url>/

Headers

{
  "Content-Type": "application/json",
  "X-Webhook-Secret": "<your-shared-secret>"
}

Request Body Template

{}

메타데이터 필드(alert_rule_name, project_name, runs_url 등)는 여기에 무엇을 넣든 LangSmith가 본문에 병합하므로 빈 본문으로 충분합니다.

참고: 핸들러에서 경고 필드 값의 * 또는 _를 제거하지 마세요. 이 문자들은 Google Chat의 기본 텍스트 서식에도 사용되지만 LangSmith 식별자(예: run_count)에도 나타납니다. 제거하면 메시지의 필드 이름이 손상됩니다.

참고: Google Chat은 space당 초당 1 메시지 쓰기 속도 제한을 적용하며, 해당 space에 쓰는 모든 웹훅이 공유합니다. 여러 LangSmith 경고가 같은 space로 라우팅되고 동시에 발화하면 일부 메시지가 누락될 수 있습니다.

옵션 B: Google Apps Script (인프라 불필요) Google Apps Script는 클라우드 인프라를 배포하지 않고도 경량 미들웨어 역할을 할 수 있습니다. script.google.com에서 새 Apps Script 프로젝트를 만들고 다음을 붙여넣은 후 웹 앱으로 배포합니다(자기 자신으로 실행, 모두에게 접근 허용):

function doPost(e) {
  var payload = JSON.parse(e.postData.contents);
  var secret = e.parameter.secret; // shared secret passed as query param
  if (secret !== PropertiesService.getScriptProperties().getProperty("LANGSMITH_SHARED_SECRET")) {
    return ContentService.createTextOutput("forbidden").setMimeType(ContentService.MimeType.TEXT);
  }
  var text =
    "*" + (payload.alert_rule_name || "") + "* triggered for `" + (payload.project_name || "") + "`\n" +
    (payload.alert_rule_attribute || "") + ": " + (payload.triggered_metric_value || "") +
    " (threshold " + (payload.triggered_threshold || "") + ")";
  UrlFetchApp.fetch(PropertiesService.getScriptProperties().getProperty("GCHAT_WEBHOOK_URL"), {
    method: "post",
    contentType: "application/json",
    payload: JSON.stringify({ text: text }),
  });
  return ContentService.createTextOutput("ok").setMimeType(ContentService.MimeType.TEXT);
}

Project Settings > Script Properties에서 GCHAT_WEBHOOK_URL과 LANGSMITH_SHARED_SECRET을 설정합니다.

경고: Apps Script 웹 앱은 커스텀 HTTP 요청 헤더를 읽을 수 없으므로, 공유 시크릿은 헤더가 아닌 쿼리 문자열 매개변수(?secret=...)로 전달해야 합니다. LangSmith 웹훅 URL에 Headers 필드가 아닌 그것을 포함하세요.

추가 리소스

모범 사례

  • 애플리케이션 중요도에 따라 민감도 조정
  • 더 넓은 임계값으로 시작하고 관찰된 패턴에 기반해 정교화
  • 경고 라우팅이 적절한 온콜 담당자에게 도달하는지 확인

더 알아보기

  • 알림 채널로 Slack, PagerDuty, Dynatrace 또는 웹훅을 설정하는 방법은 알림 채널 설정을 참고하세요.
  • 피드백 점수 기반 경고에 대한 자세한 내용은 Attach user feedback 문서를 확인해 보세요.