정식 와이드 이벤트

정식 와이드 이벤트는 결과를 설명하는 데 필요한 컨텍스트와 함께 완료된 하나의 작업 단위를 설명합니다. 연결이 끊어진 "시작됨", "데이터베이스 호출됨" 및 "완료됨" 메시지에서 요청을 재구성하는 대신 애플리케이션은 경로, 계정, 릴리스, 기간, 상태 및 분류된 오류 컨텍스트가 포함된 하나의 요청 결과를 내보냅니다.

이 패턴은 표준 로그 라인, 구조화된 이벤트 또는 와이드 이벤트라고도 합니다. Stripe는 요청에 대한 중요한 컨텍스트를 한 곳에서 수집하는 방법으로 표준 로그 라인을 설명했습니다. Honeycomb은 컨텍스트가 풍부한 구조화된 이벤트를 옵저버빌리티의 기초로 사용합니다. OpenTelemetry 로그 데이터 모델은 로그를 추적과 연관시킬 수 있는 표준 표현을 제공합니다. 이름과 운송 수단은 다르지만 유용한 디자인 질문은 동일합니다. 하나의 기록이 내러티브를 검색하지 않고도 의미 있는 결과를 설명할 수 있습니까?

"넓다"는 것은 이벤트가 목적이 있는 많은 분야를 다룰 수 있다는 것을 의미합니다. 메모리의 모든 개체를 복사한다는 의미는 아닙니다.

이벤트 그레인으로 시작하기

이벤트 그레인은 하나의 행으로 표현되는 것입니다. 필드를 선택하기 전에 적어 두십시오. 유용한 곡물은 다음과 같습니다:

• 하나의 API 요청이 최종 결과에 도달했습니다.
• 하나의 백그라운드 작업이 완료되었거나 재시도가 소진되었습니다.
• 하나의 웹훅 전달이 처리, 거부 또는 중복 제거되었습니다.
• 하나의 에이전트 실행이 완료, 실패 또는 안전 한계에 도달했습니다.
• 한 계정이 활성화, 청구 또는 보존 마일스톤에 도달했습니다.
• 제한된 지문으로 완료된 하나의 데이터베이스 작업

한 테이블에 곡물을 섞지 마십시오. 한 행이 때때로 요청 시도를 의미하고 때로는 모든 재시도에 대한 논리적 요청을 의미하는 경우 횟수와 비율이 모호해집니다. 두 보기가 모두 필요한 경우 별도의 attempt_number 또는 별도의 시도 이벤트를 사용하세요.

작업 수명 주기 동안 정식 이벤트를 빌드하고 최종 결과가 알려지면 내보냅니다.

const outcome = {
  request_id: requestId,
  route_template: "/api/projects/:id/sync",
  method: "POST",
  team_id: teamId,
  release: process.env.APP_RELEASE,
  environment: "production",
  started_at: new Date().toISOString(),
};

try {
  await syncProject();
  await telemetry.log("api_request_completed", {
    ...outcome,
    status: "success",
    status_code: 200,
    latency_ms: Math.round(performance.now() - startedAt),
  });
} catch (error) {
  await telemetry.log("api_request_completed", {
    ...outcome,
    status: "failed",
    status_code: statusFor(error),
    error_type: classifyError(error),
    latency_ms: Math.round(performance.now() - startedAt),
  });
  throw error;
}

계측 전달이 성공적인 요청을 실패한 요청으로 전환해서는 안 됩니다. 제한된 시간 초과를 사용하고, 배달 실패를 별도로 관찰하고, 내구성 있는 대기열이 필요한 중요한 이벤트를 명시적으로 결정합니다.

필드 분류 사용

유용한 표준 이벤트는 일반적으로 6개 필드 그룹에서 가져옵니다.

그룹화할 필드에 대해 제어된 범주를 사용합니다. error_type: "dependency_timeout"는 원시 예외 메시지보다 더 안정적입니다. 이름에 명시적 단위(_ms, _bytes, _usd 및 _count)를 사용합니다. 원시 URL 대신 정규화된 경로 템플릿을 사용하세요.

