# For OpenTelemetry engineers

> What hashspan adds to an OpenTelemetry setup, in one page: spans and metrics, schema status, overhead, the Collector, and six blockchain words you'll meet.

Source: https://hashspan.dev/docs/otel-engineers

You know OpenTelemetry. This page gives you hashspan in OTel terms, and the few blockchain words its spans use.

## What does it add to my traces?

A library, not a service: it uses your SDK, your exporter and your backend. Inside whatever span is active, such as a tool call, it records:

| Span | Kind | Ends when |
|---|---|---|
| `send {blockchain.chain.id}` | CLIENT | the node returns a transaction hash, or the send fails |
| `confirm {blockchain.chain.id}` | CLIENT | the receipt arrives, or a timeout or error; linked to `send` or `payment` |
| `payment {blockchain.chain.id}` | CLIENT | a paid request settles or fails (x402, MPP) |

It also records histograms for send duration, confirmation duration and fees, for every transaction, whatever a sampler decides. Span names stay low-cardinality: the chain id, never a hash.

## Is the schema stable?

Not yet. Every attribute is marked development, in schema `0.5.0-dev` ([semantic conventions](https://hashspan.dev/docs/reference/semantic-conventions)).

OpenTelemetry has no blockchain conventions, and had no open proposal when hashspan started ([ADR 0003](https://github.com/selimaytac/hashspan/blob/main/docs/adr/0003-attribute-namespace.md)). So hashspan uses its own `blockchain.*` namespace, shaped like `db.*` and `rpc.*`. Where upstream names exist it reuses them: `error.type`, `rpc.*`, `jsonrpc.*` and `gen_ai.agent.*`. The plan is to propose the schema upstream once it has real users. Renames follow a written change policy. The one rename so far records both names, and drops the old one at 1.0.

## What does it cost?

On a local chain, a traced send plus receipt took 0.25 to 0.5 ms more at p50 than plain viem. Tracing can add JSON-RPC requests: one for a transfer where viem picks the nonce, three for a reverted transaction. The [tracing overhead benchmark](https://hashspan.dev/docs/benchmarks/tracing-overhead) has the method and every number.

## How do I run it in production?

- **Sampling:** keep head sampling at 100% and decide in a Collector. A reverted transaction only shows on the `confirm` span, which can end after the Collector decides. A policy on `blockchain.*` keeps those traces: [Collector recipe](https://hashspan.dev/docs/recipes/collector), tested.
- **Privacy:** addresses are recorded by default, in lower case. Hash or drop them in the SDK or in the Collector. Calldata arguments and error messages are opt-in ([privacy](https://hashspan.dev/docs/reference/semantic-conventions#privacy)).
- **Backends:** any OTLP backend. [Backends](https://hashspan.dev/docs/backends) has dated notes for Jaeger, Grafana, Langfuse, Honeycomb and others.
- **Security and stability:** keys, defaults, vulnerability reports and what 1.0 keeps stable are on [one page](https://hashspan.dev/docs/security).
- **Short-lived processes:** call `flush()` before exit, or confirmations still open end as `timeout`.

## Which languages?

TypeScript on Node.js 22.3 or later, with viem, the Coinbase CDP SDK, x402 or MPP. There is no Go, Python or Java version.

Not on TypeScript? Much of it still applies, because it is plain OpenTelemetry:

- **The names:** the [semantic conventions](https://hashspan.dev/docs/reference/semantic-conventions) define the spans, attributes and metrics. You can record the same names from any OpenTelemetry SDK, such as Python's around web3.py.
- **The Collector:** the [Collector recipe](https://hashspan.dev/docs/recipes/collector) works on any spans that carry `blockchain.operation.name`.
- **Queries and dashboards:** the TraceQL queries on [Backends](https://hashspan.dev/docs/backends) and the [Grafana dashboards](https://github.com/selimaytac/hashspan/tree/main/dashboards) match on those names.

## Seven blockchain words you'll meet

| Word | Meaning |
|---|---|
| Transaction hash | The id of a sent transaction. Like a trace id: known at send, used to look it up later |
| Nonce | A per-account counter. Each transaction uses the next one, once |
| Gas | The work a transaction does, in units. Units times a price per unit is the fee |
| Receipt | The node's record that a transaction ran: block, gas used, success or reverted |
| Revert | The contract stopped on purpose and undid its changes. The fee is still paid |
| Wei | The smallest unit of ETH, 10^-18. Too big for int64, so hashspan records it as a decimal string |
| L1 data fee | On chains built on top of Ethereum, such as Base, a second fee for posting the transaction to Ethereum itself |

[Transaction lifecycle](https://hashspan.dev/learn/tx-lifecycle) walks a transaction from send to receipt. The [architecture](https://hashspan.dev/docs/architecture) page shows the packages and every extra request.

## Who maintains it?

An open-source project under Apache-2.0, maintained on [GitHub](https://github.com/selimaytac/hashspan). `@hashspan/viem` has had 23 releases since its first, on 2026-09-29. Releases are listed in the [changelog](https://hashspan.dev/changelog).