swarms 框架 Telemetry 遥测与可观测性实战指南从装饰器到 OpenTelemetry 追踪【免费下载链接】swarmsThe Enterprise-Grade Multi-Agent Orchestration Framework. Website: https://swarms.ai项目地址: https://gitcode.com/GitHub_Trending/swar/swarms遥测Telemetry是让多智能体系统“可观测”的关键能力它负责监控 Agent 的每一次运行、记录操作日志、上报性能数据与异常从而把黑盒式的智能体调用变成可追踪、可分析的链路。本文以 swarms 仓库的 examples/utils/telemetry/README.md 为切入点结合 swarms/telemetry 模块源码与 tests/telemetry/test_telemetry.py 测试用例完整讲解如何在 swarms 中为 Agent 与各类 Swarm 架构接入监控与可观测性读完你将掌握遥测开关的配置方法、trace_run装饰器与capture_run上下文管理器的用法、配置快照与错误追踪的采集方式以及遥测数据如何通过 OpenTelemetry OTLP 协议导出。遥测模块是什么定位与整体架构原文档对遥测示例给出了清晰的主题界定This directory contains examples demonstrating telemetry and monitoring capabilities for agents. Telemetry examples demonstrate how to add monitoring, logging, and observability to agents. These examples show how to track agent performance, log operations, and monitor agent behavior using decorators and class methods.翻译过来即是遥测示例用于演示如何为 Agent 添加监控monitoring、日志记录logging与可观测性observability核心手段是装饰器decorators与类方法class methods目标是追踪 Agent 性能、记录操作并监控 Agent 行为。这一定位在仓库中有着完整的落地实现。虽然examples/utils/telemetry/目录当前仅包含 README 文档但与之对应的核心实现集中在 swarms/telemetry 模块下包含四个文件文件职责swarms/telemetry/otel.pyOpenTelemetry 封装核心SwarmTelemetry类、trace_run装饰器、capture_run/capture_init/capture_error、ContextThreadPoolExecutor等swarms/telemetry/main.py系统信息采集与身份标识帮助函数get_comprehensive_system_info、get_machine_id、generate_user_idswarms/telemetry/bootup.py启动阶段的环境初始化与遥测、日志级别联动swarms/telemetry/init.py模块导出入口将上述 API 汇总为__all__从模块结构可以看出遥测能力分为两条主线身份与系统信息采集main.py以及链路追踪Tracingotel.py。其中otel.py是绝对核心它直接基于 OpenTelemetry SDK 构建是整篇文章的主体。遥测总开关SWARMS_TELEMETRY_ON 与相关环境变量在使用任何遥测 API 之前先要理解框架的总开关。源码 swarms/telemetry/otel.py 中的telemetry_on()函数定义了唯一的口径读取环境变量SWARMS_TELEMETRY_ON默认开启——只要该变量未设置遥测就是开启状态只有把变量显式设置为false、0、no、off、disable、disabled大小写不敏感且允许首尾空白时才会关闭空字符串或纯空白值同样视为关闭因此.env中的SWARMS_TELEMETRY_ON是显式关停而非误开。这一开关是全局共享的“唯一门闸”one on/off gatemain.py的log_agent_data与otel.py的整套追踪体系共用同一判断保证整个框架行为一致。除此之外otel.py顶部还定义了三个可通过环境变量调节的参数环境变量默认值作用SWARMS_OTEL_MAX_CHARS16000单个 span 属性payload最大字符数超出后截断并附加…[truncated]标记SWARMS_OTEL_MAX_CONFIG_CHARS65536序列化后的配置快照JSON 字符串最大长度SWARMS_OTEL_TIMEOUT8OTLP HTTP 导出的超时秒数避免死网络拖慢进程退出在 tests/telemetry/test_telemetry.py 中测试则会在导入模块前先设置os.environ[SWARMS_TELEMETRY_ON] true这正是为了在构造 telemetry 单例之前让开关被正确读取——单例构造后修改环境变量不会生效需重启进程。装饰器与类方法两大采集入口原文档强调的 “using decorators and class methods” 在otel.py中对应两套 API装饰器trace_run与上下文管理器/类方法capture_run。它们是把“每一次运行”变成一条 span 的两种等价写法。trace_run一键装饰方法trace_run是模块级装饰器用法最简洁。它接收两个参数span 名称name与需要捕获的方法参数名列表input_params默认(task,)。被装饰的方法每次调用都会打开一个名为name的 span并打上实例身份属性把指定的入参按名字捕获为swarms.input.key属性正常调用原方法若返回成功则记录输出并标记为completed若抛异常则由capture_run自动记录错误。官方 docstring 中的示例用法为trace_run(Agent.run, input_params(task, img)) def run(self, taskNone, imgNone, ...): ...该装饰器在仓库中已被真实使用——swarms/structs/agent.py 中的核心 Agent 类对run方法应用了trace_run(Agent.run, input_params(task, img, imgs))。也就是说你在日常使用Agent时只要遥测开启每一次run调用都会自动生成一条Agent.runspan无需任何额外代码。capture_run细粒度上下文管理capture_run是SwarmTelemetry类的上下文管理器也是模块级便捷函数capture_run的底层实现。它对多返回值路径的方法更加灵活from swarms.telemetry.otel import capture_run with capture_run(SwarmRouter.run, self, tasktask) as span: result self._run(...) span.record_output(result)入参以swarms.input.key属性记录None值会被跳过返回的span是一个_SpanHandle句柄提供set、record_output、record_error三个方法若块内抛出异常异常会被自动捕获并记录随后原样重新抛出raise不会吞掉错误当遥测关闭时capture_run退化为一个 no-op 句柄成本趋近于零。capture_init初始化配置快照capture_init用于在组件构造时发出一条ClassName.initspan。它最有价值的地方在于配合init_configinit_config通过inspect.signature(type(obj).__init__)反射出构造函数参数再逐一把同名属性序列化为 JSON 字符串作为swarms.config属性写入 span。这保证了采集到的是输入配置而非内部运行时状态对无法 JSON 编码的值如函数、类、自引用容器会通过_describe输出确定性的限定名或unserializable ClassName且绝不输出内存地址——因为地址会让两次相同构造产生不同字符串破坏遥测后端的归组能力。在 swarms/structs/sequential_workflow.py 中SequentialWorkflow的构造末尾即调用capture_init(self)Agent类也在 swarms/structs/agent.py 附近注释中表明会“Capture the full__init__configuration if telemetry is enabled”。这意味着你不需要手动埋点组件的完整构造参数就会自动进入追踪链路。capture_error捕获被吞掉的异常capture_error专门用于已被捕获且不再上抛的异常。例如某个工作流为了继续运行而吞掉单个 Agent 的失败时capture_run永远看不到这个异常此时应手动调用from swarms.telemetry.otel import capture_error try: result agent.run(task) except Exception as e: capture_error(e, self, agentagent.agent_name) result None # swallowed to keep the swarm going它会生成一条Component.errorspan记录swarms.status、swarms.error.type、swarms.error.message并调用span.record_exception与错误状态。反之直接穿透capture_run/trace_run块的异常会被自动捕获无需额外调用。SwarmTelemetry 类底层的 fail-safe 设计SwarmTelemetryswarms/telemetry/otel.py是整套遥测的运行时载体其核心设计原则是fail-safe永不向调用方抛异常构造时读取telemetry_on()门闸并检测 OpenTelemetry 依赖任一条件不满足时实例保持惰性ready False所有方法退化为廉价 no-op配置就绪时创建TracerProviderservice.name默认取环境变量OTEL_SERVICE_NAME缺省为swarms通过BatchSpanProcessorOTLPSpanExporter把 span 批量导出到遥测端点TELEMETRY_BASE_URL /v1/traces见 otel.py导出超时受SWARMS_OTEL_TIMEOUT约束若初始化失败缺依赖、配置错误仅以 debug 级别日志提示绝不影响正常程序运行。此外swarm_telemetry()otel.py是一个lru_cache单例进程内全局共享首次调用时惰性构建。身份标注_set_identity同样值得一提每个 span 会自动打上swarms.component类名、swarms.name优先取agent_name其次name、swarms.id以及多智能体架构才有的swarms.swarm_type对Agent与 swarm 还会按 GenAI 语义约定写入gen_ai.operation.name为agent或swarm。这些统一属性让后端查询时可以按组件、名称、类型快速过滤。并发场景下的上下文传播多智能体框架大量使用线程池并发执行而 OpenTelemetry 的当前 span 存放在 context var 中新线程不会继承。若不做处理线程内产生的 span 会脱离父 trace形成孤立的根 trace父/子结构随之丢失。otel.py为此提供了两个关键设施bind_context把函数绑定到绑定时刻的 OTel context内部用context.attach/context.detach恢复上下文ContextThreadPoolExecutorThreadPoolExecutor的直接替代品submit时自动为每个任务绑定调用方的追踪上下文保证一个并发 swarm 的所有 Agent span 都嵌套在同一条 trace 之下。swarms/structs/agent.py 的导入列表证实了ContextThreadPoolExecutor已被 Agent 内部使用用于承载并发执行路径。状态快照与系统信息log_agent_data 与身份帮助函数log_agent_datalog_agent_data是main.py旧版遥测 POST 的 OpenTelemetry 替代品接收组件的to_dict()状态载荷将其序列化为一条swarms.statespan 的swarms.state属性。若载荷是 dict还会自动提取agent_name/name与id作为查询用身份属性。该函数同样受SWARMS_TELEMETRY_ON门闸控制且完全 fail-safe因此它被导出在 swarms/telemetry/init.py 中供全局使用。系统信息与身份帮助函数swarms/telemetry/main.py 提供三个轻量工具generate_user_id()基于uuid.uuid4()生成随机用户 IDget_machine_id()以platform.node()主机名的 SHA-256 十六进制摘要作为机器标识注意它不直接暴露原始主机名get_comprehensive_system_info()lru_cache(maxsize1)进程内只算一次聚合平台信息系统、发行版、架构、处理器、主机名、MAC 地址、逻辑/物理 CPU 核数、内存总量/已用/空闲/可用GB 单位、Python 版本并基于这些信息生成一个uuid5的unique_identifier。这些数据可作为遥测上报的环境上下文用于区分不同运行环境。遥测在整个框架中的覆盖范围遥测不是孤立模块而是被深度集成进几乎所有核心架构。对 swarms 目录的检索显示以下文件均直接引用了遥测 APIagent.py、sequential_workflow.py、concurrent_workflow.py、agent_rearrange.py、round_robin.py、mixture_of_agents.py、majority_voting.py、batched_grid_workflow.py、swarm_router.py、hiearchical_swarm.py、graph_workflow.py、groupchat.py、heavy_swarm.py、llm_council.py、multi_agent_router.py、council_as_judge.py、debate_with_judge.py、planner_worker_swarm.py、model_router.py、self_moa_seq.py、spreadsheet_swarm.py等。从源码结构看从单 Agent 到编排类 Swarm遥测已经作为框架内置能力贯穿全链路你通常无需手动埋点即可获得基础可观测性。测试如何验证遥测行为tests/telemetry/test_telemetry.py3084 行是覆盖最完整的验证依据其文件头 docstring 明确列出了四大测试关注点原语Primitivescapture_run、capture_error、trace_run、capture_init、payload 模式与关闭路径不变量Invariantsspan 父子关系、遥测默认关闭路径、遥测不改变行为、后端故障不影响运行、payload 长度上限、属性模式一致性、无重复或泄漏 span核心架构SequentialWorkflow、ConcurrentWorkflow、AgentRearrange、RoundRobinSwarm、MixtureOfAgents、MajorityVoting、BatchedGridWorkflow、SwarmRouter高级架构HierarchicalSwarm、MultiAgentRouter、GraphWorkflow、GroupChat、DebateWithJudge、CouncilAsAJudge、LLMCouncil、HeavySwarm、PlannerWorkerSwarm。测试全部离线运行LLM 调用由FakeLLM充当遥测端点被指向本地死地址保证 span 不出本机唯一例外是TestRealLLMRuns它仅在存在 provider key 时才执行。这从测试层面印证了文档所述“track agent performance, log operations, and monitor agent behavior”的完整闭环。实践小结如何在自己的 Agent 中使用遥测结合以上源码落地到自己的项目可以按以下步骤进行安装依赖确保已安装opentelemetry-sdk与opentelemetry-exporter-otlp-proto-httpotel.py顶部导入它们缺少时 telemetry 会静默失效而非报错决定开关默认是开启的若要在生产环境关闭在.env或启动环境中设置SWARMS_TELEMETRY_ONfalse开箱即用直接使用 swarms 的Agent与各类 Swarm——Agent.run已被trace_run装饰SequentialWorkflow等组件构造时已调用capture_init基础链路与配置快照会自动上报自定义埋点对自定义方法用trace_run(MyClass.run)装饰或在方法体内用with capture_run(...) as span:手动包裹必要时调用span.set/record_output处理被吞异常在捕获异常且不重新抛出的位置调用capture_error(e, self, ...)避免错误静默丢失配置导出参数按需调整SWARMS_OTEL_MAX_CHARS、SWARMS_OTEL_MAX_CONFIG_CHARS、SWARMS_OTEL_TIMEOUT并设置OTEL_SERVICE_NAME为你的服务名。需要说明的是examples/utils/telemetry/README.md是对遥测示例目录的引导性说明更完整的可直接运行示例与底层实现证据分布在 swarms/telemetry 源码、各架构实现与 tests/telemetry/test_telemetry.py 中配合阅读可获得从埋点到导出的完整认识。【免费下载链接】swarmsThe Enterprise-Grade Multi-Agent Orchestration Framework. Website: https://swarms.ai项目地址: https://gitcode.com/GitHub_Trending/swar/swarms创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考