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 是一个开源的 Python SDK，为生成式 AI 应用和智能体（Agent）添加了兼容 OpenTelemetry 的追踪功能。它能够自动对主流框架（LangChain、LlamaIndex、Haystack、Google ADK、Claude CLI 等）进行插桩，并针对提示词（prompts）、LLM 调用、工具调用、向量数据库查询以及智能体运行元数据生成结构化的 span。配套的 monocle-test-tools 包允许你编写 pytest 风格的测试，直接对这些追踪数据进行断言，而不仅仅是验证输出结果。

重要性 – 生成式 AI 智能体通常被视为黑盒，这使得调试、成本监控、合规性检查和 CI 测试变得困难。Monocle 将智能体执行的每一步转化为可视化的时间线，可以发送到任何 OTLP 收集器、存储为 JSON，或通过 Okahu VS Code 扩展进行可视化展示。

核心功能（README 中所述）

功能	描述
元模型	定义了智能体、提示词、响应、工具和向量操作的标准 span 属性的 JSON 模式。
自动插桩适配器	为多种 GenAI 技术栈（LangChain、LlamaIndex、Haystack、Google ADK、Claude CLI、Codex CLI、Copilot、AWS Bedrock、Azure OpenAI 等）提供即插即用的支持，无需手动创建 span。
兼容 OTLP 导出	追踪数据可发送至任何 OpenTelemetry 收集器、写入本地文件，或推送到云端后端（AWS S3、Azure Blob、Okahu cloud、PostgreSQL、ClickHouse 等）。
Scope API	提供上下文管理器/装饰器辅助工具（`monocle_trace_scope`、`monocle_trace_scope_method`），用于将业务属性（user-id、tenant-id、session-id）附加到代码块中的每个 span。
内置脱敏	自动从 span 中屏蔽敏感信息；可通过环境变量（`MONOCLE_OBFUSCATE_ENV_VALUES`、`MONOCLE_OBFUSCATE_EXTRA_PATTERNS`）进行配置。
零代码包装模式	提供 CLI 风格的入口点（`monocle_apptrace …`），无需修改源码即可追踪脚本，适用于 Lambda 层或平台级注入。
`monocle-test-tools`	pytest 扩展，允许对追踪内容进行断言：包括运行了哪些智能体、调用了哪些工具、Token/成本限制、持续时间以及更高级的评估指标（角色遵循、知识留存等）。
IDE 集成	Okahu VS Code 扩展可读取 Monocle JSON 文件，并显示带有 Token 计数和错误标记的甘特图风格时间线。
Linux 基金会治理	该项目托管在 LF AI & Data 旗下，并遵循 Apache-2.0 许可协议。

典型用例

调试复杂智能体 – 可视化每一次 LLM 调用和工具使用，以查明回答出错的原因。
成本与合规性监控 – 追踪 Token 使用情况并自动屏蔽敏感信息；在 CI 中强制执行 Token 预算限制。
AI 流程的 CI/CD 测试 – 编写 monocle-test-tools 测试，验证智能体和工具调用的正确顺序，而不仅仅是最终输出。
平台级可观测性 – 基础设施团队可以通过包装模式注入追踪，为 SRE 提供所有 GenAI 服务的统一视图。
多租户追踪 – 使用 Scope API 为 span 添加 tenant_id 或 session_id 标签，以便在仪表板中轻松过滤。

入门指南（README 快速入门）

# 安装 SDK
pip install monocle_apptrace

# 一次性遥测设置（通常在应用启动时）
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 行为进行测试驱动的验证。