빠른 시작
JSON 이벤트를 Telemetry로 보내고 SQL로 조회하세요. 이 빠른 시작에서는 이벤트 하나를 보내고, Telemetry가 만든 테이블을 확인한 뒤 쿼리를 실행합니다.
아래 예시는 예약된 telemetry_quickstart 테이블에 가상 데이터를 보냅니다. 전송과 쿼리 경로를 확인하기 위한 예시입니다. 앱 연동을 완료하려면 실제 작업을 실행하고 그 작업에서 기록한 이벤트를 쿼리하세요.
Telemetry가 내부적으로 어떻게 작동하는지 자세히 알아보려면 Telemetry 아키텍처 문서에서 자세한 개요를 확인하세요. API 호출을 계측하여 OpenAI 비용을 추적하는 등 보다 심층적인 사용 사례에 대해서는 OpenAI 비용 추적 가이드를 참조하세요.
더 짧은 작업별 경로를 선호하시나요? 팔로우:
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을 작성하지 않고 이벤트를 필터링하고 차트나 표를 만드세요.
탐색은 한 번에 하나의 테이블을 다룹니다. 여는 방법은 다음과 같습니다.
- Go를 팀에 보내주세요.
- 테이블을 엽니다.
- 테이블을 선택하세요.
- 해당 테이블 페이지에서 탐색 탭을 엽니다.
경로 모양:
/team/{team}/table/{table}?tab=explore
- 그래프 유형(
Samples,Table,Line,Bar또는Stacked Area)을 선택합니다. - 시간 범위를 설정하고 하나 이상의 필터를 추가합니다.
- 포함할 열을 선택합니다(
data.toolName와 같은 중첩 필드 포함). - 실행을 클릭하여 실행하고 결과를 렌더링합니다.
팁: 컨트롤은 초안 상태입니다. 실행을 클릭하는 경우에만 결과가 업데이트됩니다.
가상의 예시 데이터 세트(가상)
아래 탐색 예시에서는 다음과 같은 구조로 합성 테스트 이벤트(실제 사용자 데이터 없음)를 기록했다고 가정합니다.
{
"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에서 다음을 시도해 보세요.
- 그래프 유형을 다음으로 설정
Samples. - 필터 추가:
event = tool_call. - 필터 추가:
data.toolName = smart_avantis_buy. - 클릭 실행.
URL 템플릿(자리 표시자 교체):
/team/{team}/table/telemetry_quickstart?tab=explore&graphType=samples&f=event:=:tool_call&f=data.toolName:=:smart_avantis_buy
예 2: 차트 보기와 테이블 보기 비교
동일한 필터를 사용한 다음:
- 선택
Line그리고 클릭 실행. - 다음으로 전환
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
대시보드
대시보드를 사용하면 탐색 차트/테이블과 쿼리 결과를 하나의 공유 보기에 고정할 수 있습니다.
대시보드를 만들고 사용하려면 다음을 수행합니다.
- 탐색에서 테이블을 열거나 저장된 쿼리 결과를 엽니다.
- 대시보드 이름이 표시된 저장 버튼 또는 이 결과 저장으로 바로 저장합니다.
- 대시보드가 없으면 스타터 대시보드 생성 및 저장을 사용합니다.
- 대시보드가 여러 개이면 대시보드 선택에서 대상과 위젯 제목을 지정합니다.
대시보드 경로 모양:
/team/{team}/dashboard/{dashboardSlug}
대시보드를 사용하여 팀의 주요 신호(지연 시간, 오류율, 비용 및 전환 지표)를 한 곳에 보관하세요.
알림 만들기
차트 또는 쿼리 결과가 있으면 Telemetry UI에서 이를 알림로 전환할 수 있습니다.
- 탐색에서 테이블을 열거나 결과/차트 보기에서 쿼리를 실행하세요.
- 결과 모니터링을 클릭합니다.
- 조건(집계, 마지막 N 포인트, 비교 및 임계값)을 구성합니다.
- 확인 간격과 한 명 이상의 이메일 수신자를 설정합니다.
- 저장하려면 알림 생성을 클릭하세요. 상태 및 기록을 모니터링하기 위해
/team/{team}/alert/{alertSlug}로 리디렉션됩니다.
팁: 버킷화된 시계열에 대해 마지막 데이터 포인트 무시를 활성화된 상태로 두세요. 최신 버킷은 종종 불완전하기 때문입니다.
전체 연습을 보려면 알림 가이드를 참조하세요.
대화형 인라인 예
예시 1: 지연 시간 스파이크 감지기(p95)
다음이 포함된 테이블의 Explore에서 이것을 시도해 보세요. latency_ms:
- 그래프 유형을 다음으로 설정
Line. - 집계를 다음으로 설정
p95미터법으로latency_ms. - 클릭 실행을 클릭한 다음 결과 모니터링.
- 조건:
p95 of last 5 data points is Greater than 850. - 간격:
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는 문자열이므로 이 필터에 사용할 수 없습니다.
- 탐색에서
status_code >= 500및status_code < 600조건을 모두 만족하는 행을 필터링합니다. - 집계와 함께 꺾은선형 차트 사용
count. - 클릭 결과 모니터링.
- 조건:
Average of last 3 data points is Greater than 20.
이는 단일 불량 버킷의 노이즈를 피하면서 짧은 오류 버스트를 포착합니다.
예 3: 조용한 트래픽 감지기(임계값 아래로 떨어짐)
크론 작업, 대기열 또는 수집 파이프라인에 이를 사용합니다.
- 시간 경과에 따른 쿼리 또는 차트 이벤트 볼륨입니다.
- 비교를 통해 알림 만들기
Less than. - 조건:
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 가시성 데모.