monocle2ai/monocle
Monocle is a framework for tracing GenAI app code. This repo contains implementation of Monocle for GenAI apps written in Python.
Monocle – GenAI 앱을 위한 관측 가능성 및 테스트 도구
개요 – Monocle은 생성형 AI 애플리케이션 및 에이전트에 OpenTelemetry 호환 추적 기능을 추가하는 오픈 소스 Python SDK입니다. 이 도구는 널리 사용되는 프레임워크(LangChain, LlamaIndex, Haystack, Google ADK, Claude CLI 등)를 자동으로 계측하며, 프롬프트, LLM 호출, 도구 호출, 벡터 저장소 쿼리 및 에이전트 실행 메타데이터에 대한 구조화된 스팬(span)을 생성합니다. 함께 제공되는 monocle-test-tools 패키지를 사용하면 단순히 출력값뿐만 아니라 이러한 추적 데이터를 기반으로 검증하는 pytest 스타일의 테스트를 작성할 수 있습니다.
중요성 – GenAI 에이전트는 종종 블랙박스로 취급되어 디버깅, 비용 모니터링, 규정 준수 및 CI 테스트를 어렵게 만듭니다. Monocle은 에이전트 실행의 모든 단계를 가시적인 타임라인으로 변환하여 모든 OTLP 수집기로 전송하거나, JSON으로 저장하거나, Okahu VS Code 확장 프로그램을 통해 시각화할 수 있게 합니다.
주요 기능 (README 설명 기준)
| 기능 | 제공 내용 |
|---|---|
| 메타모델 | 에이전트, 프롬프트, 응답, 도구 및 벡터 작업에 대한 표준 스팬 속성을 정의하는 JSON 스키마. |
| 자동 계측 어댑터 | 다양한 GenAI 스택(LangChain, LlamaIndex, Haystack, Google ADK, Claude CLI, Codex CLI, Copilot, AWS Bedrock, Azure OpenAI 등)에 대한 플러그 앤 플레이 지원 – 수동 스팬 생성 불필요. |
| OTLP 호환 내보내기 | 추적 데이터를 모든 OpenTelemetry 수집기로 전송하거나, 로컬 파일에 기록하거나, 클라우드 백엔드(AWS S3, Azure Blob, Okahu cloud, PostgreSQL, ClickHouse 등)로 푸시 가능. |
| Scope API | 블록 내 모든 스팬에 비즈니스 속성(user-id, tenant-id, session-id)을 첨부하기 위한 컨텍스트 관리자/데코레이터 도우미 (monocle_trace_scope, monocle_trace_scope_method). |
| 내장 난독화 | 스팬에서 비밀 정보를 자동으로 삭제; 환경 변수(MONOCLE_OBFUSCATE_ENV_VALUES, MONOCLE_OBFUSCATE_EXTRA_PATTERNS)를 통해 구성 가능. |
| 제로 코드 래퍼 모드 | CLI 스타일 진입점(monocle_apptrace …)을 통해 소스 수정 없이 스크립트를 추적 – Lambda 레이어 또는 플랫폼 수준 주입에 유용. |
monocle-test-tools |
추적 내용을 기반으로 검증할 수 있는 pytest 확장: 실행된 에이전트, 호출된 도구, 토큰/비용 제한, 지속 시간 및 상위 수준 평가 사실(역할 준수, 지식 유지 등). |
| IDE 통합 | Okahu VS Code 확장 프로그램이 Monocle JSON 파일을 읽어 토큰 수와 오류 배지가 포함된 간트 차트 스타일의 타임라인을 표시. |
| Linux Foundation 거버넌스 | 프로젝트는 LF AI & Data 산하에서 호스팅되며 Apache-2.0 라이선스를 따름. |
일반적인 사용 사례
- 복잡한 에이전트 디버깅 – 모든 LLM 호출과 도구 사용을 시각화하여 답변이 잘못된 원인을 정확히 파악.
- 비용 및 규정 준수 모니터링 – 토큰 사용량을 추적하고 비밀 정보를 자동으로 삭제하며, CI에서 토큰 예산 제한을 강제.
- AI 흐름의 CI/CD 테스트 – 최종 출력뿐만 아니라 에이전트 및 도구 호출의 올바른 순서를 검증하는
monocle-test-tools테스트 작성. - 플랫폼 수준의 관측 가능성 – 인프라 팀이 래퍼 모드를 통해 추적을 주입하여 SRE에게 모든 GenAI 서비스에 대한 통합된 뷰 제공.
- 멀티 테넌트 추적 – Scope API를 사용하여 스팬에
tenant_id또는session_id를 태그 지정하여 대시보드에서 쉽게 필터링.
시작하기 (README의 퀵스타트)
# SDK 설치
pip install monocle_apptrace
# 1회성 텔레메트리 설정 (보통 앱 시작 시)
python - <<'PY'
from monocle_apptrace import setup_monocle_telemetry
setup_monocle_telemetry(workflow_name="my_genai_app")
PY
이제 앱을 실행하면 ./monocle/ 아래에 JSON 추적 파일이 생성됩니다 (예: monocle_trace_my_genai_app_<trace_id>_<ts>.json).
테스트를 위해서는:
pip install monocle_test_tools
그런 다음 README 예제에 표시된 대로 expected 또는 MonocleValidator를 사용하여 pytest 함수를 작성하십시오.
생태계 및 통합
- 프레임워크 어댑터 – LangChain, LlamaIndex, Haystack, Google ADK, Claude CLI, OpenAI Codex CLI, GitHub Copilot, AWS Bedrock Agentcore, Azure AI Foundry 등.
- 내보내기 대상 – stdout, 로컬 파일, 메모리 내, Azure Blob, AWS S3, Okahu cloud, 일반 OTEL 수집기, Google Cloud Storage, PostgreSQL, ClickHouse, Paygentic.
- IDE – 대화형 타임라인 뷰를 위한 Okahu Trace Visualizer VS Code 확장 프로그램.
- 언어 지원 – 기본 Python SDK; TypeScript 동반 저장소(
monocle-typescript)가 연결되어 있음.
라이선스
Apache-2.0 (README의 배지에 표시된 대로).
결론 – Monocle은 생성형 AI 애플리케이션을 위한 즉시 사용 가능한 OpenTelemetry 기반 관측 가능성 계층을 제공하여, 불투명한 에이전트 실행을 구조화되고 검색 가능한 추적으로 변환하고 AI 동작에 대한 테스트 기반 검증을 가능하게 합니다.
관련
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트