Skip to content

Telemetry, coming from @nestjs/observe

Where @nestjs/observe's options and every TracerService call land in NestRS: one line in main, the OpenTelemetry variables, and the backend you choose.

@nestjs/observe is the agent of NestJS’s hosted observability product: it reports to their backend under an app key. NestRS exports what it records to the OpenTelemetry backend you point it at, in the names the semantic conventions give, and has no hosted product of its own. This page maps the options you set, and every call TracerService offers, onto where each lands.

apps/api/src/main.rs
use anyhow::Result;
use nest_rs::core::App;
use nest_rs::opentelemetry::OpenTelemetry;
use api::ApiModule;
#[nest_rs::main]
async fn main() -> Result<()> {
let _otel = OpenTelemetry::init()?;
App::builder().module::<ApiModule>().build().await?.run().await
}
Terminal window
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 cargo run --bin api

That line replaces createObserveModule(), the instrument: option and enableShutdownHooks(): the guard init returns flushes what is still batched when main returns. Every request, job, tick and operation is then a span, and every line a log record, sent to the collector the variable names.

In @nestjs/observeIn NestRS
createObserveModule(), ObserveModule.forRoot(...), instrument:, enableShutdownHooks()let _otel = OpenTelemetry::init()?;, the first line of main (OpenTelemetry)
appKey, appSecret, endpointOTEL_EXPORTER_OTLP_ENDPOINT, and a credential your backend asks for in OTEL_EXPORTER_OTLP_HEADERS (configuration)
serviceId, serviceVersionthe binary’s package name and version; OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES override them
tracesSampleRateOTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG, parent-based (sampling)
tracer.createSpan(name, callback)#[tracing::instrument] on the function (custom spans)
tracer.activeSpan()tracing::Span::current()
tracer.captureError(error, tags?)return the error: its edge files the chain, and the unit’s span says why; for one you handle, tracing::error!(error = %nest_rs::core::error_message(&err), "…"), a log record and an event of the current span, which that error line marks Error, with no description, whatever the unit answers (a failed span says why)
tracer.setAttribute / getAttributea value a layer makes ambient with cx.attach(value), read anywhere the unit reaches with nest_rs::core::ambient::<T>() (execution context)
tracer.setOperationId(id)nothing: a unit is named by what the server declares — its route template, root field, event or tool — so its names stay bounded; another grouping is your backend’s query
tracer.currentTraceId()nest_rs::core::current_trace_id()
tracer.counter / gauge / summaryMetrics::counter / up_down_counter or gauge / histogram, on an injected Arc<Metrics> (metrics)
x-request-idtraceparent, continued from a trusted proxy and sent on every request the framework or ReqwestMiddleware sends, and traceresponse on the answer (correlation)
forwardLogsthe OpenTelemetry logs bridge, on once an endpoint is set (logs)
redactiona secret is a nest_rs::core::Secret, which prints <redacted>, and no line quotes a value
outbound fetch and node:http spansReqwestMiddleware on your own reqwest client (calling another service)
enabled: false in testsnothing: a suite boots the module and never runs main, so it exports nothing (tests)
http.tagsOTEL_RESOURCE_ATTRIBUTES, on every span, record and point the process exports
http.setAttributes(req)a field of your own on your own span, #[tracing::instrument(fields(...))]; the request’s span keeps the fields the HTTP conventions name, user_agent.original among them
http.getUserId(req)the authentication guard, which records the caller’s id as enduser.id on the unit’s span and actor_id on every line
http.queryParamsObfuscateRegexnothing to mask: a request’s span records url.path and never its query, and a request the app sends records its server, never its path or query
http.ignorenothing to list: a health probe’s trace starts unsampled and its healthy line files at debug (health); any other route is the sampler’s or the collector’s to drop
@Objective(), the dashboard, alertsyour backend’s, computed from http.server.request.duration (metrics)

The agent keeps a failed request’s inputs: its headers, from a default list with nothing that authenticates or identifies anyone, and its body once you turn that on, capped at 2 KB; a slow request too, once you set slowerThanMs (http.capture). NestRS captures no request’s headers or body: a request’s span keeps what the HTTP conventions name — its route, its path, its user agent — and nothing its body carried. Lines of source shipped with an error are your code leaving for a third party; a panic’s line carries panic_location instead. Scrubbing logs by pattern is replaced by holding secrets in a type that never prints them.

A span per guard, pipe or service method has no counterpart either. Write #[tracing::instrument] where you want to see inside a unit.

  • The left column reads @nestjs/observe 0.3.26.
  • A span of your own is exported where the console’s filter admits it (custom spans); the spans the framework opens are exported whatever the console writes.