Otellix
LLM 청구서 충격(Bill Shock)을 막으세요. OpenTelemetry를 기반으로 구축된 Go 백엔드용 프로덕션급 관측 가능성.
Otellix Dashboard
<div align="center">
<a href="https://oluwajubelo1.github.io/otellix/docs/demo/"><strong style="font-size: 1.2em;">실시간 인터랙티브 데모 →</strong></a>
</div>
CI
Go Reference
Go Report Card
License: MIT
💸 문제점: '청구서 충격(Bill Shock)'은 현실입니다.
대부분의 LLM 관측 가능성 도구는 돈이 나간 후에 얼마나 지출했는지 알려줄 뿐입니다. 프로덕션 환경에서 재귀적 프롬프트 루프(recursive prompt loop)나 단 한 명의 '파워 유저'가 청구서 알림이 울리기 전에 수천 달러의 비용을 발생시킬 수 있습니다.
Otellix는 다릅니다. 애플리케이션 계층에 실시간 비용 강제 적용 기능을 제공합니다.
⚡ 주요 기능 (Key Features)
- 🧩 원라인 SDK 미들웨어(One-Line SDK Middleware): 공식 OpenAI 또는 Anthropic Go SDK를 이미 사용하고 있나요?
option.WithMiddleware(otellixopenai.Middleware(...))만 추가하면 모든 호출이 추적되고, 비용이 계산되며, 예산 책정됩니다. 기존 호출 방식은 변경되지 않습니다.
- ⛓️ LangChainGo 통합: LangChainGo용 드롭인(Drop-in)
callbacks.Handler를 제공합니다. 체인(chain)에 대한 토큰, 비용, 스팬(span)을 자동으로 캡처합니다.
- 🔌 자동 기여도 할당 (Automatic Attribution): Gin, Echo 또는 Fiber 미들웨어를 통해 인증(auth) 과정이나 검증된 JWT로부터
user_id와 project_id를 캡처합니다. 수동적인 컨텍스트 배선 작업이 필요 없으며, 호출자가 예산을 우회할 방법도 없습니다.
- 🗄️ Redis 예산 저장소 (Redis Budget Store): 고가용성(high-availability) 프로덕션 클러스터를 위한 분산형 예산 강제 적용 기능을 제공합니다.
- 🚀 Go 네이티브 및 고성능: 네이티브 스트리밍과 OpenTelemetry를 사용하여 Go 1.22+ 환경에 최적화되어 구축되었습니다.
- 📊 표준 준수 (OTel): OTel(OpenTelemetry)을 100% 준수합니다. Jaeger, Honeycomb, Prometheus, Grafana와 함께 작동합니다.
- 💎 프롬프트 캐싱 ROI: Anthropic/OpenAI의 프롬프트 캐싱을 통해 정확히 얼마나 많은 비용을 절약했는지 추적할 수 있습니다.
🚀 빠른 시작 (Quick Start)
go get github.com/oluwajubelo1/otellix
🕹️ 로컬에서 사용해 보기 (Docker)
(Prometheus + Grafana) 전체 스택이 작동하는 것을 보고 싶으신가요? 다음 원라인 데모를 실행하세요:
curl -sL https://raw.githubusercontent.com/oluwajubelo1/otellix/main/scripts/demo.sh | bash
1. 간단한 트레이싱 (Simple Tracing)
프로바이더 호출을 감싸서 즉각적인 비용 할당(cost attribution)과 표준 OTel 스팬을 얻으세요.
p := openai.New()
result, err := otellix.Trace(ctx, p, params,
otellix.WithUserID("user_456"),
...
2. LangChainGo 통합 (Integration)
Otellix 핸들러를 LLM 설정에 추가하기만 하면 됩니다.
import "github.com/oluwajubelo1/otellix/integrations/langchaingo"
handler := langchaingo.NewOtellixHandler(...)
이 핸들러는 컨텍스트 내 스팬에 llm.* 속성을 기록하거나, 존재하지 않으면 자체 llm.call 스팬을 생성하여 항상 원격 측정(telemetry)이 캡처되도록 합니다. 비용 추적을 활성화하려면 WithProvider/WithModel을 설정하세요 (LangChainGo는 콜백에서 이를 노출하지 않습니다).
3. 미들웨어 기반 속성 할당 (Middleware Attribution)
ID를 수동으로 전달하는 것을 중단하세요. 미들웨어가 각 요청의 사용자 및 프로젝트 정보를 컨텍스트에 넣기 때문에, 이를 처리하는 동안 이루어지는 모든 LLM 호출이 할당됩니다(attributed).
import otellixmw "github.com/oluwajubelo1/otellix/middleware"
r := gin.Default()
...
예산(Budget)은 검증된 신원(verified identity)에만 제한을 적용하므로, 호출자가 새로운 사용자 ID를 위조하여 사용자별 한도를 회피할 수 없습니다. 검증된 신원 및 예산을 참조하세요.
4. 로컬 개발 (Local Development)
두 가지 개발 모드는 빌드하는 동안 트레이스를 볼 수 있도록 도와줍니다:
shutdown := otellix.SetupDev()
defer shutdown()
...
- **
SetupDev()**는 OpenTelemetry stdout 트레이스 익스포터(사람이 읽을 수 있는 요약 및 원시 스팬 JSON)를 구성합니다. 정확한 스팬 페이로드를 검사하는 데 가장 적합합니다.
- **
SetupDevConsole()**은 호출당 한 줄의 [otellix] 요약만 출력하고 기존 TracerProvider는 건드리지 않습니다. 데모 및 발표에 이상적입니다.
RegisterDevPrinter()는 이미 자체 TracerProvider가 구성된 경우, 요약 프린터만 활성화합니다.
📊 표준화된 OTel 속성 (Standardized OTel Attributes)
Otellix는 업계 표준 속성을 사용하여 스팬을 채웁니다:
| 속성 (Attribute) | 설명 (Description) |
|---|
llm.provider | LLM 제공업체 (OpenAI, Anthropic 등) |
| ... | |
🏗️ 지원되는 제공업체 (Supported Providers)
Provider wrappers (드롭인 방식의 Call/Stream):
- Anthropic: Claude Opus/Sonnet/Haiku 계열에 전체 프롬프트 캐싱(Prompt Caching) 메트릭을 지원합니다.
- OpenAI: GPT-5.x, GPT-4.x, o-series, gpt-oss를 캐싱 지원과 함께 제공합니다.
- Google Gemini: Gemini 3.x, 2.5, 2.0 및 1.5 Pro/Flash를 지원합니다.
- Ollama: 의존성 없이 로컬 모델 스트리밍을 지원합니다.
가격만 지원하는 경우 (Pricing-only support) (llm.cost_usd에 대한 내장 비용 테이블 제공; 사용자 정의 제공업체/API 연결 가능): Kimi (Moonshot), DeepSeek, Qwen, GLM, ERNIE, Hunyuan, Mistral, Grok 및 위에 언급된 모든 모델 — 총 130개 이상의 모델을 지원합니다. docs/providers.md를 참조하세요.
📖 심층 탐구(Deep Dives)
🤝 기여하기(Contributing)
별점과 기여를 환영합니다! [CONTRIBUTING.md] 파일을 참조해 주세요.
MIT 라이선스 하에 배포됩니다.
