Docs

Observability (OTel)

Send Schift retrieval traces to LangSmith, Datadog, Sentry, Helicone, Honeycomb, or any OTLP-compatible backend.

Schift API and worker emit OpenTelemetry spans for every retrieval call (embedding, vector search, BM25, rerank, LLM dispatch). Any OTLP-compatible backend can ingest them by setting three environment variables.

Quick start

bashexport OTEL_EXPORTER_OTLP_ENDPOINT="<vendor endpoint>"
export OTEL_EXPORTER_OTLP_HEADERS="<vendor auth header>"
# Optional — auto-detected to http/protobuf for HTTPS endpoints
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

Vendor endpoints

Vendor	Endpoint	Auth header
LangSmith	`https://api.smith.langchain.com/otel`	`x-api-key=<langsmith-key>`
Datadog (agent)	`http://datadog-agent:4318`	(none — IAM/network)
Datadog (direct)	`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`	(none)

Custom span attributes

Every Schift retrieval span carries:

Attribute	Type	Example
`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>`

Sampling

High-volume deployments should sample to control cost:

bashexport OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1   # 10% sampling

Detailed guides

See /docs/observability/langsmith and /docs/observability/vendors for vendor-specific walkthroughs including sampling strategies and trace correlation.