For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/web/setup-observability.md (or send Accept: text/markdown).
옵저버빌리티 설정
오류 추적, 제품 분석, 실패 알림 — 전부 선택 사항.
작업이 실패할 때 유용한 정보 찾기
관찰 가능성은 앱이 수행한 작업을 확인하는 것을 의미합니다. 웹 서버를 실행하는 터미널에서 시작합니다. 실패한 작업 하나를 반복하고 첫 번째 오류와 상관 ID, 동일한 요청의 메시지를 연결하는 레이블을 읽습니다. 도움을 요청할 때 명령, 시간 및 삭제된 오류를 공유하세요. .env 파일이나 토큰을 공유하지 마세요.
호스팅된 오류 보고서의 경우 상태 및 작업에 따라 apps/web/.env.local 또는 호스트 환경 대시보드에서 지원되는 모니터링 설정을 구성합니다. 서버를 저장하고 다시 시작하십시오. 테스트 환경에서 제어된 테스트 실패를 트리거하고 올바른 작업 공간 컨텍스트로 나타나는지 확인합니다. 구성 중인 모니터링은 이벤트 수신을 증명하지 않습니다.
ALERT_WEBHOOK_URL는 작업 및 터미널 웹훅 전달 실패 경고에 대한 선택적 HTTPS 대상입니다. 필요한 경우 호환되는 수신 엔드포인트를 생성하고 해당 URL 서버측을 저장하세요. 그렇지 않으면 비워 두십시오. 에이전트에게 하나의 실패를 시뮬레이션하고 텍스트에 비밀이 없는 정확히 하나의 경고를 확인하도록 요청하세요. 이 테스트를 위해 고객 계정에서 유급 작업이나 실패를 유발하지 마십시오.
워크스페이스별 감사 추적 유지
감사 레코드는 워크스페이스 내의 프로바이더 구성 업데이트 같은 변경을 캡처합니다. 그 레코드를 읽거나 쓰기 전에 인증된 워크스페이스를 해석하고, 제품 고유 이벤트를 추가할 때 그 경계를 유지하세요.
액션과 그것을 이해하는 데 필요한 식별자를 기록하세요. 프로바이더 자격 증명과 기타 민감한 값은 감사 페이로드와 로그에서 제외해야 합니다.
제품 이벤트 캡처
관찰 가능성 패키지는 AnalyticsClient 어댑터와 워크스페이스 범위 AnalyticsEvent 값을 노출합니다. 각 이벤트는 이름, distinct ID, workspaceId, 선택적 속성을 가집니다.
createObservability를 사용해 구성된 분석 클라이언트를 통해 이벤트를 라우팅하세요. 구조화된 속성은 전송 전에 삭제됩니다. 민감한 자유 텍스트도 이벤트 이름과 속성 값에서 제외하세요.
안전한 컨텍스트로 오류 보고
ErrorClient는 workspaceId 태그와 구조화된 추가 컨텍스트로 예외를 캡처합니다. 공유 관찰 가능성 계층은 구성된 클라이언트로 전달하기 전에 예외와 민감한 컨텍스트를 삭제합니다.
로컬 어댑터로 모니터링 프로바이더를 호출하지 않고 캡처된 이벤트와 예외를 검증하세요. 외부 대상을 활성화하기 전에 워크스페이스 태그가 유지되고 자격 증명이 제거되는지 테스트하세요.
작업, 작업 및 웹훅 전반에 걸쳐 요청을 따릅니다.
항목 경계는 원래 요청을 트리거하는 작업에 연결하는 corr_<uuid> 상관 관계 ID를 생성합니다. AI 작업 제출은 작업 페이로드 및 ai_task_submitted 이벤트에 ID를 스탬프 처리하고, 모든 청구 웹후크 수신기는 요청당 하나를 생성하고, 스케줄러는 발송된 작업당 하나를 생성합니다.
동일한 ID가 job.completed 및 ai_task_completed 이벤트 속성, CaptureException 추가 항목, webhook_event 원장 페이로드 및 각 webhook_delivery 페이로드 메타를 타고 있으므로 구독자가 수신하는 서명된 본문 내부에 배치됩니다. 누락되거나 잘못된 형식의 ID는 허용됩니다. 소비자는 이전 행을 거부하는 대신 새로운 ID를 생성합니다.
실제 실패에 대한 경고
ALERT_WEBHOOK_URL를 JSON POST 모양의 {텍스트, 이름, 심각도, 컨텍스트}를 허용하는 HTTPS 엔드포인트로 설정합니다. Slack 스타일의 수신 웹훅은 그대로 작동합니다. 경고는 5초 제한 시간으로 발생하고 잊어버리며, 전달 실패는 콘솔 경고 1회를 기록하며, 변수가 설정되지 않은 동안 경고는 놉을 뜹니다.
발송된 경고는 job.failed(경고 — 작업 핸들러가 발생했거나 작업 유형을 알 수 없음) 및 webhook.delivery_failed(중요 — 나가는 전달이 최종 시도 후 최종 실패에 도달한 경우에만 해당. 일반 재시도는 조용히 유지되며 각 전달 행은 최대 한 번 경고합니다).
기간 측정 및 구조화된 로그 스트리밍
serverObservability.measure는 비동기 작업의 시간을 측정하고 원래 오류를 마스킹하지 않고 성공 및 실패 시에 DurationMs를 포함하는 <name>.duration 분석 이벤트를 내보냅니다. ai.task.execute 작업 실행은 이미 래핑되어 있으므로 작업 실행 기간은 구성된 분석 클라이언트에 속합니다.
serverObservability.logger는 환경 및 서비스 기반 필드를 사용하여 레코드당 하나의 JSON 라인을 stdout에 기록합니다. 공유 편집 레이어는 라인이 방출되기 전에 비밀을 제거합니다.
설치 및 설정
1. 오류 보고용으로 SENTRY_DSN을 설정하세요 — 예외는 상관 ID와 워크스페이스 태그와 함께 캡처됩니다.
2. 제품 분석용으로 NEXT_PUBLIC_POSTHOG_KEY와 NEXT_PUBLIC_POSTHOG_HOST를 설정하세요 — 이들은 설계상 공개 브라우저 값입니다.
3. 실패 알림용으로 ALERT_WEBHOOK_URL을 Slack 호환 엔드포인트로 설정하세요 — 앱이 {text, name, severity, context} JSON을 POST합니다.
SENTRY_DSN=https://…@….ingest.sentry.io/…
NEXT_PUBLIC_POSTHOG_KEY=phc_…
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
ANALYTICS_PROVIDER=off # off | local | plausible | posthog
# ANALYTICS_SITE_ID=
# ANALYTICS_HOST=
ALERT_WEBHOOK_URL=https://hooks.slack.com/services/…구현 워크플로
옵저버빌리티 계층은 전달 전에 예외를 살균하고 알려진 시크릿 키를 삭제합니다 — 하지만 자유 형식 이벤트 텍스트는 작성자 책임이므로 자격 증명을 이벤트 이름과 속성 값에서 빼세요.
로컬 어댑터는 Sentry나 PostHog를 호출하지 않고 캡처된 이벤트와 예외에 대해 어서트하게 합니다. 이 변수들은 로컬 실행에 필요 없습니다.
신호가 흐르나요? 커스텀 도메인 설정으로 계속하세요.
검증 및 문제 해결
테스트 예외를 발생시켜 페이로드에서 시크릿이 제거된 채 Sentry에 도착하는지 확인하고, 연결된 실패가 ALERT_WEBHOOK_URL로 POST되는지 검사하세요. 이벤트가 도착하지 않으면 DSN/키 쌍과 서버에서 호스트 도달 가능성을 확인하세요.
설정을 계속하려면 커스텀 도메인 설정 가이드를 읽어보세요.