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

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

시작하기 전에

홈페이지의 설정 프롬프트를 복사했다면 그 안의 anon_… 키로 계정 없이 이벤트를 보내고 쿼리할 수 있습니다.

계정이 있다면 다음 단계에서 이벤트를 읽을 수 있도록 팀 설정 → API 키에서 read-and-write 키를 만드세요. 이벤트만 보내는 앱은 ingest 키를 사용할 수 있습니다.

키는 로컬 환경 변수나 비밀 관리 도구에 보관하세요.

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

익명 키, 읽기 전용 키, 읽기·쓰기 키는 비공개로 유지하세요. 브라우저나 모바일 앱에서 이벤트를 기록할 때는 Ingest only 키를 사용할 수 있습니다. 이 키로는 데이터를 조회하거나 관리할 수 없습니다. 하지만 키를 복사해 원치 않는 이벤트를 보낼 수는 있으므로 사용 상황을 확인하고 악용되면 폐기하세요. 권한과 키 교체 방법은 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": "telemetry_quickstart",
    "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("telemetry_quickstart", {
  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에 기간을 저장하십시오.

성공의 의미

익명 쿼리는 첫 이벤트 이후 24시간 동안 사용할 수 있습니다. 7일 이내에 계정을 만들면 이벤트와 같은 키를 유지할 수 있습니다. 가입 시 같은 브라우저의 체험을 감지합니다. 다른 브라우저에서는 **익명 API 키가 있나요?**를 선택하고 키를 붙여 넣은 뒤 내 데이터 찾기를 누르고 가입하세요. 기존 사용자는 내 데이터 유지에서 키를 복구한 뒤 로그인할 수 있습니다. 이벤트가 없는 체험은 생성 후 7일이 지나면 만료됩니다.

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

이 예시는 가상 데이터로 API 전송 경로만 확인합니다. 앱 연동을 완료하려면 실제 작업이 끝나는 지점에서 이벤트를 기록하고, 그 작업을 실행한 뒤 저장된 이벤트를 쿼리로 확인하세요. telemetry_quickstart 테이블의 행만으로는 설정이 완료되지 않습니다.

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

첫 번째 실제 이벤트를 연결하세요

설정 프롬프트를 코딩 에이전트에 붙여넣고 실제 애플리케이션 흐름을 실행한 다음 이벤트를 확인하고 첫 번째 쿼리를 작성합니다. 샘플 데이터는 선택 사항으로 남아 있습니다.

신용 카드가 필요하지 않습니다. 명확하게 표시된 샘플 이벤트와 실행 준비가 완료된 쿼리가 자동으로 생성되므로 워크플로를 평가하는 데 프로덕션 데이터가 필요하지 않습니다.

코딩 에이전트와 함께 이 문서를 사용하세요.