JavaScript 및 TypeScript SDK

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

아래 예제는 서버에서 패키지를 초기화합니다. 익명 체험 키, read 키, read-and-write 키를 브라우저 번들에 넣지 마세요. 이벤트만 보내는 클라이언트에는 Ingest only 키를 사용할 수 있습니다. 공개 빌드에 넣기 전에 권한을 확인하세요. 결과는 대시보드에서 확인하거나 신뢰할 수 있는 서버에서 별도의 읽기 키로 확인하세요. API 키와 인증을 참고하세요.

아래 전송 예제는 가상의 값으로 SDK의 데이터 전송을 확인합니다. telemetry_quickstart 테이블을 사용하세요. 이 예제만으로 애플리케이션 계측이 완료되었다고 볼 수는 없습니다. 실제 사용에서는 선택한 애플리케이션 작업이 완료될 때 관측한 값을 기록하고 해당 워크플로의 테이블을 사용하세요.

설치 및 초기화

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("telemetry_quickstart", {
    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("telemetry_quickstart", [
  {
    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 telemetry_quickstart
  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
FROM telemetry_quickstart
ORDER BY timestamp_utc DESC
LIMIT 20;

테이블 이름, 필드 유형, Null 동작, UTC 타임스탬프 및 민감한 필드가 없는지 확인하세요. 그런 다음 대시보드나 알림을 만들기 전에 재시도, 시간 초과 및 종료 분기를 테스트하세요.

문제 해결

API key is not initialized: 첫 번째 SDK 메서드 전에 telemetry.init를 호출합니다.
401: 누락되었거나 유효하지 않거나 취소된 키를 교체합니다.
403: 필요한 범위의 키를 사용합니다.
400: 테이블 이름, JSON 모양 및 필드 유형 호환성을 검사합니다. 변경하지 않고 다시 시도하지 마세요.
429 또는 5xx: 이벤트가 두 번 이상 안전하게 전달될 수 있는 경우 제한된 재시도 정책을 사용합니다.
전달 전 프로세스 종료: 즉각적인 호출을 추적하고 기다리거나 종료 전에 필요한 이벤트를 지속합니다. SDK 플러시 대기열이 없습니다.

로그 API, 비율 제한 및 API 오류 및 Node.js 및 Express 통합을 계속 진행하세요.

Next.js App Router 레시피

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