Learn
Short, plain explanations of the ideas behind tracing AI agents that move money on-chain. Each page answers one question first, then shows where it appears in a trace.
Start here
What is a span?
One timed operation, such as a tool call or a transaction send, with a name, a start, an end and attributes.
What is a trace?
The tree of spans for one request or agent run. Child spans nest under the operation that caused them.
Agentic era
OpenTelemetry for AI agents, one idea per page: spans, attributes, context, sampling and export, each shown on a real agent run.
Traces and spans: the anatomy of one agent runOpenTelemetry span vs trace on one real AI agent run: what a span is, how trace IDs and span IDs differ, and how parent IDs build the tree.Span attributes: putting the tx hash on the spanOpenTelemetry span attributes explained with an agent's transaction: key and value rules, the allowed types, and why fees in wei go in as strings.Span status: when is a span an error?OpenTelemetry span status codes Unset, Error and Ok, shown on an agent's reverted transaction: when to set Error, why success stays Unset, and error.type.Span events vs logsOpenTelemetry span event vs log: what a span event is, how exceptions are recorded on spans, and why OpenTelemetry is moving events to the Logs API.Span kind: client, server, internalOpenTelemetry span kind explained on one agent trace: client vs internal, server, producer and consumer, and why a transaction send is a CLIENT span.Span links: connecting spans that aren't parent and childOpenTelemetry span links with an example: link a transaction's confirm span to its send span, even when the receipt arrives in another trace.Context propagation in async Node.jsOpenTelemetry context propagation in Node.js: how the active span survives await, what breaks without a context manager, and the traceparent header.Baggage vs span attributesOpenTelemetry baggage vs attributes, with an agent ID as the example: what travels to other services, what lands on spans, and what to keep private.Resource attributes: who emitted this span?OpenTelemetry resource attributes and service.name for an AI agent: what belongs on the resource, what on the span, and why env vars get ignored.Semantic conventions: shared names for spans and attributesWhat OpenTelemetry semantic conventions are, what Development and Stable mean, and why a blockchain library picks its own namespace while none exists.Sampling without losing the spans that moved moneyAn OpenTelemetry sampling strategy for agents that move money: head vs tail sampling, what a 10% sampling rate drops, and a policy that keeps reverts.Exporters and OTLP: getting spans to Jaeger or LangfuseThe OpenTelemetry OTLP exporter in a TypeScript Node.js example: send agent spans to Jaeger or Langfuse, and why spans vanish without shutdown.
Blockchain era
What happens to a transaction after an agent sends it: the lifecycle, fees, reverts and replaced transactions.
Transaction lifecycle: send, mempool, confirmWhat happens between sending an EVM transaction and knowing whether it worked: the hash, the pending pool, the block and the receipt.What is the L1 data fee?On OP Stack chains like Base, every transaction also pays to publish its data to Ethereum. What that fee is, why agents should care and where to see it.
Glossary
- x402
- Agentic payments
- Agent identity
- GenAI semantic conventions
- Span
- Trace
- Transaction hash
- Mempool
- Receipt
- Nonce
- Replaced transaction
- Gas
- Effective gas price
- L1 data fee
- OP Stack
- Revert reason
- ERC-4337
- User operation