Telemetry 엔드포인트

Prism API는 worker가 적재한 조직 데이터에서 텔레메트리 쿼리를 처리합니다.

GET /v1/telemetry/context

단일 Claude Code 세션의 최신 컨텍스트 스냅샷 — 최근 24시간 내의 가장 새로운 API 요청 텔레메트리에서 제공되며, 재개 시 작업 컨텍스트를 복원하기 위해 플러그인이 사용합니다. 인증된 개발자 범위로 제한됩니다(위임된 사용자가 없는 서비스 주체는 거부됩니다).

GET /v1/telemetry/context?session_id=abc123
Authorization: Bearer gck_your_key

파라미터	타입	필수	설명
session_id	string	예	최신 컨텍스트를 가져올 세션

빈 session_id는 400 Bad Request를 반환합니다. 최근 텔레메트리가 없으면 엔드포인트는 오류 대신 잘 구성된 “unavailable” 컨텍스트 응답을 반환합니다.

GET /v1/telemetry/logs

로그 레코드 쿼리.

GET /v1/telemetry/logs?from=2024-01-01T00:00:00Z&to=2024-01-07T00:00:00Z&limit=100
Authorization: Bearer gck_your_key

파라미터	타입	기본값	설명
from	ISO8601	24시간 전	시작 시간
to	ISO8601	현재	종료 시간
session_id	string	—	단일 세션으로 필터
developer_id	string	—	단일 개발자로 필터
limit	integer	100	최대 레코드 (최대 1000)
offset	integer	0	페이지네이션 오프셋

GET /v1/telemetry/metrics

메트릭 데이터 포인트 쿼리. /logs와 동일한 파라미터.

GET /v1/telemetry/traces

트레이스 스팬 쿼리. /logs와 동일한 파라미터.

GET /v1/telemetry/stats

시간·세션·개발자 기준 집계 통계.

GET /v1/telemetry/stats?from=2024-01-01T00:00:00Z&to=2024-01-07T00:00:00Z&group_by=day&signal=logs
Authorization: Bearer gck_your_key

파라미터	타입	기본값	설명
from	ISO8601	7일 전	시작 시간
to	ISO8601	현재	종료 시간
group_by	enum	hour	hour, day, session_id, developer_id 중 하나. 잘못된 값은 400 반환.
signal	enum	logs	logs, metrics, traces 중 하나.

POST /v1/telemetry/per-turn

특정 프롬프트/세션 집합에 대한 턴별 텔레메트리 쿼리 (긴 쿼리 문자열을 피하기 위해 바디 기반). 대시보드의 세션 탐색기가 턴 단위 상세를 채우는 데 사용합니다.

POST /v1/telemetry/per-turn
Authorization: Bearer gck_your_key
Content-Type: application/json

{
  "session_id": "…",
  "prompt_ids": ["…"]
}

GET /v1/telemetry/analytics

인메모리 캐싱이 포함된 분석 — 사용된 도구, 오류, 효율성 메트릭.

GET /v1/telemetry/analytics?from=2024-01-01T00:00:00Z&to=2024-01-07T00:00:00Z&tz_offset=-300
Authorization: Bearer gck_your_key

파라미터	타입	기본값	설명
from	ISO8601	7일 전	시작 시간
to	ISO8601	현재	종료 시간
tz_offset	integer	0	UTC 기준 동쪽으로의 분 단위 타임존 오프셋. 집계 전 이벤트 타임스탬프를 이동시켜 day/hour 집계가 로컬 시간을 반영합니다. 예: KST는 540, EST는 -300.

결과는 빠른 반복 쿼리를 위해 org_id:from:to 키별로 캐시됩니다.

POST /v1/telemetry/analytics/batch

여러 시간 범위의 분석을 한 요청으로 계산합니다 — 대시보드는 예컨대 “이번 주”와 “지난 주”를 순차 호출 대신 함께 가져오는 데 사용합니다. 각 범위는 호출자가 준 key를 담으며, 일치하는 결과에 그 값이 다시 실려 돌아옵니다.

POST /v1/telemetry/analytics/batch
Authorization: Bearer gck_your_key
Content-Type: application/json

{
  "ranges": [
    { "key": "this_week", "from": "2024-01-08T00:00:00Z", "to": "2024-01-15T00:00:00Z" },
    { "key": "last_week", "from": "2024-01-01T00:00:00Z", "to": "2024-01-08T00:00:00Z" }
  ],
  "tz_offset": -300
}

바디 필드	타입	기본값	설명
ranges	array	—	범위마다 { key, from, to } 객체 하나
tz_offset	integer	0	UTC 기준 동쪽으로의 분 단위 타임존 오프셋
timezone	string	—	선택적 IANA 타임존 이름
refresh	boolean	false	분석 캐시 우회

응답: { "results": [ { "key": "this_week", "analytics": { … } }, … ] } — 각 analytics 값은 GET /v1/telemetry/analytics와 동일한 형태입니다.

컴팩션 읽기 안전성

텔레메트리 컴팩션 코드는 기본적으로 비활성(off)이며 audit, write-retain, raw-delete 모드도 정의합니다. 이 API 참조는 롤아웃, 구성 또는 활성화를 지시하거나 암시하지 않습니다.

손상되었거나 읽을 수 없는 컴팩션 authority 또는 manifest, 또는 사용할 수 없는 authority output은 불완전하거나 사용할 수 없는 데이터입니다. 이는 빈 Complete 결과로 표현되지 않습니다.

참고 사항

• 기간과 필터를 가능한 한 좁히세요 — 스캔량이 줄어 응답이 빨라집니다.
• 데이터는 year/month/day/hour로 파티션됩니다 (Hive 파티셔닝) — 좁은 시간 범위가 더 빠릅니다.
• 결과는 인증된 조직으로 범위가 제한됩니다.