요청 ID, 계정 ID, 추적 ID와 같은 식별자는 높은 카디널리티입니다. 이는 종종 맞습니다. 차트 차원이 좋지 않은 경우에도 필터링 및 상관 관계에 유용합니다. 조사 이점이 개인정보 보호, 저장, 쿼리 비용을 정당화하는 경우에만 보관하세요. 카디널리티가 높은 필드를 참조하세요.

세 가지 실용적인 이벤트 형태

API 요청 이벤트는 분모와 결과를 함께 유지해야 합니다.

{
  "event_name": "api_request_completed",
  "request_id": "req_7d91",
  "route_template": "/api/projects/:id/sync",
  "method": "POST",
  "status_code": 503,
  "status": "failed",
  "error_type": "dependency_timeout",
  "latency_ms": 8420,
  "release": "2026.07.4",
  "schema_version": 2
}

백그라운드 작업 이벤트는 재시도 그레인을 명시적으로 만들어야 합니다.

{
  "event_name": "job_completed",
  "job_id": "job_82f1",
  "job_name": "sync_billing_account",
  "queue_name": "billing",
  "status": "failed",
  "terminal": true,
  "attempt_number": 4,
  "queue_wait_ms": 1820,
  "duration_ms": 9612,
  "error_type": "provider_timeout"
}

에이전트 실행 이벤트는 중요한 콘텐츠와 운영 결과를 분리해야 합니다.

{
  "event_name": "agent_run_completed",
  "run_id": "run_28bd",
  "workflow": "support_resolution",
  "agent_name": "support_agent",
  "model": "approved_model_alias",
  "status": "success",
  "tool_call_count": 3,
  "retry_count": 1,
  "duration_ms": 4820,
  "accepted": true,
  "prompt_version": "support-v4"
}

기본적으로 원시 프롬프트, 완성, 도구 인수 또는 검색된 문서를 기록하지 마십시오. 결과 이벤트는 고객 콘텐츠를 유지하지 않고도 볼륨, 신뢰성, 비용 및 승인 질문에 답할 수 있습니다.

개인정보 보호 경계를 좁게 유지하세요

모든 필드를 쿼리 결과, 대시보드, 내보내기 또는 지원 워크플로에 나타날 수 있는 데이터로 처리합니다. 이벤트 생성 시 허용 목록을 사용합니다. 인증 헤더, 쿠키, 자격 증명, 연결 문자열, 요청 또는 응답 본문, 웹후크 페이로드, 결제 세부정보 또는 무제한 고객 콘텐츠를 포함하지 마세요.

이메일 주소보다는 내부 계정 식별자를, 전체 URL보다는 경로 템플릿을, 예외 텍스트보다는 제어된 오류 범주를 선호합니다. 개인 데이터를 해싱한다고 해서 자동으로 안전해지는 것은 아닙니다. 안정적인 해시는 여전히 연결 가능한 식별자일 수 있습니다. 이벤트 추적 계획에 소유권, 목적, 보존 및 삭제 기대치를 문서화합니다.

복제 대신 상호 연관

정식 와이드 이벤트는 메트릭, 추적 및 자세한 진단 로그를 보완합니다. 이를 재현할 필요는 없습니다.

• 집계된 서비스 상태 및 인프라 알림에 대한 메트릭은 효율적으로 유지됩니다.
• 추적은 전체 범위에 걸쳐 타이밍과 인과성을 보여줍니다.
• 진단 로그는 스택 추적과 같은 로컬 세부 정보를 보존합니다.
• 정식 이벤트는 완료된 애플리케이션 또는 비즈니스 결과를 보존합니다.

더 깊은 증거가 다른 곳에 있는 경우 승인된 trace_id 또는 상관 관계 ID를 첨부하세요. 응답자는 범위 폭포 또는 스택 추적을 이벤트에 복사하지 않고도 실패한 결과 행에서 해당 추적으로 이동할 수 있습니다. 로그, 메트릭 및 추적 가이드에서 경계를 더 자세히 다루고 있습니다.

출시 전 스키마 발전 계획

