Skip to main content

Recipes

Trace a method with a decorator​

import { TelemetryDecorators } from '@quik/telemetry';
import { QObject } from '@quik/core';

class JobsService extends QObject {
  @TelemetryDecorators.Span('jobs.process')
  async process() {
    // do work
  }
}

TelemetryDecorators.Span(nameOrOptions?, options?) wraps the method call in a span, ending it (and recording any thrown error) automatically, for both sync and async methods. Omitting the name uses the method's own name.

Start and end a span manually​

import { endSpan, recordSpanError, setSpanAttribute, startSpan } from '@quik/telemetry';

const span = startSpan('jobs.run', { attributes: { jobId: '123' } });
try {
  // do work
  setSpanAttribute(span, 'success', true);
} catch (err) {
  recordSpanError(span, err);
  throw err;
} finally {
  endSpan(span);
}

startSpan/endSpan/recordSpanError/setSpanAttribute are no-ops when telemetry is disabled, so this pattern is safe to use unconditionally — this is the same helper set @quik/scheduler's QExecutor uses to trace task runs.

Use span helpers from a QObject subclass​

QObject (from @quik/core) exposes protected startSpan/endSpan/recordSpanError/setSpanAttribute helpers directly, so classes extending it do not need to import from @quik/telemetry for basic span tracing.

Bridge logs into the active span​

TELEMETRY_LOGGING_BRIDGE=true
TELEMETRY_LOGGING_PASSTHROUGH=true

With telemetry.logging.bridge enabled, log records emitted while a span is active are attached to that span via TelemetryLogger; telemetry.logging.passthrough additionally forwards them to the normal logger output.