OpenTelemetry

Schift는 검색(retrieval) 및 검색(search) 작업에 대해 OpenTelemetry 트레이스(trace)를 내보냅니다. 몇 가지 환경 변수(environment variables)만 설정하면 이 트레이스를 Datadog, Honeycomb, Grafana Tempo, Jaeger, LangSmith 등 OTLP 호환 백엔드(OTLP-compatible backend)로 라우팅할 수 있습니다. 텔레메트리(telemetry)가 설정되지 않으면 계측(instrumentation)은 no-op(무연산) 상태가 되어 오버헤드가 전혀 발생하지 않습니다.

내보내지는 것

Schift API는 OTEL_EXPORTER_OTLP_ENDPOINT가 설정된 경우 부팅 시 OTLP 트레이스 익스포터(trace exporter)를 초기화합니다. 현재 다음 트레이스(trace)가 내보내집니다:

• schift.bucket.search — 로컬 검색(retrieval) 파이프라인을 실행하는 모든 POST /v1/buckets/{bucket_id}/search 요청에 대해 생성되는 최상위 버킷(bucket) 검색 스팬(span)입니다.

각 schift.bucket.search 스팬(span)은 요청, 검색 전략, 결과 품질을 설명하는 속성(attribute)을 포함합니다.

텔레메트리 활성화

Schift API를 시작하기 전에 다음 환경 변수(environment variables)를 설정하세요:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.honeycomb.io"
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<your-api-key>"

서버를 재시작하면 스팬(span)이 배치로 모아져 비동기적으로 익스포트됩니다.

참고: OTEL_EXPORTER_OTLP_HEADERS는 인증 정보를 포함합니다. 체크인된 .env 파일이 아닌 비밀 관리자(secret manager) 또는 배포 플랫폼의 비밀 저장소에서 불러오세요.

설정 참조

변수	필수	기본값	설명
OTEL_EXPORTER_OTLP_ENDPOINT	Yes	—	OTLP 엔드포인트(endpoint) URL입니다.
OTEL_EXPORTER_OTLP_HEADERS	Usually	—	인증용 key=value 쌍을 쉼표로 구분한 헤더입니다.
OTEL_EXPORTER_OTLP_PROTOCOL	No	auto	grpc 또는 http/protobuf입니다.
OTEL_SERVICE_NAME	No	schift-api	모든 스팬(span)에 붙는 서비스 이름입니다.
OTEL_TRACES_SAMPLER	No	always_on	샘플러(sampler) 이름입니다. 예: parentbased_traceidratio.
OTEL_TRACES_SAMPLER_ARG	No	—	샘플러 인수입니다. 예: 10% 샘플링을 위한 0.1.

OTEL_EXPORTER_OTLP_ENDPOINT가 설정되지 않으면 init_telemetry()는 즉시 반환되며 익스포터(exporter), 트레이서 제공자(tracer provider), FastAPI 계측(instrumentation)이 설치되지 않습니다.

프로토콜 선택

Schift는 전송 프로토콜(transport protocol)을 자동 감지(auto-detect)하므로 HTTPS 엔드포인트(endpoint)에 추가 설정 없이 동작합니다:

• OTEL_EXPORTER_OTLP_PROTOCOL이 grpc 또는 http/protobuf로 설정된 경우 해당 값을 사용합니다.
• 그렇지 않고 HTTPS 엔드포인트인 경우 http/protobuf를 사용합니다.
• 그렇지 않고 일반 HTTP 또는 grpc:// 엔드포인트인 경우 grpc를 사용합니다.

대부분의 관리형 벤더(vendor)는 http/protobuf를 필요로 합니다. 자동 감지 결과가 수집기(collector)와 맞지 않을 때만 해당 변수를 명시적으로 설정하세요.

스팬 속성

schift.bucket.search 스팬(span)은 다음 속성(attribute)을 포함합니다:

