Monocle GenAI 追踪框架

这个 Agent 能做什么，适合哪些场景？

Monocle 是 Linux Foundation AI & Data 旗下的开源项目，本仓库提供其 Python 实现（monocle_apptrace），定位为面向 GenAI 应用的可观测层。核心由三部分组成：定义智能体、提示词、工具调用与向量操作等实体的元模型（span_format.），自动生成 span 的框架适配器，以及 OTLP 兼容的追踪导出。初始化一次 setup_monocle_telemetry() 即可自动插桩 LangChain、LlamaIndex、Google ADK、OpenAI、Anthropic 等主流框架，默认将追踪导出为本地 JSON 文件，也可接入云存储或任意 OTEL 后端。配套的 monocle_test_tools 包基于 pytest，让你对追踪本身做断言（智能体调用、工具行为、token 成本），而不只是输入输出对。适合需要调试、可靠性与合规能力的应用开发者、平台工程师和企业 SRE 团队。

安装 monocle_apptrace 后，调用一次 setup_monocle_telemetry(workflow_name=...) 即完成 OpenTelemetry 接线、元模型配置和对已支持框架的自动插桩；框架适配器为智能体运行、工具调用、LLM 推理和检索查询自动创建标准化 span。默认导出为 ./monocle 目录下的 JSON 追踪文件（monocle_trace_{workflow}_{trace_id}_{timestamp}.），也可导出到 stdout、Azure Blob、AWS S3、GCS、PostgreSQL、ClickHouse、Okahu 云等。通过 monocle_trace_scope / monocle_trace_scope_method 可为 span 附加 user_id、tenant_id 等业务上下文。配套的 monocle_test_tools 提供 expected() 流式断言（called_agent、called_tool、under_token_limit、under_duration）以及 MonocleValidator 多轮会话评估；还支持零代码的包装模式（monocle-apptrace claude-setup / codex-setup / copilot-setup）为 Claude CLI、Codex CLI、GitHub Copilot 注册钩子。

1. 应用开发者想在不逐个函数手写 OpenTelemetry 代码的情况下，追踪任意环境中的 LangChain 或 LlamaIndex 智能体的每次模型调用与工具调用。
2. 平台/基础设施团队希望通过包装模式（不修改产品代码）为多租户 AI 平台注入追踪，并用 tenant_id scope 区分租户。
3. QA 工程师用 monocle_test_tools 在 CI/CD 中断言智能体确实调用了正确的工具、输出符合预期且 token 用量在预算内。
4. SRE 团队需要将 GenAI 追踪送入既有 OTEL 收集器、APM 或 Okahu 云做生产环境监控与排障。
5. 使用 Claude Code、Codex CLI 或 GitHub Copilot 的开发者想追踪这些 AI 编程助手与代码库的交互过程。
6. 需要评估多轮会话质量（角色遵循度、知识保留度）的团队，可基于 session_id 聚合追踪并运行 agentic_sessions 评估。

这个 Agent 有哪些优点和局限？

如何安装或部署这个 Agent？

pip install monocle_apptrace

# 测试框架（可选）

pip install monocle_test_tools

# 为 AI 编程 CLI 注册追踪钩子（可选）

uv tool install monocle_apptrace

monocle-apptrace claude-setup # 或 codex-setup / copilot-setup

需要 Python 运行环境；无强制云凭据，默认本地文件导出即可工作，接入 Okahu 云需 GitHub 登录或粘贴 API key。

如何使用这个 Agent？

from monocle_apptrace import setup_monocle_telemetry
setup_monocle_telemetry(workflow_name="simple_math_app")

# 运行你的应用后，检查 ./monocle/ 下的 JSON 追踪文件，
# 或用 Okahu VS Code 扩展查看甘特图时间线。

# 业务上下文：

from monocle_apptrace.instrumentation.common.instrumentor import monocle_trace_scope

with monocle_trace_scope("user_id", "user-123"):

result = my_agent.run("What's the weather in London?")

# 测试：

from monocle_test_tools import expected

def test_weather_agent():
result = expected(input="What is the weather in London?",

expected_output="weather report for London")
result.called_agent("weather_agent")
result.called_tool("get_weather", agent_name="weather_agent")
result.under_token_limit(5000)