Telemetry

Overview

Swarms ships with optional OpenTelemetry tracing. When enabled, every agent and swarm run emits a span recording what was asked, what came back, how long it took, and whether it failed — and those spans nest, so a swarm run and every agent run underneath it form a single connected trace. Telemetry is fail-safe by design: if the exporter is unreachable, the configuration is wrong, or the dependency is missing, the instance goes inert and your agents keep running. It never raises into your code.

Turning it on and off

Telemetry is controlled by a single environment variable, SWARMS_TELEMETRY_ON.

# Unset, or any value other than the three below
unset SWARMS_TELEMETRY_ON

export SWARMS_TELEMETRY_ON=true

SWARMS_TELEMETRY_ON="true"

Accepted “on” values are exactly "True", "true", and "1". Anything else — including "yes", "TRUE", or an empty string — is off.

The gate is read once per process, at first use. Changing SWARMS_TELEMETRY_ON at runtime has no effect until you restart. This is deliberate: it keeps the hot path to a single cached lookup.

A .env file in your working directory is loaded automatically on import. If telemetry appears to be on when you expected it off, check .env before checking your shell — the file populates the variable before the gate is read.

Verifying the current state

from swarms.telemetry.otel import swarm_telemetry, telemetry_on

print(telemetry_on())              # what the env gate says
print(swarm_telemetry().ready)     # whether the tracer actually initialized

ready can be False even when telemetry_on() is True — that means setup failed and telemetry silently disabled itself. Run with loguru at DEBUG level to see why.

Performance cost

Measured overhead per decorated call:

State	Overhead per `run()`	Notes
Off	~0.14 µs	One cached lookup and a boolean check, then straight through
On, small payload	~22 µs	Span creation, attributes, context attach
On, ~48 KB output	~100 µs	Cost scales with payload size, not span machinery

Every one of those numbers is dwarfed by a single LLM round trip (200 ms – several seconds). Even the worst case is roughly 0.05% of a 200 ms call. Span export happens on a background thread via BatchSpanProcessor, so the network is never on your hot path. The dominant cost when enabled is stringifying inputs and outputs for the span. Payloads are truncated to 16,000 characters (SWARMS_OTEL_MAX_CHARS), and captured constructor configs to 65,536 (SWARMS_OTEL_MAX_CONFIG_CHARS).

What gets captured

Spans

Span	Emitted when	Key attributes
`<Component>.init`	A component is constructed	`swarms.config` — the full constructor configuration as JSON
`<Component>.run`	`run()` is called	inputs, output, status, identity
`<Component>.error`	An error is caught and not re-raised	error type, message, context

Every span carries identity attributes:

Attribute	Meaning
`swarms.component`	Class name — `Agent`, `SwarmRouter`, `ConcurrentWorkflow`, …
`swarms.name`	The agent’s `agent_name` or the swarm’s `name`
`swarms.id`	The component’s `id`
`swarms.swarm_type`	Present on multi-agent structures only, never on a single `Agent`
`gen_ai.operation.name`	`"agent"` for a single agent, `"swarm"` for everything else

And run spans add:

Attribute	Meaning
`swarms.input.task`	The task passed in (also `.tasks`, `.img`, `.imgs` where applicable)
`swarms.output`	The return value, truncated
`swarms.status`	`completed` or `error`
`swarms.error.type` / `swarms.error.message`	Present on failures

Trace structure

Spans nest, including across the thread pools that concurrent swarms use:

SwarmRouter.run
└─ ConcurrentWorkflow.run
   ├─ Agent.run          (worker thread)
   └─ Agent.run          (worker thread)

One trace, one root, every agent attributable to the run that spawned it.

SequentialWorkflow delegates internally to AgentRearrange, so a sequential run shows an extra AgentRearrange.run span between the workflow and its agents. That is the real call path, not a duplicate.

Instrumented components

Every multi-agent harness and the Agent class itself:

Agents

Agent

Workflows

SequentialWorkflow, ConcurrentWorkflow, AgentRearrange, GraphWorkflow, BatchedGridWorkflow, RoundRobinSwarm

Orchestrators

SwarmRouter, HierarchicalSwarm, MultiAgentRouter, PlannerWorkerSwarm, MixtureOfAgents

Deliberation

MajorityVoting, CouncilAsAJudge, DebateWithJudge, GroupChat, LLMCouncil, HeavySwarm

