# hashspan

> Trace your AI agents' on-chain transactions with OpenTelemetry. hashspan is an open-source OpenTelemetry library that records every transaction an AI agent sends as spans keyed by the transaction hash, inside the agent's own trace.

Packages: @hashspan/core, @hashspan/viem, @hashspan/cdp (npm, Apache-2.0). Source: https://github.com/selimaytac/hashspan

## Docs
- [Introduction](https://hashspan.dev/docs): hashspan records every on-chain transaction an AI agent sends as OpenTelemetry spans inside the agent's own trace.
- [Coinbase CDP](https://hashspan.dev/docs/adapters/cdp): Trace transactions sent by Coinbase CDP server accounts.
- [core](https://hashspan.dev/docs/adapters/core): The transaction lifecycle tracker behind every adapter, for instrumenting other send paths.
- [viem](https://hashspan.dev/docs/adapters/viem): Trace transactions sent through viem wallet and public clients with send and confirm spans.
- [x402](https://hashspan.dev/docs/adapters/x402): Trace x402 payments: a payment span for each paid request, and a confirm span for its settlement.
- [Tracing backends](https://hashspan.dev/docs/backends): Send hashspan spans to Jaeger, Grafana Tempo, Langfuse, Honeycomb or any OTLP backend.
- [Local lab](https://hashspan.dev/docs/local-lab): Run the example AI SDK agent against a local chain and see its transactions in Jaeger, with no API key.
- [Quickstart](https://hashspan.dev/docs/quickstart): Trace your first agent transaction with hashspan and viem.
- [Semantic conventions](https://hashspan.dev/docs/reference/semantic-conventions): The span names, attributes and status values hashspan records (draft).

## Learn
- [Traces and spans: the anatomy of one agent run](https://hashspan.dev/learn/otel-traces-and-spans): OpenTelemetry 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.
- [Transaction lifecycle: send, mempool, confirm](https://hashspan.dev/learn/tx-lifecycle): What happens between sending an EVM transaction and knowing whether it worked: the hash, the pending pool, the block and the receipt.
- [Span attributes: putting the tx hash on the span](https://hashspan.dev/learn/otel-span-attributes): OpenTelemetry span attributes explained with an agent's transaction: key and value rules, the allowed types, and why fees in wei go in as strings.
- [What is the L1 data fee?](https://hashspan.dev/learn/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.
- [Span status: when is a span an error?](https://hashspan.dev/learn/otel-span-status): 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 logs](https://hashspan.dev/learn/otel-span-events): OpenTelemetry 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, internal](https://hashspan.dev/learn/otel-span-kind): OpenTelemetry 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 child](https://hashspan.dev/learn/otel-span-links): OpenTelemetry 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.js](https://hashspan.dev/learn/otel-context-propagation): OpenTelemetry context propagation in Node.js: how the active span survives await, what breaks without a context manager, and the traceparent header.
- [Baggage vs span attributes](https://hashspan.dev/learn/otel-baggage): OpenTelemetry 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?](https://hashspan.dev/learn/otel-resource-attributes): 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 attributes](https://hashspan.dev/learn/otel-semantic-conventions): What 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 money](https://hashspan.dev/learn/otel-sampling): An 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 Langfuse](https://hashspan.dev/learn/otel-exporters-otlp): The OpenTelemetry OTLP exporter in a TypeScript Node.js example: send agent spans to Jaeger or Langfuse, and why spans vanish without shutdown.

## Blog
- [Your agent's trace stops at the tool call. Here's what happens next.](https://hashspan.dev/blog/agent-trace-stops-at-the-tool-call): AI agent observability with OpenTelemetry stops at the tool call. Here's how to put the transaction outcome (send, confirm, fees, reverts) in the same trace.

## Optional
- [Full docs as one file](https://hashspan.dev/llms-full.txt)
- [Changelog](https://hashspan.dev/changelog)