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

Claude Code, Codex, Cursor 또는 다른 코딩 에이전트에 대한 집중 프롬프트 팩을 연 다음 여기에서 다루는 워크플로에 맞게 조정하세요.

이 페이지에서

설치 및 초기화
하나의 구조화된 이벤트 보내기
일괄 보내기
입력된 쿼리 실행
전달 동작 및 재시도
통합 확인
문제 해결

JavaScript 및 TypeScript SDK

서버 측 JavaScript 또는 TypeScript에서 telemetry-sh 패키지를 사용합니다. 현재 클라이언트는 ESM 및 CommonJS 빌드를 통해 즉각적인 log 및 query 호출을 노출합니다. 백그라운드 이벤트 큐를 유지하지 않거나 플러시 메소드를 노출하지 않습니다.

브라우저 코드에서 패키지를 초기화하지 마십시오. Telemetry API 키는 팀에 대한 액세스 권한을 부여하며 클라이언트 번들로 제공되어서는 안 됩니다.

설치 및 초기화

npm install telemetry-sh

ES 모듈:

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

커먼JS:

const telemetry = require("telemetry-sh");

telemetry.init(process.env.TELEMETRY_API_KEY);

서버 또는 작업자 시작 중에 init를 한 번 호출합니다. 수집 전용 코드에는 쓰기 범위 키를 사용하고 보고 또는 쿼리 전용 자동화에는 읽기 범위 키를 사용하세요.

하나의 구조화된 이벤트 보내기

애플리케이션이 전달 성공 또는 실패를 관찰해야 할 때 반환된 Promise를 기다립니다.

const eventId = crypto.randomUUID();

try {
  await telemetry.log("api_request_completed", {
    event_id: eventId,
    route_template: "/api/projects/:id",
    method: "POST",
    status_code: 201,
    status: "success",
    latency_ms: 184,
    environment: process.env.APP_ENV,
    release: process.env.APP_RELEASE,
  });
} catch (error) {
  console.error("Telemetry delivery failed", {
    event_id: eventId,
    error_type: "telemetry_delivery_failed",
  });
}

원시 URL, 요청 본문, 쿠키, 인증 헤더, 비밀, 프롬프트 및 개인 고객 콘텐츠를 페이로드에서 제외하세요. 안정적인 경로 템플릿, 내부 식별자 및 제어된 오류 범주를 사용합니다.

일괄 보내기

log는 호환 가능한 객체의 배열을 허용합니다. 일괄 처리는 요청 오버헤드를 줄이지만 하나의 실패한 요청으로 인해 영향을 받는 이벤트 수를 늘립니다.

await telemetry.log("job_completed", [
  {
    event_id: "evt_job_101",
    job_name: "invoice_sync",
    status: "success",
    duration_ms: 912,
  },
  {
    event_id: "evt_job_102",
    job_name: "invoice_sync",
    status: "failed",
    duration_ms: 2401,
    error_type: "provider_timeout",
  },
]);

JavaScript 클라이언트는 제공된 배열을 즉시 보냅니다. 통화를 내부 배치로 수집하지 않습니다. 애플리케이션이 자체 버퍼를 도입하는 경우 일괄 처리 및 역압에 설명된 대로 크기, 수명, 재시도 예산 및 종료 동작을 제한합니다.

입력된 쿼리 실행

type ReliabilityRow = {
  requests: number;
  route_template: string;
};

const result = await telemetry.query<ReliabilityRow>(`
  SELECT
    route_template,
    COUNT(*) AS requests
  FROM api_request_completed
  WHERE timestamp_utc >= now() - INTERVAL '24 hours'
  GROUP BY route_template
  ORDER BY requests DESC
`);

for (const row of result.data) {
  console.log(row.route_template, row.requests);
}

일반 유형은 TypeScript에 대한 결과 행을 설명합니다. 런타임 시 SQL 결과의 유효성을 검사하지 않습니다. 자동화에서 쿼리를 사용하기 전에 빈 결과와 예기치 않은 null을 확인하세요.

SDK의 query 메서드는 대화형 쿼리 끝점을 호출합니다. SDK 옵션이 비동기 작업을 생성하고 폴링한다고 가정하는 대신 비동기 JSON 또는 Parquet 내보내기에 대해 문서화된 HTTP 흐름을 사용합니다.

전달 동작 및 재시도

현재 패키지는 각 log 또는 query 호출에 대해 하나의 fetch 요청을 수행합니다. SDK 시간 초과, 자동 재시도, 영구 대기열 또는 플러시 수명 주기를 추가하지 않습니다.

수집을 다시 시도하는 경우:

일시적 전송 오류인 429, 502, 503 및 504만 재시도합니다.
논리적 이벤트의 event_id를 재사용합니다.
지터를 사용하여 지수 백오프를 적용합니다.
최대 시도 횟수 및 경과 시간입니다.
원격 분석이 워크플로 내구성 계약의 명시적으로 일부가 아닌 이상 완료된 고객 작업을 실패로 전환하지 마세요.

삭제할 수 없는 청구 또는 승인된 감사 이벤트에 대해 애플리케이션 소유의 내구성 있는 발신함을 사용하십시오. 이벤트 전달 및 멱등성을 참조하세요.

통합 확인

합성 성공 및 실패 이벤트를 보낸 후 다음을 실행합니다.

SELECT
  timestamp_utc,
  event_id,
  route_template,
  status,
  latency_ms,
  error_type
FROM api_request_completed
ORDER BY timestamp_utc DESC
LIMIT 20;