Skip to main content

OtelOptions

Defined in: src/otel/config.ts:135

OpenTelemetry configuration for JetstreamModule.forRoot({ otel: … }). All fields are optional; when the host app has not registered an OTel SDK, every call made by the library is a no-op regardless of config.

Properties​

captureBody?​

readonly optional captureBody?: boolean | CaptureBodyOptions

Defined in: src/otel/config.ts:192

Capture the message payload as the messaging.nats.message.body span attribute. Defaults to false for privacy and cost reasons.

Passing true captures up to 4 KiB per message. Use the object form for finer control over size and subject scope.

SECURITY / GDPR: payloads commonly contain PII, credentials, financial data, or content regulated by HIPAA / PCI-DSS. Enabling body capture in production is almost always a policy violation. Prefer enabling only in development, or pair with a custom SpanProcessor that scrubs or drops the attribute before export.

Default​

false

captureHeaders?​

readonly optional captureHeaders?: boolean | readonly string[]

Defined in: src/otel/config.ts:175

Header names to capture as span attributes (messaging.header.<name>). Match is case-insensitive. Glob wildcards (*) and negation (!prefix-*) are supported in the per-pattern form.

SECURITY / GDPR: headers may contain authentication tokens, session identifiers, or other sensitive data. Captured values are exported to the configured OTel backend. Use an explicit allowlist in production. Setting this to true captures every header and is intended for development environments only.

Transport-internal headers (x-correlation-id, x-reply-to, x-error, x-subject, x-caller-name) and propagator-owned headers (traceparent, tracestate, baggage, sentry-trace, b3, …) are always suppressed regardless of the allowlist.

Default​

['x-request-id']

enabled?​

readonly optional enabled?: boolean

Defined in: src/otel/config.ts:142

Global kill switch. When false, no spans are emitted, no propagation is attempted, and no hooks fire.

Default​

true

traces?​

readonly optional traces?: "all" | readonly JetstreamTrace[] | "default" | "none"

Defined in: src/otel/config.ts:155

Which trace kinds to emit.

  • 'default' — publish, consume, RPC client round-trip, dead letter
  • 'all' — every trace kind defined in JetstreamTrace
  • 'none' — emit no spans at all (useful with enabled: true for pure trace-context propagation without the span overhead)
  • JetstreamTrace[] — explicit selection

Default​

'default'

Methods​

consumeHook()?​

optional consumeHook(span, ctx): void

Defined in: src/otel/config.ts:207

Invoked after a consume span has been started and before the handler is dispatched. Use to enrich the span with custom attributes derived from the incoming message or handler metadata.

Parameters​

span​

Span

ctx​

JetstreamConsumeContext

Returns​

void

errorClassifier()?​

optional errorClassifier(err): ErrorClassification

Defined in: src/otel/config.ts:256

Classify a thrown error as 'expected' (business error, part of the RPC contract) or 'unexpected' (infrastructure failure or bug). Drives OpenTelemetry span status and attributes only.

  • 'expected' → span status OK with jetstream.rpc.reply.has_error and jetstream.rpc.reply.error.code attributes
  • 'unexpected' → span status ERROR with span.recordException(err)

Reply envelopes delivered to RPC clients are identical in both cases. This classification affects only the observability artifact.

The default recognizes NestJS-idiomatic primitives for business errors: RpcException and HttpException. Teams with custom error hierarchies override to recognize their own types.

Parameters​

err​

unknown

Returns​

ErrorClassification

Example​

errorClassifier: (err) => {
    if (err instanceof MyDomainError) return 'expected';
    if (err?.code?.startsWith('BIZ_')) return 'expected';
    return 'unexpected';
  }

publishHook()?​

optional publishHook(span, ctx): void

Defined in: src/otel/config.ts:200

Invoked after a publish span has been started and before the actual publish call executes. Use to enrich the span with custom attributes. Must be synchronous — thrown errors are caught and logged at debug level without affecting the publish path.

Parameters​

span​

Span

ctx​

JetstreamPublishContext

Returns​

void

responseHook()?​

optional responseHook(span, ctx): void

Defined in: src/otel/config.ts:214

Invoked once an operation's outcome is known (success, error, or timeout) and the span status has been set, just before the span ends. Fires for publish, consume, and RPC client spans.

Parameters​

span​

Span

ctx​

JetstreamResponseContext

Returns​

void

shouldTraceConsume()?​

optional shouldTraceConsume(subject, msg): boolean

Defined in: src/otel/config.ts:231

Predicate evaluated at the top of every incoming message delivery. Returning false skips span creation for that delivery; the handler still executes normally and trace context is still extracted from headers for downstream calls.

Parameters​

subject​

string

msg​

ConsumeSourceMsg

Returns​

boolean

shouldTracePublish()?​

optional shouldTracePublish(subject, record): boolean

Defined in: src/otel/config.ts:223

Predicate evaluated at the top of every outgoing publish. Returning false skips span creation for that publish; propagation of trace context through headers still occurs, so downstream consumers are unaffected. Useful for suppressing noise from health-check or internal-only subjects.

Parameters​

subject​

string

record​

JetstreamRecord

Returns​

boolean