콘텐츠로 건너뛰기
Telemetry
문서 찾아보기

시작하기업데이트된 2026년 10월 2일5 최소 읽기

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

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

이 페이지에서
  1. API 키 받기
  2. Telemetry 설치
  3. 일부 데이터 기록
  4. UI를 통해 데이터 탐색
  5. 탐색 보기
  6. 대시보드
  7. 알림 만들기
  8. 대화형 인라인 예
  9. 코드베이스와 통합

빠른 시작

JSON 이벤트를 Telemetry로 보내고 SQL로 조회하세요. 이 빠른 시작에서는 이벤트 하나를 보내고, Telemetry가 만든 테이블을 확인한 뒤 쿼리를 실행합니다.

아래 예시는 예약된 telemetry_quickstart 테이블에 가상 데이터를 보냅니다. 전송과 쿼리 경로를 확인하기 위한 예시입니다. 앱 연동을 완료하려면 실제 작업을 실행하고 그 작업에서 기록한 이벤트를 쿼리하세요.

Telemetry가 내부적으로 어떻게 작동하는지 자세히 알아보려면 Telemetry 아키텍처 문서에서 자세한 개요를 확인하세요. API 호출을 계측하여 OpenAI 비용을 추적하는 등 보다 심층적인 사용 사례에 대해서는 OpenAI 비용 추적 가이드를 참조하세요.

더 짧은 작업별 경로를 선호하시나요? 팔로우:

  1. 첫 번째 구조화된 이벤트 보내기
  2. 이벤트 수집 및 스키마 확인
  3. 첫 번째 Telemetry SQL 쿼리 작성
  4. 첫 번째 대시보드 및 알림 만들기
  5. 프로덕션 계측 체크리스트

API 키 받기

홈페이지의 설정 프롬프트에서 anon_… 키를 받으세요. 계정 없이 이벤트를 보내고 쿼리할 수 있습니다. 계정이 있다면 팀 설정 → API 키의 read-and-write 키를 사용하세요.

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

Telemetry 설치

이 튜토리얼에서는 JavaScript를 사용합니다. Python SDK, Go SDK, Rust SDK, Ruby SDK, PHP SDK 또는 cURL을 사용할 수도 있습니다.

npm install telemetry-sh

일부 데이터 기록

Telemetry는 데이터가 기록될 때 자동으로 테이블을 생성합니다. 다음 예에서는 합성 탑승 데이터를 telemetry_quickstart라는 테이블에 기록합니다. Telemetry는 city 및 price를 사용하여 테이블과 해당 스키마를 생성합니다. 모든 행에는 timestamp_utc도 수신됩니다.

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

await telemetry.log("telemetry_quickstart", {
  city: "paris",
  price: 42
});

UI를 통해 데이터 탐색

먼저 가입하지 않고 이벤트를 쿼리해 확인하세요.

const result = await telemetry.query("SELECT city, price FROM telemetry_quickstart WHERE city IS NOT NULL LIMIT 10");
console.log(result);

차트, 대시보드, 알림을 사용하려면 계정을 만들고 데이터를 유지하세요. 기존 키는 계속 작동하며 가입 후 이벤트가 있는 워크스페이스가 열립니다. 계정이 있다면 체험을 연결하세요.

테이블, 쿼리, 차트에서 대시보드와 알림으로 이어지는 설명용 다이어그램

Telemetry 앱을 사용하여 수집된 이벤트에서 쿼리, 차트, 대시보드 및 알림로 이동하세요.

이 결과 저장은 안내에 표시된 대시보드에 쿼리 결과를 저장합니다. 다른 결과 작업은 아래의 대시보드 및 알림 단계를 참고하세요.

탐색 보기

탐색 탭에서 SQL을 작성하지 않고 이벤트를 필터링하고 차트나 표를 만드세요.

탐색은 한 번에 하나의 테이블을 다룹니다. 여는 방법은 다음과 같습니다.

  1. Go를 팀에 보내주세요.
  2. 테이블을 엽니다.
  3. 테이블을 선택하세요.
  4. 해당 테이블 페이지에서 탐색 탭을 엽니다.