이벤트에 소유자와 schema_version를 제공합니다. 필수 필드로 만들기 전에 선택적 필드를 추가하세요. 숫자 필드를 자동으로 문자열로 변경하거나 다른 의미로 필드 이름을 재사용하지 마십시오. 마이그레이션 중에 프로듀서와 기록 창이 수렴될 때까지 SQL에서 두 스키마 버전을 모두 지원합니다.

통제된 카테고리를 제한적으로 유지하세요. 새 오류 범주가 나타나면 대시보드, 알림 또는 Runbook이 변경되는지 검토하세요. 애플리케이션 업그레이드로 인해 경로나 워크플로의 이름이 바뀌는 경우 구현 이름과 별도로 안정적인 분석 이름을 유지하세요.

스키마 진화 가이드 및 데이터 유형 및 null 허용 여부에서는 이러한 롤아웃 선택 사항을 설명합니다.

편의성이 아닌 의사결정에 따른 샘플

드문 실패, 최종 작업 결과, 청구 변경, 보안 조치 또는 정확한 조정에 사용되는 이벤트를 샘플링하지 마십시오. 성공적인 대용량 요청은 결정적 또는 속도 기반 샘플링의 후보가 될 수 있지만 다운스트림 분석에 추정 총계가 필요한 경우 샘플링 결정과 가중치를 유지합니다.

저장된 저장 공간과 잃어버린 질문을 비교해보세요. 샘플링을 통해 지연 시간 분포를 보존하면서 정확한 계정 영향 계산을 불가능하게 만들 수 있습니다. 이벤트 샘플링 가이드에서는 안전한 경우와 안전하지 않은 경우를 설명합니다.

SQL을 사용하여 이벤트 유효성을 검사합니다.

이벤트는 가장 많은 필드를 포함할 때가 아니라 방어 가능한 SQL로 의도한 질문에 답할 때 완료됩니다. 비프로덕션 환경에서 성공, 실패, 재시도, 시간 초과, 중복 전달, null 필드 및 지연 도착 경로를 연습합니다. 대시보드를 구축하기 전에 저장된 스키마를 검사하세요.

API 결과 이벤트의 경우 개수와 분모로 시작합니다.

SELECT
  route_template,
  COUNT(*) AS requests,
  SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failures,
  100.0 * SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END)
    / NULLIF(COUNT(*), 0) AS failure_rate_pct,
  approx_percentile_cont(latency_ms, 0.95) AS p95_latency_ms
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
  AND environment = 'production'
GROUP BY route_template
HAVING COUNT(*) >= 20
ORDER BY failure_rate_pct DESC;

비율 외에 볼륨을 유지하고, 기간을 비교할 때 불완전한 시간 버킷을 제외하고, 재시도가 시도인지 아니면 논리적 결과인지 명시합니다. 운영상 중요해지는 쿼리에 대한 결정적 고정 장치와 예상 결과를 저장합니다. CI 가이드의 계측 테스트에서는 계약이 표류하지 않도록 하는 방법을 보여줍니다.

한 번에 하나의 워크플로 마이그레이션

전체 로그 스트림을 교체하지 마십시오. 하나의 반복 결정을 선택하고, 기존 텔레메트리 옆에 표준 이벤트를 내보내고, 동일한 닫힌 UTC 창에서 이전 답변과 새 답변을 이중 실행합니다. 재시도 처리, 경로 정규화, 타임스탬프, Null 및 제외의 차이점을 조사합니다. 소유자가 의미 체계를 수락한 후에만 새 쿼리를 대시보드 또는 알림로 승격하세요.

실제 경로는 다음과 같습니다.

1. 이벤트 그레인 및 결정을 정의합니다.
2. 허용 목록에 있는 필드 계약을 작성합니다.
3. 계측 터미널 결과.
4. 전달 및 스키마를 확인합니다.
5. 픽스처를 사용하여 쿼리를 테스트합니다.
6. 이중 실행 보고서 또는 알림.
7. 중복 소비자만 폐기합니다.

구조화된 로그 관리 가이드, 구조화된 이벤트와 텍스트 로그 비교 또는 전체 마이그레이션 가이드를 계속 진행하세요.