빠른 시작

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

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, Go, Rust를 사용할 수도 있습니다. Ruby, PHP 또는 cURL.

npm install telemetry-sh

일부 데이터 기록

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

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

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

UI를 통해 데이터 탐색

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

const result = await telemetry.query("SELECT city, price FROM uber_rides LIMIT 10");
console.log(result);

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

탐색 보기

탐색 탭에서 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
    }
  }
}

이를 agent_demo_events와 같은 테이블에 기록하고 Explore에서 해당 테이블을 사용할 수 있습니다.

/team/{team}/table/agent_demo_events?tab=explore&graphType=samples&f=event:=:tool_call&f=data.toolName:=:smart_avantis_buy

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}로 리디렉션됩니다.

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

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

대화형 인라인 예

/team/{team}/table/{table}?tab=explore&graphType=line&agg=p95&metric=latency_ms&time=7d

코드베이스와 통합

API 쿼리를 통해 SQL로 데이터를 쿼리하여 Telemetry를 제품 또는 내부 대시보드에 통합할 수 있습니다.

const results =
  await telemetry.query(`
    SELECT
      city,
      AVG(price)
    FROM
      uber_rides
    GROUP BY
      city
  `);

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

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