문서

관측성 (OTel)

Schift 검색 trace를 LangSmith, Datadog, Sentry, Helicone, Honeycomb 등 OTLP 호환 백엔드로 전송.

Schift API와 worker는 모든 retrieval 호출(임베딩, 벡터 검색, BM25, rerank, LLM dispatch)에 대해 OpenTelemetry span을 emit합니다. OTLP 호환 백엔드라면 환경 변수 3개만 세팅하면 ingest 가능합니다.

빠른 시작

bashexport OTEL_EXPORTER_OTLP_ENDPOINT="<vendor endpoint>"
export OTEL_EXPORTER_OTLP_HEADERS="<vendor auth header>"
# 선택 — HTTPS endpoint는 http/protobuf로 자동 감지
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

벤더 endpoint

벤더	Endpoint	Auth header
LangSmith	`https://api.smith.langchain.com/otel`	`x-api-key=<langsmith-key>`
Datadog (agent)	`http://datadog-agent:4318`	(없음 — IAM/네트워크)
Datadog (직접)	`https://trace.agent.datadoghq.com`	`dd-api-key=<key>`
Sentry	`https://o<org>.ingest.sentry.io/api/<project>/otlp/v1/traces`	`x-sentry-auth=sentry_key=<public-key>`
Helicone	`https://api.helicone.ai/otel/v1/traces`	`authorization=Bearer <key>`
Honeycomb	`https://api.honeycomb.io`	`x-honeycomb-team=<key>,x-honeycomb-dataset=schift`
Tempo / Jaeger	`http://collector:4318`	(없음)

커스텀 span 속성

모든 Schift retrieval span은 다음 속성을 포함합니다:

속성	타입	예시
`schift.bucket.id`	string	`bkt_abc123`
`schift.search.top_k`	int	`10`
`schift.search.mode`	string	`vector` / `hybrid`
`schift.search.method`	string	`engine_hybrid` / `hyde` / `fallback`
`schift.search.rerank`	bool	`true`
`schift.search.results.count`	int	`8`
`schift.search.scores.top`	float	`0.91`
`schift.search.scores.avg`	float	`0.74`
`schift.filter.keys`	string[]	`["tag","source_url"]`
`schift.filter.ops`	string[]	`["eq","like"]`
`schift.timing.total_ms`	int	`186`
`schift.search_id`	string	`search_<hex>`

샘플링

대용량 트래픽은 비용 제어를 위해 샘플링하세요:

bashexport OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1   # 10% 샘플링