monocle2ai/monocle

Monocle is a framework for tracing GenAI app code. This repo contains implementation of Monocle for GenAI apps written in Python.

What it solves

Monocle은 생성 AI 애플리케이션 및 에이전트를 위한 관측성 및 테스트 기능을 제공합니다. "블랙박스" AI 에이전트를 투명한 단계별 트레이스로 변환하여 개발자가 모델 호출, 도구 호출 및 벡터 조회를 연결된 타임라인에서 확인할 수 있게 합니다. 또한 최종 출력만 확인하는 것이 아니라 실제 실행 트레이스에 대한 어설션(예: 어떤 도구가 호출되었는지 검증)을 허용함으로써 AI 에이전트 테스트 문제를 해결합니다.

How it works

Monocle은 OpenTelemetry 위에 구축된 GenAI 전용 관측성 레이어입니다. 에이전트, 프롬프트, 벡터 연산과 같은 엔터티를 span 속성에 매핑하는 메타모델을 사용합니다. LangChain, LlamaIndex, Haystack 등 인기 프레임워크용 계측 어댑터를 제공하여 수동 코딩 없이 자동으로 트레이스를 생성합니다. 이러한 트레이스는 OTLP 호환 스팬으로 방출되어 표준 관측성 백엔드에 전송하거나 Okahu VS Code 확장으로 시각화할 수 있습니다.

Who it’s for

앱 개발자 – 맞춤형 OpenTelemetry 코드를 작성하지 않고 GenAI 앱을 추적하고 싶은 사람.
플랫폼·인프라 엔지니어 – 애플리케이션 코드를 리팩터링하지 않고 래퍼나 오퍼레이터를 통해 추적을 주입하고 싶은 사람.
엔터프라이즈·SRE – 표준화된 OTel 호환 트레이스와 AI 파이프라인을 위한 CI 친화적 테스트가 필요한 사람.

Highlights

네이티브 OpenTelemetry 지원: 모든 APM 또는 콜렉터와 호환되는 표준 OTLP 스팬을 방출합니다.
자동 계측: 다양한 에이전트 프레임워크, LLM 제공자 및 벡터 스토어를 지원합니다.
트레이스 기반 테스트: monocle-test-tools를 사용해 에이전트 동작, 도구 사용, 토큰 비용 및 실행 시간을 pytest로 어설션할 수 있습니다.
유연한 배포: 코드 내 초기화와 AWS Lambda와 같은 환경을 위한 제로코드 래퍼/오퍼레이터 모드를 모두 제공합니다.
AI 어시스턴트 추적: Claude CLI, OpenAI Codex CLI, GitHub Copilot용 특수 설정 훅을 제공합니다.