속성	타입	설명
schift.bucket.id	string	요청 경로의 버킷(bucket) ID입니다.
schift.search.top_k	int	요청한 결과 개수입니다.
schift.search.mode	string	검색 모드입니다. 예: vector 또는 hybrid.
schift.search.rerank	bool	재정렬(rerank)이 요청되었는지 여부입니다.
schift.search.model	string	재정의된 경우 쿼리에 사용된 임베딩(embedding) 모델입니다.
schift.expand_neighbors.enabled	bool	이웃 확장(neighbor expansion)이 활성화되었는지 여부입니다.
schift.filter.keys	string[]	적용된 메타데이터(metadata) 필터 키입니다.
schift.filter.ops	string[]	적용된 필터 연산자입니다. 예: eq 또는 like.
schift.schiftql.plan_digest	string	해당하는 경우 실행된 SchiftQL 계획의 다이제스트(digest)입니다.
schift.search.method	string	실제로 실행된 검색(retrieval) 메서드입니다.
schift.search.results.count	int	반환된 결과 개수입니다.
schift.search.scores.top	float	최상위 결과의 점수입니다.
schift.search.scores.avg	float	결과 전체의 평균 점수입니다.
schift.timing.total_ms	int	총 검색 지연 시간(latency)(밀리초)입니다.
schift.search_id	string	내부 검색 상관관계 ID입니다.
schift.search.error	string	검색 실패 시 오류 유형입니다.

이러한 속성(attribute)을 사용하면 구조화되지 않은 로그를 파싱하지 않고도 버킷(bucket), 검색 메서드, 필터 형태, 결과 개수, 지연 시간(latency)별로 대시보드와 알림을 구축할 수 있습니다.

FastAPI 계측

텔레메트리(telemetry)가 활성화되면 Schift는 FastAPIInstrumentor.instrument_app(app)도 호출합니다. 이렇게 하면 들어오는 HTTP 요청에 대한 스팬(span)이 생성되고 W3C 트레이스 컨텍스트(trace context)가 전파(propagate)되므로, Schift API에서 내보내는 스팬이 상위 호출자와 상관관계를 가질 수 있습니다.

클라이언트 요청을 Schift 트레이스(trace)와 상관관계 지으려면 traceparent 헤더를 전파하세요:

from schift import Client

client = Client(
    api_key="...",
    headers={"traceparent": current_traceparent()},
)

import { WorkspaceClient } from "@schift-io/sdk";

const client = new WorkspaceClient({
  apiKey: "...",
  headers: { traceparent: currentTraceparent() },
});

고트래픽 샘플링

기본적으로 모든 트레이스(trace)를 샘플링(sampling)합니다. 고용량 배포 환경에서는 샘플링 비율을 낮추세요:

export OTEL_TRACES_SAMPLER="parentbased_traceidratio"
export OTEL_TRACES_SAMPLER_ARG="0.1"

이렇게 하면 10%의 트레이스(trace)를 샘플링하면서 부모-자식 상관관계는 유지됩니다.

벤더 예시

Datadog Agent

export OTEL_EXPORTER_OTLP_ENDPOINT="http://datadog-agent:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

Honeycomb

export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.honeycomb.io"
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<your-api-key>,x-honeycomb-dataset=schift"

Grafana Tempo 또는 Jaeger

export OTEL_EXPORTER_OTLP_ENDPOINT="http://tempo:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

LangSmith 전용 안내는 LangSmith 통합을 참조하세요.

문제 해결

• 스팬(span)이 나타나지 않습니다. 앱 시작 전에 OTEL_EXPORTER_OTLP_ENDPOINT가 설정되었고 서버에서 엔드포인트(endpoint)에 도달할 수 있는지 확인하세요. init_telemetry()는 앱 생성 시 한 번만 호출되며, 부팅 후 런타임(runtime) 변경 사항은 반영되지 않습니다.
• 수집기(collector)가 스팬을 거부합니다. OTEL_EXPORTER_OTLP_PROTOCOL이 수집기의 리시버(receiver)와 일치하는지 확인하세요. 대부분의 HTTPS 기반 벤더(vendor)는 http/protobuf를 필요로 합니다.
• 높은 카디널리티(cardinality). schift.filter.keys에 무한한 값이 들어가지 않도록 주의하세요. 일부 벤더는 고유한 속성(attribute) 조합 수에 따라 요금을 청구합니다.

같이 보기

• Buckets
• API reference