TraceBehaviorOptions

Defined in: trace.behavior.ts:42

Per-handler tracing options for TraceBehavior.

Example

Service-specific tracing

@UsePipeline([TraceBehavior, {
  tracerName: 'users-api',
  spanName: (ctx) => `${ctx.requestKind}.${ctx.requestName}`,
  attributeFactory: (ctx) => ({
    'app.tenant': ctx.tenantId ?? 'unknown',
  }),
}])
export class GetUserHandler {}

Properties

attributeFactory?

optional attributeFactory?: PipelineTelemetryAttributeFactory

Defined in: trace.behavior.ts:93

Additional request-aware span attributes. The factory may be synchronous or asynchronous; failures are ignored so observability cannot replace the business result/error.

Prefer bounded semantic values (tenant tier, feature name, operation type) rather than full request payloads or secrets.

Example

@UsePipeline([TraceBehavior, {
  attributeFactory: (ctx) => ({
    'app.tenant.tier': ctx.items.get('tenantTier') as string,
    'app.region': process.env.REGION ?? 'unknown',
  }),
}])

---

enabled?

optional enabled?: boolean

Defined in: trace.behavior.ts:57

Explicitly disable tracing for this handler without removing the behavior. Useful when the behavior is registered globally but a hot/noisy handler should not create its own pipeline span.

Default

true

---

includeContextAttributes?

optional includeContextAttributes?: boolean

Defined in: trace.behavior.ts:117

Apply request-local attributes accumulated through addPipelineTelemetryAttributes to the span. Attributes written by downstream behaviors/handler are applied again after execution so late enrichment is visible on the final span.

Span attributes may legitimately contain request-local identifiers such as correlation ID because traces are already request-scoped. Metric labels use a stricter cardinality policy; see MetricsBehaviorOptions.

Default

true

---

recordException?

optional recordException?: boolean

Defined in: trace.behavior.ts:103

Record thrown exceptions on the active span.

Disable when another instrumentation layer already records the same exception and you want to avoid duplicate exception events.

Default

true

---

spanName?

optional spanName?: string | ((context) => string)

Defined in: trace.behavior.ts:73

Custom span name or request-aware span-name factory.

The default span name is {requestKind}.{requestName}, e.g. query.GetUserQuery. If a factory throws or returns an empty string, the default name is used so telemetry enrichment cannot break the request.

Example

@UsePipeline([TraceBehavior, {
  spanName: (ctx) => `application.${ctx.requestName}`,
}])

---

tracerName?

optional tracerName?: string

Defined in: trace.behavior.ts:48

Name of the OpenTelemetry tracer used to create spans.

Default

'nestjs-pipeline'