Tracing

// src/orders/orders.service.ts
import { Injectable } from '@nestjs/common';
import { SpanStatusCode, trace } from '@opentelemetry/api';
import { OrdersRepository } from './orders.repository.js';

// One tracer per module or library; the name and version appear on the span
// as its instrumentation scope.
const tracer = trace.getTracer('orders-api', '1.4.0');

@Injectable()
export class OrdersService {
  constructor(private readonly orders: OrdersRepository) {}

  async settle(orderId: string): Promise<number> {
    // startActiveSpan makes this span the parent of everything awaited
    // inside the callback, including the SQL spans the pg instrumentation
    // creates, and returns whatever the callback returns.
    return tracer.startActiveSpan('settle order', async (span) => {
      span.setAttribute('order.id', orderId);

      try {
        const totalCents = await this.orders.settle(orderId);
        span.setAttribute('order.total_cents', totalCents);
        return totalCents;
      } catch (error) {
        span.recordException(error as Error);
        span.setStatus({ code: SpanStatusCode.ERROR, message: 'settle failed' });
        throw error;
      } finally {
        // A span that is never ended is never exported. finally covers both
        // the success and the failure path.
        span.end();
      }
    });
  }
}

// src/observability/trace-fields.ts
import { trace } from '@opentelemetry/api';

// Returns an empty object when no span is active, for example when the SDK
// was not preloaded or the call came from a startup hook.
export function traceFields(): { traceId?: string; spanId?: string } {
  const span = trace.getActiveSpan();

  if (!span) {
    return {};
  }

  const { traceId, spanId } = span.spanContext();
  return { traceId, spanId };
}

// src/orders/shipping.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { traceFields } from '../observability/trace-fields.js';

@Injectable()
export class ShippingService {
  private readonly logger = new Logger(ShippingService.name);

  dispatch(orderId: string, carrier: string): void {
    // The ids go into the structured params, so one log query opens the
    // matching trace and one trace links back to its log lines.
    this.logger.log('dispatch requested', {
      orderId,
      carrier,
      ...traceFields(),
    });
  }
}

// src/jobs/email.producer.ts
import { InjectQueue } from '@nestjs/bullmq';
import { Injectable } from '@nestjs/common';
import { context, propagation } from '@opentelemetry/api';
import type { Queue } from 'bullmq';

export interface EmailJob {
  to: string;
  carrier: Record<string, string>;
}

@Injectable()
export class EmailProducer {
  constructor(@InjectQueue('email') private readonly queue: Queue<EmailJob>) {}

  async enqueue(to: string): Promise<void> {
    // inject() writes the active context into a plain object as W3C headers
    // ({ traceparent, tracestate, baggage }), which is JSON-safe.
    const carrier: Record<string, string> = {};
    propagation.inject(context.active(), carrier);

    await this.queue.add('welcome', { to, carrier });
  }
}

// src/jobs/email.processor.ts
import { Processor, WorkerHost } from '@nestjs/bullmq';
import { SpanKind, context, propagation, trace } from '@opentelemetry/api';
import type { Job } from 'bullmq';
import { MailService } from '../mail/mail.service.js';
import type { EmailJob } from './email.producer.js';

const tracer = trace.getTracer('email-worker');

@Processor('email')
export class EmailProcessor extends WorkerHost {
  constructor(private readonly mail: MailService) {
    super();
  }

  async process(job: Job<EmailJob>): Promise<void> {
    // extract() rebuilds the producer's context; context.with() makes it
    // active, so this span is a child of the request that queued the job
    // instead of a trace of its own.
    const parent = propagation.extract(context.active(), job.data.carrier);

    await context.with(parent, () =>
      tracer.startActiveSpan(
        'send welcome email',
        { kind: SpanKind.CONSUMER },
        async (span) => {
          try {
            await this.mail.sendWelcome(job.data.to);
          } finally {
            span.end();
          }
        },
      ),
    );
  }
}