Telemetry

Overview

Swarms ships with OpenTelemetry tracing, enabled by default. 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. Spans are exported over OTLP/HTTP to the Swarms telemetry collector (https://swarms-telemetry-capturer-production.up.railway.app/v1/traces). The endpoint is fixed in the source: the standard OTEL_EXPORTER_OTLP_* endpoint variables do not redirect it. To also send spans to your own backend, see Sending spans to your own backend.

Turning it on and off

Telemetry is controlled by a single environment variable, SWARMS_TELEMETRY_ON. Telemetry is on by default. It must be switched off explicitly — leaving the variable unset leaves it enabled.

export SWARMS_TELEMETRY_ON=false

# Unset, or any value that is not a recognized off value
unset SWARMS_TELEMETRY_ON

SWARMS_TELEMETRY_ON="false"

Recognized off values, case-insensitive and whitespace-tolerant: false, 0, no, off, disable, disabled. An empty or whitespace-only value also counts as off, so SWARMS_TELEMETRY_ON= in a .env file disables telemetry rather than silently enabling it. Anything else — true, 1, yes, or an unrecognized string — leaves it on.

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 is loaded automatically on import. Swarms searches upward from the current working directory for the first .env it finds. Values already set in your shell take precedence over the file. If telemetry appears to be on when you expected it off, check both.

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 (opt out)	~0.14 µs	One cached lookup and a boolean check, then straight through
On (default), small payload	~22 µs	Span creation, attributes, context attach
On (default), ~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>.<method>`	Other traced entry points: `SpreadSheetSwarm.run_from_config`, `AutoAgentBuilder.build_configs`	same as a run span
`<Component>.error` and named error spans	An error is caught and not re-raised: `Agent.llm_error` (a failed LLM attempt inside the retry loop), `Agent.tool_error` (a tool batch that failed after `tool_retry_attempts`), `ConcurrentWorkflow.agent_error` (an agent failure swallowed under `on_error`)	error type, message, context such as `swarms.loop` or `swarms.agent`
`swarms.state`	`autosave=True` on an `Agent` or `AgentRearrange`, at the points where state is saved	`swarms.state` — the component’s `to_dict()` snapshot as JSON

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

Each of these classes emits an init span from its constructor and a span for every call to the entry point listed:

Agents

Agent (run)

Workflows

SequentialWorkflow, ConcurrentWorkflow, AgentRearrange, GraphWorkflow, BatchedGridWorkflow, RoundRobinSwarm (run); SpreadSheetSwarm (run and run_from_config)

Orchestrators

SwarmRouter, HierarchicalSwarm, MultiAgentRouter, PlannerWorkerSwarm, MixtureOfAgents, ModelRouter, SocialAlgorithms (run)

Deliberation

MajorityVoting, CouncilAsAJudge, DebateWithJudge, GroupChat, LLMCouncil, HeavySwarm, SelfMoASeq (run)

Builders

AutoSwarmBuilder (run); AutoAgentBuilder (build_configs, which run calls)

Decision models

DecisionModel (run, capturing the state input)

AutoSwarmBuilder.run is the parent of the SwarmRouter.run it delegates to, so the build phase and the swarm it builds share one trace. ModelRouter dispatches through ContextThreadPoolExecutor, so its agents nest under the router’s span. Classes not in this list, such as ReasoningDuo or TreeOfThoughts, emit no spans of their own. Their inner Agent.run calls are still traced.

Configuration reference

Variable	Default	Purpose
`SWARMS_TELEMETRY_ON`	unset (on)	Master switch; set to `false` to opt out
`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

The OTLP endpoint is not configurable through environment variables. Spans go to the Swarms collector whenever telemetry is on.

Sending spans to your own backend

The tracer provider is an ordinary OpenTelemetry TracerProvider, so you can attach another span processor to it. Your exporter receives every span in addition to the Swarms collector:

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from swarms.telemetry.otel import swarm_telemetry

telemetry = swarm_telemetry()
if telemetry.ready:
    telemetry._provider.add_span_processor(
        BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces"))
    )

_provider is a private attribute, and adding a processor does not remove the built-in exporter. If you need spans to reach only your own backend, this is not supported: set SWARMS_TELEMETRY_ON=false and instrument your application with your own tracer instead.

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. With autosave=True, it also captures Agent and AgentRearrange state snapshots. All of it is sent to the Swarms telemetry collector described in the overview. Because it is on by default, opt out explicitly if any of that is sensitive in your deployment:

export SWARMS_TELEMETRY_ON=false

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

Builders

Decision models

Configuration reference

Sending spans to your own backend

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

Builders

Decision models

​Configuration reference

​Sending spans to your own backend

​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

Sending spans to your own backend

Instrumenting your own components

The decorator

Inline spans

Errors you swallow

Threads

Capturing spans in tests

Privacy