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.
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}OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 cargo run --bin apiThat 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.
Option by option
Section titled “Option by option”In @nestjs/observe | In NestRS |
|---|---|
createObserveModule(), ObserveModule.forRoot(...), instrument:, enableShutdownHooks() | let _otel = OpenTelemetry::init()?;, the first line of main (OpenTelemetry) |
appKey, appSecret, endpoint | OTEL_EXPORTER_OTLP_ENDPOINT, and a credential your backend asks for in OTEL_EXPORTER_OTLP_HEADERS (configuration) |
serviceId, serviceVersion | the binary’s package name and version; OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES override them |
tracesSampleRate | OTEL_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 / getAttribute | a 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 / summary | Metrics::counter / up_down_counter or gauge / histogram, on an injected Arc<Metrics> (metrics) |
x-request-id | traceparent, continued from a trusted proxy and sent on every request the framework or ReqwestMiddleware sends, and traceresponse on the answer (correlation) |
forwardLogs | the OpenTelemetry logs bridge, on once an endpoint is set (logs) |
redaction | a secret is a nest_rs::core::Secret, which prints <redacted>, and no line quotes a value |
outbound fetch and node:http spans | ReqwestMiddleware on your own reqwest client (calling another service) |
enabled: false in tests | nothing: a suite boots the module and never runs main, so it exports nothing (tests) |
http.tags | OTEL_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.queryParamsObfuscateRegex | nothing 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.ignore | nothing 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, alerts | your backend’s, computed from http.server.request.duration (metrics) |
What you will not find
Section titled “What you will not find”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.
Limits
Section titled “Limits”- The left column reads
@nestjs/observe0.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.
Going further
Section titled “Going further”- OpenTelemetry — the one line, its guard, and what each signal carries.
- Correlation — the trace context underneath, which waits on no crate.
- What runs differently — the rest of the machine underneath.