경로 모양:

/team/{team}/table/{table}?tab=explore
  1. 그래프 유형(Samples, Table, Line, Bar 또는 Stacked Area)을 선택합니다.
  2. 시간 범위를 설정하고 하나 이상의 필터를 추가합니다.
  3. 포함할 열을 선택합니다(data.toolName와 같은 중첩 필드 포함).
  4. 실행을 클릭하여 실행하고 결과를 렌더링합니다.

팁: 컨트롤은 초안 상태입니다. 실행을 클릭하는 경우에만 결과가 업데이트됩니다.

가상의 예시 데이터 세트(가상)

아래 탐색 예시에서는 다음과 같은 구조로 합성 테스트 이벤트(실제 사용자 데이터 없음)를 기록했다고 가정합니다.

{
  "timestamp_utc": "2026-02-27T12:00:00.000Z",
  "event": "tool_call",
  "status": "success",
  "data": {
    "toolName": "smart_avantis_buy",
    "args": {
      "symbol": "BTC-USD",
      "amountUsd": 2500
    }
  }
}

위 예시는 저장된 행을 보여 줍니다. telemetry_quickstart에 이벤트를 보낼 때는 timestamp_utc를 생략하세요. Telemetry는 timestamp에서 이 열을 생성하며, 생략하면 현재 UTC 시간을 사용합니다. 위 날짜는 설명용입니다. 과거 이벤트를 보내려면 timestamp를 설정하고 Explore에서 해당 시간을 포함하는 범위를 선택하세요. Log API 정규화 규칙을 참고하세요.

예 1: 도구 호출 필터링 및 원시 행 검사

위의 가상 스키마를 사용하여 Explore에서 다음을 시도해 보세요.

  1. 그래프 유형을 다음으로 설정 Samples.
  2. 필터 추가: event = tool_call.
  3. 필터 추가: data.toolName = smart_avantis_buy.
  4. 클릭 실행.

URL 템플릿(자리 표시자 교체):

/team/{team}/table/telemetry_quickstart?tab=explore&graphType=samples&f=event:=:tool_call&f=data.toolName:=:smart_avantis_buy
예 2: 차트 보기와 테이블 보기 비교

동일한 필터를 사용한 다음:

  1. 선택 Line 그리고 클릭 실행.
  2. 다음으로 전환 Table 그리고 클릭 실행 다시.

이를 통해 추세와 정확한 값을 모두 빠르게 확인할 수 있습니다.

예 3: 모든 열 모드의 중첩 열

당신이 유지할 때 All columns 탐색에서 선택하면 생성된 SQL는 중첩된 필드가 포함되도록 명시적으로 열을 열거합니다.

생성된 SQL 모양의 예:

SELECT "timestamp_utc", "event", "data.toolName", "data.args.symbol"
FROM "your_table"
WHERE timestamp_utc >= now() - INTERVAL '7 days'
ORDER BY timestamp_utc DESC
LIMIT 200

대시보드

대시보드를 사용하면 탐색 차트/테이블과 쿼리 결과를 하나의 공유 보기에 고정할 수 있습니다.

대시보드를 만들고 사용하려면 다음을 수행합니다.

  1. 탐색에서 테이블을 열거나 저장된 쿼리 결과를 엽니다.
  2. 대시보드 이름이 표시된 저장 버튼 또는 이 결과 저장으로 바로 저장합니다.
  3. 대시보드가 없으면 스타터 대시보드 생성 및 저장을 사용합니다.
  4. 대시보드가 여러 개이면 대시보드 선택에서 대상과 위젯 제목을 지정합니다.

대시보드 경로 모양:

/team/{team}/dashboard/{dashboardSlug}

대시보드를 사용하여 팀의 주요 신호(지연 시간, 오류율, 비용 및 전환 지표)를 한 곳에 보관하세요.

알림 만들기

