첫 번째 구조화된 이벤트 보내기

이 연습에서는 하나의 합성 API 결과를 Telemetry로 보냅니다. 목표는 200 응답을 받는 것 뿐만이 아닙니다. 원시 요청 페이로드를 수집하지 않고 SQL, 대시보드, 알림 및 향후 디버깅을 지원할 수 있는 이벤트 계약으로 시작하는 것입니다.

시작하기 전에

팀 설정 → API 키에서 팀과 write 범위 키를 만듭니다. 로컬 환경 변수 또는 보안 비밀 관리자에 값을 유지하세요.

export TELEMETRY_API_KEY="replace-with-your-key"

브라우저 JavaScript, 모바일 애플리케이션, 공개 저장소 또는 스크린샷에 팀 키를 노출하지 마세요. 범위 및 순환 지침은 API 키 및 인증을 참조하세요.

완료된 워크플로 하나를 선택하세요.

애플리케이션이 결과를 알고 있는 경계에서 시작하십시오. 좋은 첫 번째 이벤트는 다음과 같습니다.

• api_request_completed
• background_job_completed
• webhook_processing_completed
• checkout_completed
• agent_run_completed

something_happened와 같은 일반 메시지보다 완료된 결과를 선호합니다. 안정적인 이벤트 이름은 모든 프로듀서와 쿼리에 동일한 결과를 제공합니다.

이 예에서는 합성 API 요청을 사용합니다.

{
  "route_template": "/api/reports/:report_id",
  "method": "POST",
  "status": "success",
  "status_code": 200,
  "latency_ms": 184,
  "release": "local-demo",
  "environment": "development",
  "request_id": "req_demo_001"
}

URL은 식별자가 포함된 원시 URL이 아닌 경로 템플릿입니다. 이벤트에는 분류된 결과 필드와 안전한 상관 관계 식별자가 포함되어 있지만 요청 본문, 인증 헤더, 쿠키 또는 고객 콘텐츠는 포함되어 있지 않습니다.

cURL로 이벤트 보내기

curl https://api.telemetry.sh/log \
  -H "Authorization: Bearer $TELEMETRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "table": "api_request_completed",
    "data": {
      "route_template": "/api/reports/:report_id",
      "method": "POST",
      "status": "success",
      "status_code": 200,
      "latency_ms": 184,
      "release": "local-demo",
      "environment": "development",
      "request_id": "req_demo_001"
    }
  }'

SDK 또는 API 버전이 이 예와 다른 경우 로그 API에 문서화된 정확한 요청 형태를 사용하세요.

JavaScript에서 동일한 이벤트를 보냅니다.

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

await telemetry.log("api_request_completed", {
  route_template: "/api/reports/:report_id",
  method: "POST",
  status: "success",
  status_code: 200,
  latency_ms: 184,
  release: "local-demo",
  environment: "development",
  request_id: "req_demo_001"
});

신뢰할 수 있는 서버 측 코드에서 SDK를 초기화합니다. 서비스 전체에서 필드 이름과 단위를 일관되게 유지하십시오. 예를 들어 초와 밀리초를 혼합하는 대신 항상 latency_ms에 기간을 저장하십시오.

성공의 의미

성공적인 전송은 API가 이벤트를 수락했다는 것만 증명합니다. 이벤트 수집 확인을 계속 진행하여 테이블 이름, 유추된 유형, 생성된 타임스탬프, 정확한 행을 확인하세요. 첫 번째 이벤트 계약이 쿼리 가능하고 안전할 때까지 더 많은 워크플로를 계측하지 마세요.

더 큰 스키마를 보려면 이벤트 스키마 설계를 읽어보세요. 민감한 필드의 경우 민감한 데이터 수정을 사용하세요.