Skip to main content

otel-instrumentation-nats

OpenTelemetry auto-instrumentation for nats-py.

Automatically creates spans for NATS publish, subscribe, request-reply, and JetStream operations with distributed trace context propagation through message headers.

Installation

pip install otel-instrumentation-nats

Or with uv:

uv add otel-instrumentation-nats

The instrumented library (nats-py) is an optional dependency. Install it separately if you haven't already:

pip install nats-py

Quick Start

import asyncio
import nats
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

from otel_instrumentation_nats import NatsInstrumentor

async def main():
    # Set up OpenTelemetry
    provider = TracerProvider()
    provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
    trace.set_tracer_provider(provider)

    # Instrument nats-py -- call this before using the NATS client
    NatsInstrumentor().instrument()

    nc = await nats.connect("nats://localhost:4222")

    # This publish creates a PRODUCER span and injects
    # trace context into the message headers automatically
    await nc.publish("orders.new", b'{"item": "widget"}')

    await nc.close()

asyncio.run(main())

What Gets Instrumented

Method Span Kind Span Name Description
Client.publish() PRODUCER {subject} send Fire-and-forget publish
Client.subscribe() CONSUMER {subject} receive Per-message spans for both callback and next_msg() patterns
Client.request() CLIENT {subject} request Request-reply (waits for response)
JetStreamContext.publish() PRODUCER {subject} send JetStream publish with stream attributes

Span Attributes

All spans include standard OpenTelemetry messaging semantic conventions:

Attribute Value
messaging.system nats
messaging.destination.name NATS subject (e.g. orders.new)
messaging.operation publish, receive, or request
server.address NATS server hostname
server.port NATS server port

JetStream publish spans additionally include:

Attribute Value
messaging.destination.kind stream
messaging.destination.stream Stream name (when specified)

Trace Context Propagation

Trace context is automatically propagated through NATS message headers using the W3C TraceContext format. This means:

  • Publishers inject traceparent and tracestate into message headers
  • Subscribers extract trace context from incoming message headers and create child spans

This links producer and consumer spans into a single distributed trace, even across service boundaries.

Service A                          NATS                          Service B
─────────                          ────                          ─────────
publish("orders.new")  ──────►  message with  ──────►  subscribe callback
  │                             traceparent header        │
  ▼                                                       ▼
[PRODUCER span]                                    [CONSUMER span]
  trace_id: abc123                                   trace_id: abc123
  span_id:  def456                                   parent_id: def456

Usage Patterns

Publish/Subscribe with Callback

NatsInstrumentor().instrument()

nc = await nats.connect()

async def on_message(msg):
    # A CONSUMER span is active here, linked to the producer trace
    print(f"Got {msg.data} on {msg.subject}")

await nc.subscribe("events.>", cb=on_message)
await nc.publish("events.click", b"data")  # Creates a PRODUCER span

Subscribe with next_msg() (Pull Pattern)

sub = await nc.subscribe("tasks")
await nc.publish("tasks", b"do-something")

msg = await sub.next_msg(timeout=5.0)  # Creates a CONSUMER span

Request-Reply

async def handler(msg):
    await msg.respond(b"pong")

await nc.subscribe("ping", cb=handler)

# Creates a CLIENT span that encompasses the full request-reply cycle
response = await nc.request("ping", b"data", timeout=2.0)

JetStream

js = nc.jetstream()

await js.add_stream(name="ORDERS", subjects=["orders.>"])

# Creates a PRODUCER span with stream attributes
await js.publish("orders.new", b"order-data", stream="ORDERS")

# Subscribe callback receives CONSUMER spans linked to the producer
async def process_order(msg):
    await msg.ack()

await js.subscribe("orders.new", cb=process_order, manual_ack=True)

Custom Tracer Provider

from opentelemetry.sdk.trace import TracerProvider

provider = TracerProvider()
# ... configure your provider with exporters, processors, etc.

NatsInstrumentor().instrument(tracer_provider=provider)

Uninstrumenting

instrumentor = NatsInstrumentor()
instrumentor.instrument()

# ... later, to restore original behavior:
instrumentor.uninstrument()

Development

Prerequisites

  • Python 3.13+
  • uv
  • Docker (for integration tests)

Setup

git clone <repo-url>
cd otel-instrumentation-nats
uv sync --extra instruments --extra test

Running Tests

Start a NATS server (or use the included docker-compose):

docker compose up -d

Run the full test suite:

uv run pytest -v

Run only unit tests (no NATS server required):

uv run pytest tests/test_instrumentor.py tests/test_context_propagation.py -v

Run only integration tests:

uv run pytest -m integration -v

Project Structure

src/otel_instrumentation_nats/
├── __init__.py               # Public API
├── instrumentor.py           # NatsInstrumentor (patches/restores methods)
├── publish_wrapper.py        # Client.publish() -> PRODUCER spans
├── subscribe_wrapper.py      # Client.subscribe() -> CONSUMER spans
├── request_wrapper.py        # Client.request() -> CLIENT spans
├── jetstream_wrapper.py      # JetStreamContext.publish() -> PRODUCER spans
├── context_propagation.py    # Trace context inject/extract via NATS headers
├── utils.py                  # Shared span building, nested suppression
├── version.py                # Package version
└── package.py                # Instrumented library version constraints

Metadata

Release files for otel-instrumentation-nats 0.1.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for otel-instrumentation-nats 0.1.5
File Size Uploaded Provenance Actions
otel_instrumentation_nats-0.1.5.tar.gz 39.9 kB Without provenance Details for otel_instrumentation_nats-0.1.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for otel-instrumentation-nats 0.1.5
File Interpreter ABI Platform Actions
otel_instrumentation_nats-0.1.5-py3-none-any.whl Python 3 none any Details for otel_instrumentation_nats-0.1.5-py3-none-any.whl

Total release size: 52.9 kB

Release files / otel_instrumentation_nats-0.1.5.tar.gz

Download URL otel_instrumentation_nats-0.1.5.tar.gz
Size 39.9 kB
Tags Source
SHA-256 checksum
How to use checksums
73d75d82470774856cbb104ca0b202fac5e9a38967507c0cb7b91b93ebc335af
BLAKE2b-256 checksum
How to use checksums
f4cc72602b848dd6d736b98c371b731ab3a5119daa4de242cfefbf28d7120a09
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / otel_instrumentation_nats-0.1.5-py3-none-any.whl

Download URL otel_instrumentation_nats-0.1.5-py3-none-any.whl
Size 12.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
59e44f229e30cffab9ef789d45580e750420f5931bc1be3452e16f140c40f85b
BLAKE2b-256 checksum
How to use checksums
9dd26d5ed639b911a676fccb2b8440786723344da2017fed424b4d02c9c50af8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for otel-instrumentation-nats 0.1.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.5 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page