Configuration reference

Variable	Default	Purpose
`SWARMS_TELEMETRY_ON`	unset (off)	Master on/off switch
`OTEL_SERVICE_NAME`	`swarms`	Service name attached to every span
`SWARMS_OTEL_TIMEOUT`	`8`	Export timeout in seconds
`SWARMS_OTEL_MAX_CHARS`	`16000`	Max characters per input/output attribute
`SWARMS_OTEL_MAX_CONFIG_CHARS`	`65536`	Max characters for a captured `init` config

Instrumenting your own components

The same primitives are available for custom structures.

The decorator

from swarms.telemetry.otel import capture_init, trace_run

class MySwarm:
    def __init__(self, agents, name="MySwarm"):
        self.agents = agents
        self.name = name
        capture_init(self)          # emits MySwarm.init with the full config

    @trace_run("MySwarm.run", input_params=("task", "img"))
    def run(self, task=None, img=None):
        ...                          # output and errors recorded automatically

trace_run opens the span, captures the named parameters, records the return value on success, and records any exception that propagates before re-raising it unchanged. You never need to touch the span yourself.

Inline spans

When you need to attach extra attributes mid-run:

from swarms.telemetry.otel import capture_run

with capture_run("MySwarm.run", self, task=task) as span:
    result = do_work()
    span.set("myswarm.rounds", 3)
    span.record_output(result)

Errors you swallow

trace_run and capture_run only see exceptions that propagate. For errors you catch and handle, record them explicitly:

from swarms.telemetry.otel import capture_error

try:
    result = agent.run(task)
except Exception as e:
    capture_error(e, self, agent=agent.agent_name)
    result = None       # swallowed to keep the swarm going

Threads

OpenTelemetry’s active-span context does not cross thread boundaries. If you dispatch agents to a pool, use the drop-in executor so their spans nest under the run that spawned them:

from swarms.telemetry.otel import ContextThreadPoolExecutor

with ContextThreadPoolExecutor(max_workers=8) as executor:
    futures = [executor.submit(agent.run, task) for agent in self.agents]

A plain ThreadPoolExecutor still works — the agents just show up as disconnected root traces instead of children.

Capturing spans in tests

Point the tracer at an in-memory exporter instead of the network:

import os
os.environ["SWARMS_TELEMETRY_ON"] = "true"

import swarms.telemetry.otel as otel
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter

otel.TELEMETRY_BASE_URL = "http://127.0.0.1:9/dead"   # nothing leaves the machine
otel.swarm_telemetry.cache_clear()                    # rebuild with the new gate

telemetry = otel.swarm_telemetry()
memory = InMemorySpanExporter()
telemetry._provider.add_span_processor(SimpleSpanProcessor(memory))

agent.run("hello")

spans = memory.get_finished_spans()
run_span = next(s for s in spans if s.name == "Agent.run")
assert dict(run_span.attributes)["swarms.status"] == "completed"

swarm_telemetry.cache_clear() is the important line — without it you get the singleton built under the previous gate value.

Privacy

Telemetry captures task text, agent outputs, and constructor configuration — including system prompts, which may contain proprietary instructions. If that matters for your deployment, leave SWARMS_TELEMETRY_ON unset. There is no partial mode: it is entirely on or entirely off.

Getting Started

Core Concepts

Agent Development

Reasoning Agents

Multi-Agent Architectures

Deployment & Operations

Integrations

CLI Reference

Changelog

Overview

Turning it on and off

Verifying the current state

Performance cost

What gets captured

Spans

Trace structure

Instrumented components

Agents

Workflows

Orchestrators

Deliberation

Configuration reference

Instrumenting your own components

The decorator

Inline spans

Errors you swallow

Threads

Capturing spans in tests

Privacy

​Overview

​Turning it on and off

​Verifying the current state

​Performance cost

​What gets captured

​Spans

​Trace structure

​Instrumented components

Agents

Workflows

Orchestrators

Deliberation

​Configuration reference

​Instrumenting your own components

​The decorator

​Inline spans

​Errors you swallow

​Threads

​Capturing spans in tests

​Privacy

Overview

Turning it on and off

Verifying the current state

Performance cost

What gets captured

Spans

Trace structure

Instrumented components

Configuration reference

Instrumenting your own components

The decorator

Inline spans

Errors you swallow

Threads

Capturing spans in tests

Privacy