차트 또는 쿼리 결과가 있으면 Telemetry UI에서 이를 알림로 전환할 수 있습니다.

  1. 탐색에서 테이블을 열거나 결과/차트 보기에서 쿼리를 실행하세요.
  2. 결과 모니터링을 클릭합니다.
  3. 조건(집계, 마지막 N 포인트, 비교 및 임계값)을 구성합니다.
  4. 확인 간격과 한 명 이상의 이메일 수신자를 설정합니다.
  5. 저장하려면 알림 생성을 클릭하세요. 상태 및 기록을 모니터링하기 위해 /team/{team}/alert/{alertSlug}로 리디렉션됩니다.

팁: 버킷화된 시계열에 대해 마지막 데이터 포인트 무시를 활성화된 상태로 두세요. 최신 버킷은 종종 불완전하기 때문입니다.

전체 연습을 보려면 알림 가이드를 참조하세요.

대화형 인라인 예

예시 1: 지연 시간 스파이크 감지기(p95)

다음이 포함된 테이블의 Explore에서 이것을 시도해 보세요. latency_ms:

  1. 그래프 유형을 다음으로 설정 Line.
  2. 집계를 다음으로 설정 p95 미터법으로 latency_ms.
  3. 클릭 실행을 클릭한 다음 결과 모니터링.
  4. 조건: p95 of last 5 data points is Greater than 850.
  5. 간격: Every minute을 클릭한 다음 수신자 이메일을 추가하세요.

URL 템플릿(자리 표시자 교체):

/team/{team}/table/{table}?tab=explore&graphType=line&agg=p95&metric=latency_ms&time=7d
예 2: 오류 버스트 감지기(개수)

숫자형 status_code 필드가 있는 HTTP 요청 이벤트 테이블에서 서버 오류(HTTP 5xx)를 집계합니다. 앞의 도구 호출 예제에서 status는 문자열이므로 이 필터에 사용할 수 없습니다.

  1. 탐색에서 status_code >= 500 및 status_code < 600 조건을 모두 만족하는 행을 필터링합니다.
  2. 집계와 함께 꺾은선형 차트 사용 count.
  3. 클릭 결과 모니터링.
  4. 조건: Average of last 3 data points is Greater than 20.

이는 단일 불량 버킷의 노이즈를 피하면서 짧은 오류 버스트를 포착합니다.

예 3: 조용한 트래픽 감지기(임계값 아래로 떨어짐)

크론 작업, 대기열 또는 수집 파이프라인에 이를 사용합니다.

  1. 시간 경과에 따른 쿼리 또는 차트 이벤트 볼륨입니다.
  2. 비교를 통해 알림 만들기 Less than.
  3. 조건: Sum of last 10 data points is Less than 50.

이것이 트리거되면 일반적으로 고객이 알기 전에 데이터 흐름이 중단되었음을 의미합니다.

코드베이스와 통합

쿼리 API를 사용하면 코드에서 이 가상의 탑승 이벤트를 읽을 수 있습니다. 제품이나 내부 대시보드에서는 이 예시 테이블 대신 실제로 실행한 작업에서 기록한 이벤트 테이블을 사용하세요.

const results =
  await telemetry.query(`
    SELECT
      city,
      AVG(price)
    FROM
      telemetry_quickstart
    WHERE city IS NOT NULL
    GROUP BY
      city
  `);

API 오류, 대기 시간 백분위수, 작업 재시도, LLM 비용, 변환, 보존 또는 누락된 하트비트를 분석할 준비가 되면 SQL 레시피 라이브러리를 찾아보세요.

해당 레시피의 아키텍처 및 분석 모델을 보려면 다음을 계속하세요. 옵저버빌리티 및 이벤트 분석을 위한 SQL. 수집부터 SQL 결과까지 하나의 완전한 합성 워크플로를 실행하려면 다음을 사용하세요. 엔드 투 엔드 SaaS 가시성 데모.

관련 기능

안정적인 이벤트 이름, 타입이 지정된 필드, 개인 정보 보호 검토 컨텍스트를 캡처합니다.

페이지 작성자 및 참고 자료

이 설명은 Telemetry 편집팀의 소유입니다. 제품 팀은 동작, 예시, 경계를 검토합니다.

문서 검토 방법