Ingest 엔드포인트

ingest 서비스는 OpenTelemetry 데이터를 받아 NATS JetStream에 발행합니다.

세 OTLP 엔드포인트(endpoint) 모두 JSON만 수락합니다(OTLP/HTTP proto3 JSON 매핑). Protobuf는 아직 지원되지 않으며, Content-Type: application/x-protobuf 요청(request)은 415 Unsupported Media Type을 반환합니다. gzip으로 압축된 본문(Content-Encoding: gzip)은 투명하게 해제됩니다.

POST /v1/logs

OTLP 로그 레코드를 수집합니다.

POST /v1/logs
Authorization: Bearer gck_your_key
Content-Type: application/json

OTLP LogsData를 JSON으로 받습니다.

응답: 성공 시 200 OK.

POST /v1/metrics

OTLP 메트릭 데이터 포인트를 수집합니다.

POST /v1/metrics
Authorization: Bearer gck_your_key
Content-Type: application/json

OTLP MetricsData를 JSON으로 받으며, Gauge, Sum, Histogram, Summary 메트릭을 포함합니다.

응답: 성공 시 200 OK.

source_event_id는 각 메트릭 데이터 포인트를 식별합니다. R1과 R2에서 표준 파생값은 스키마를 포함하는 메트릭 부모 표현과 개별 데이터 포인트를 함께 해싱합니다. 메트릭 부모 표현에는 메트릭 데이터 컨테이너가 포함되지만 형제 데이터 포인트는 제외됩니다. Sum 메트릭에서 Metric.sum은 스칼라 값이 아닌 객체 컨테이너입니다. 반면 Histogram 및 Summary 데이터 포인트의 sum은 숫자입니다.

POST /v1/traces

OTLP 트레이스 스팬을 수집합니다.

POST /v1/traces
Authorization: Bearer gck_your_key
Content-Type: application/json

OTLP TracesData를 JSON으로 받습니다.

응답: 성공 시 200 OK.

GET /health

헬스 체크 엔드포인트. 일반 텍스트 본문을 반환합니다.

GET /health

응답:

• NATS가 연결되었을 때 본문 ok와 함께 200 OK.
• NATS가 다운되었을 때 본문 nats unhealthy와 함께 503 Service Unavailable.

/health 엔드포인트는 Retry-After를 보내지 않습니다. 해당 헤더는 NATS 발행 파이프라인이 백프레셔를 받을 때 OTLP 엔드포인트에서만 추가됩니다(Retry-After: 5).

참고 사항

• OTLP 엔드포인트는 JSON만 수락하며, 다른 콘텐츠 타입은 415를 반환합니다.
• 과도한 페이로드는 413 Payload Too Large를 반환합니다.
• NATS 백프레셔 상황에서 OTLP 엔드포인트는 Retry-After: 5와 함께 503을 반환합니다.
• ingest 서비스는 무상태(stateless)입니다 — NATS에 발행하고 즉시 반환합니다.
• 데이터 흐름: Ingest → NATS JetStream → worker의 아카이브 및 적재 lane.

프롬프트 캡처 경로

플러그인은 다음 인증(authentication)된 경로를 사용합니다:

• POST /v1/prompts — 프롬프트 턴을 캡처합니다.
• POST /v1/prompts/response — 프롬프트에 대한 응답(response)을 캡처합니다.
• GET /v1/plugin/config — 플러그인의 런타임 구성을 확인합니다.
• POST /v1/setup-complete — 플러그인이 /prism:setup 종료를 알립니다.

응답 캡처 와이어 계약

최신 응답 캡처는 prompt_id 또는 client_event_id로 프롬프트를 선택하고 response_operation_id를 포함합니다. 의미적으로 같은 응답을 재시도하면 멱등적으로 처리됩니다. prompt_id와 client_event_id가 모두 제공되면 prompt_id가 우선합니다.

의미적 응답 콘텐츠는 response_text와 이미 함께 저장된 안정적인 응답 필드인 elapsed_ms, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, model, cost_usd로 구성됩니다. cost_catalog_revision과 cost_kind는 의미적 응답 콘텐츠가 아닌 추가적인 카탈로그 출처 정보입니다. 이후의 동일한 재시도는 누락된 카탈로그 출처 정보를 채울 수 있습니다. 이미 저장된 출처 정보와 다른 값이 재시도에 포함되면 최초 값을 유지하고 재시도는 멱등적인 no-op으로 처리합니다. response_content_hash는 선택 사항입니다. 제공되는 경우, response_text와 다음 일곱 개의 관리되는 응답 필드인 elapsed_ms, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, model, cost_usd에 대해 서버가 정준 방식으로 계산한 SHA-256과 같아야 합니다.

POST /v1/prompts/response의 응답은 다음과 같습니다:

• 성공적인 캡처 또는 멱등적 no-op에는 204 No Content.
• 요청 검증에 실패하면 400 Bad Request, 여기에는 제공된 response_content_hash가 서버가 정준 방식으로 계산한 SHA-256과 일치하지 않는 경우가 포함됩니다.
• 선택한 프롬프트가 없으면 404 Not Found.
• 응답 작업 또는 의미적 콘텐츠가 충돌하면 409 Conflict.
• 요청이 raw ingress 프레임 한도(현재 4MiB)를 초과하면 413 Payload Too Large. 이 상태는 전송된 요청 자체에 대해 영구적입니다. 같은 본문을 재시도해도 성공하지 않으며, 응답에는 Retry-After가 포함되지 않습니다.
• 하위 전송 계층이 일시적으로 포화 상태이면 Retry-After: 5와 함께 503 Service Unavailable. 413과 달리 이 상태는 재시도 가능합니다.

POST /v1/prompts도 동일한 이유로 같은 413/503 응답 쌍을 반환합니다.

tool_session_id를 사용하는 세션 전용 응답 선택은 레거시 호환성 전용입니다. 플러그인 버전이 0.5.1보다 낮고 2026-08-16T00:00:00Z 이전인 경우에만 허용됩니다.

엔진 프록시 엔드포인트

내부 엔진에 접근할 수 없는 호출자를 위해 일부 엔진 엔드포인트가 ingest를 통해 프록시(proxy)됩니다:

경로	메서드	대상
/v1/telemetry/logs	GET	API — Telemetry 엔드포인트 참조
/v1/insights/report	GET	API — Insights 엔드포인트 참조
/v1/insights/report/generate	POST	API — Insights 엔드포인트 참조
/v1/insights/report/quick	POST	API — 동기식, LLM 미사용 리포트 (Insights)
/v1/score_v3/realtime/sub-sessions	GET	API — Prompt Score v3.0 참조
/v1/score_v3/today-summary	GET	API — 오늘의 v3 집계 요약
/v1/model-catalog	GET	API — 컴파일된 모델 카탈로그 스냅샷 (Prompt Score v3.0)
/v1/intelligence/prism	GET	스텁 — 인증되지만 항상 { "scores": [], "total": 0 }을 반환. v2.14 이전의 prism.prism_scores 파이프라인은 제거되었으며, 현재 스코어링은 Prompt Score v3.0 아래에 있습니다.

프록시 경로도 다른 ingest 엔드포인트와 동일한 인증이 필요합니다.