在 goose 中接入 Laminar 实现 Agent 可观测性：OTLP 导出配置与 Trace 分析实战

在 goose 中接入 Laminar 实现 Agent 可观测性OTLP 导出配置与 Trace 分析实战【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/gooseLaminar是一款面向 AI Agent 的云原生可观测性平台通过标准 OpenTelemetryOTLP协议即可将 goose 会话中每一次 LLM 调用、工具执行与子代理sub-agent运行过程记录为可检索、可回放的 trace。本教程以 documentation/docs/tutorials/laminar.md 为主线结合 goose 的 OpenTelemetry 源码实现crates/goose/src/otel/otlp.rs与官方环境变量指南带你完成 Laminar 账号准备、OTLP 环境变量配置、云端与自托管两种接入方式、常见坑位排查以及如何借助 Playground、数据集与自然语言看板把 trace 转化为可执行的评估闭环。为什么需要给 goose 接一个 Agent 观测平台goose 是「能安装、执行、编辑代码并调用任意 LLM 的 Agent」。Agent 的每一次决策背后都是多轮 LLM 推理与一连串工具调用先是读取文件、搜索符号、运行测试再基于结果继续推理。这个过程中任何一个环节的理解偏差都可能让整个任务跑偏而传统日志只能看到结果看不到决策链路。Laminar 的价值正在于把这条链路显性化高信号 traceLLM 调用、工具执行、子代理sub-agent都以 span 形式记录谁调用谁、花了多少 token、耗时多久一目了然Playground 回放任意一个 span 都可以在 Playground 中重放直接对比不同的 prompt 与模型在同一任务上的表现从生产数据构建数据集把线上真实 trace 沉淀为数据集用于后续批量评估自然语言分析用自然语言查询 trace 模式配合看板做趋势观察与异常定位。需要强调的是goose 本身并不绑定任何专有协议。它内部以标准 OpenTelemetry 规范产出 telemetry通过 OTLP/HTTP 上报这意味着任何兼容 OTLP 的平台Laminar、Langfuse、MLflow 乃至自建 Collector都可以成为观测后端。Laminar 只是其中一个高契合度的选择。第一步准备 Laminar 项目与 API KeyLaminar 提供两种使用形态Laminar Cloud托管版直接注册账号即可开箱即用自托管Self-hosted从 Laminar 的开源仓库自行部署数据完全掌控在本地。两种形态都需要先拿到Project API Key形如lmnr_proj_...。这个 Key 将作为鉴权凭证放在 OTLP 上报的authorization请求头中因此请妥善保管不要提交进版本库。goose 的 OTLP 导出机制先理解底层再配环境变量goose 通过 crates/goose/src/otel/otlp.rs 实现完整的 OpenTelemetry 导出能力默认导出三条信号signaltraces会话与工具执行链路追踪metrics周期上报的指标logs结构化日志通过OpenTelemetryTracingBridge桥接tracing日志框架。出口判定逻辑集中在signal_exporter()crates/goose/src/otel/otlp.rs其判定优先级依次为OTEL_SDK_DISABLEDtrue全局关闭所有导出OTEL_{SIGNAL}_EXPORTER如OTEL_TRACES_EXPORTER显式指定该信号的导出器类型取值otlp、console、none其中none直接禁用对应信号console表示只打印到标准输出便于本地调试无需 CollectorOTEL_EXPORTER_OTLP_{SIGNAL}_ENDPOINT或OTEL_EXPORTER_OTLP_ENDPOINT只要配置了非空的 endpoint就自动启用 OTLP 导出。也就是说你并不需要额外开启什么开关只要按上文设置OTEL_EXPORTER_OTLP_ENDPOINTgoose 就会自动把 trace 等数据上报到该地址这也解释了官方环境变量指南中设置 endpoint 即开启导出的描述。两点值得注意的实现细节协议只支持 HTTP。goose 的opentelemetry-otlp构建仅启用http-proto传输默认http/protobuf也兼容http/json未启用grpc-tonic。若环境中存在OTEL_EXPORTER_OTLP_PROTOCOLgrpcgoose 会跳过该信号并打印一次性 stderr 警告见 otlp.rs 与对应测试 otlp.rs因此请务必保持 endpoint 为http://...形式每条上报都带有会话级资源属性。create_resource()crates/goose/src/otel/otlp.rs会为数据附加service.namegoose、service.version、service.namespacegoose、host.name、user.name等资源属性且支持通过OTEL_SERVICE_NAME、OTEL_RESOURCE_ATTRIBUTES覆盖或补充日志 span 还会携带session.id、session.user、session.host、session.agent_type等会话属性见 otlp.rs方便你在 Laminar 中按会话维度筛选分析。配置 goose 向 Laminar 导出 OTLPgoose 通过 OTLP/HTTP 上报只要把导出器指向 Laminar 的接收地址并把 Project API Key 作为authorization请求头带上即可。以下环境变量在启动 goose 前导出即可。接入 Laminar Cloudexport LMNR_PROJECT_API_KEYlmnr_proj_... export OTEL_EXPORTER_OTLP_ENDPOINThttps://api.lmnr.ai export OTEL_EXPORTER_OTLP_HEADERSauthorizationBearer ${LMNR_PROJECT_API_KEY} export OTEL_EXPORTER_OTLP_TIMEOUT10000接入自托管 Laminarexport LMNR_PROJECT_API_KEYlmnr_proj_... export OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:8000 export OTEL_EXPORTER_OTLP_HEADERSauthorizationBearer ${LMNR_PROJECT_API_KEY}如果你的自托管实例不要求鉴权可以直接省略OTEL_EXPORTER_OTLP_HEADERS。各变量含义与取值范围如下表环境变量作用取值说明LMNR_PROJECT_API_KEYLaminar 项目密钥形如lmnr_proj_...取自 Laminar 控制台OTEL_EXPORTER_OTLP_ENDPOINTOTLP 接收基地址基地址会自动拼接/v1/traces等信号路径OTEL_EXPORTER_OTLP_HEADERS附加请求头本场景传authorizationBearer ${LMNR_PROJECT_API_KEY}OTEL_EXPORTER_OTLP_TIMEOUT单次导出超时毫秒默认见 SDK建议显式设为10000排查提示如果迟迟看不到 trace尝试把 endpoint 显式写成带 OTLP 路径的完整地址例如https://api.lmnr.ai/v1/traces或http://localhost:8000/v1/traces。官方环境变量指南还补充了几个与导出行为直接相关的进阶变量可作为调优依据OTEL_EXPORTER_OTLP_{SIGNAL}_ENDPOINT针对单个信号traces/metrics/logs单独指定 endpoint优先级高于通用 endpointOTEL_TRACES_EXPORTERconsole不开 Collector 也能把 trace 打到 stdout 本地调试OTEL_TRACES_SAMPLERparentbased_traceidratioOTEL_TRACES_SAMPLER_ARG0.1生产环境按 10% 采样降噪降量OTEL_SERVICE_NAME覆盖service.name默认goose多环境部署时建议显式设置以便区分OTEL_SDK_DISABLEDtrue一键关闭全部导出。另外从 promote_config_to_env 的源码可以看出除了环境变量goose 的配置文件同样支持otel_exporter_otlp_endpoint与otel_exporter_otlp_timeout两个参数进程退出时的冲刷超时对应otel_shutdown_timeout_ms默认 5000ms见 shutdown_otlp。配置文件的优先级低于环境变量仅当对应环境变量未被设置时配置文件中的值才会被提升为环境变量。启动 goose 并观察 trace配置完成后像往常一样启动 goose 即可# 以交互式 TUI 启动 goose # 或以 headless 模式执行单条指令会自动带上 telemetry 上下文 goose run 分析当前目录下的项目结构并输出报告只要 OTLP 环境变量在位goose 会话期间产生的 trace 与工具执行记录就会被批量上报到 Laminar无需任何代码改动。此后你可以在 Laminar 的 trace 列表中找到对应会话逐 span 查看LLM 请求/响应、工具入参与出参、token 消耗与耗时对可疑的 span 在Playground中重放尝试替换 prompt 或模型对比效果把表现良好的线上 trace 收集为数据集接入后续的评估与回归流程用自然语言查询与看板统计失败率、工具调用频率、超时分布等模式定位 Agent 的行为瓶颈。在 gooes 侧导出的数据并非全量倾泻trace 过滤器默认接收 INFO 及以上级别的 span 事件并额外放行goose::、opentelemetry等目标在 DEBUG 级别的事件见 create_otlp_tracing_filter同时会静默过滤rmcp::service这类可能携带用户记忆内容、体积高达 400KB 且无分析价值的敏感日志目标见 OTLP_SUPPRESSED_TARGETS以及边界测试 otlp.rs。这意味着上报到 Laminar 的数据在保证高信号的前提下已内置了一层隐私与体积保护。小结与下一步本文从 Laminar 的能力定位出发完成了 goose 的可观测性接入闭环申请 Project API Key → 设置 OTLP endpoint 与鉴权头 → 正常启动 goose → 在 Laminar 中分析、回放与评估 trace。接入过程中你同时了解了 goose 的 OpenTelemetry 三层信号模型、HTTP-only 协议约束、会话级资源属性以及敏感目标过滤等源码级细节这些同样适用于自建 Collector 或接入其他 OTLP 平台。若你想深入了解 goose 端的环境变量全貌与采样调优可继续阅读官方环境变量指南中的 Observability 一节若希望对比其他观测后端仓库中的 Langfuse 教程与 MLflow 教程提供了同构的集成路径。【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考