> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 감사, 분석, 오류

워크스페이스 컨텍스트와 삭제된 이벤트 데이터로 활동을 이해하세요.

## 작업이 실패할 때 유용한 정보 찾기

관찰 가능성은 앱이 수행한 작업을 확인하는 것을 의미합니다. 웹 서버를 실행하는 터미널에서 시작합니다. 실패한 작업 하나를 반복하고 첫 번째 오류와 상관 ID, 동일한 요청의 메시지를 연결하는 레이블을 읽습니다. 도움을 요청할 때 명령, 시간 및 삭제된 오류를 공유하세요. .env 파일이나 토큰을 공유하지 마세요.

호스팅된 오류 보고서의 경우 상태 및 작업에 따라 apps/web/.env.local 또는 호스트 환경 대시보드에서 지원되는 모니터링 설정을 구성합니다. 서버를 저장하고 다시 시작하십시오. 테스트 환경에서 제어된 테스트 실패를 트리거하고 올바른 작업 공간 컨텍스트로 나타나는지 확인합니다. 구성 중인 모니터링은 이벤트 수신을 증명하지 않습니다.

ALERT_WEBHOOK_URL는 작업 및 터미널 웹훅 전달 실패 경고에 대한 선택적 HTTPS 대상입니다. 필요한 경우 호환되는 수신 엔드포인트를 생성하고 해당 URL 서버측을 저장하세요. 그렇지 않으면 비워 두십시오. 에이전트에게 하나의 실패를 시뮬레이션하고 텍스트에 비밀이 없는 정확히 하나의 경고를 확인하도록 요청하세요. 이 테스트를 위해 고객 계정에서 유급 작업이나 실패를 유발하지 마십시오.

[애플리케이션 상태 및 작동 설정 확인](https://supastack.dev/ko/docs/web/security.md)

[로컬 단말기의 오류 진단](https://supastack.dev/ko/docs/web/troubleshooting.md)


## 워크스페이스별 감사 추적 유지

감사 레코드는 워크스페이스 내의 프로바이더 구성 업데이트 같은 변경을 캡처합니다. 그 레코드를 읽거나 쓰기 전에 인증된 워크스페이스를 해석하고, 제품 고유 이벤트를 추가할 때 그 경계를 유지하세요.

액션과 그것을 이해하는 데 필요한 식별자를 기록하세요. 프로바이더 자격 증명과 기타 민감한 값은 감사 페이로드와 로그에서 제외해야 합니다.


## 제품 이벤트 캡처

관찰 가능성 패키지는 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에 기록합니다. 공유 편집 레이어는 라인이 방출되기 전에 비밀을 제거합니다.


## 다음

[배포 체크리스트](https://supastack.dev/ko/docs/web/deployment.md)