Logging & Observability

# TaskFlow incident runbook
1. Confirm symptom, start time, affected route/workflow, environment, release.
2. Inspect request/error rate and p95/p99 latency.
3. Select a representative request/error and correlate by requestId.
4. Use traces/logs to isolate the slow/failing boundary.
5. Mitigate first; verify recovery with metrics and health checks.
6. Create follow-up action for root cause, missing telemetry, and test coverage.

# Observability field catalog

Allowed common fields: requestId, event, context, method, normalizedRoute, statusCode, durationMs, environment, release, workspaceId (logs/traces only where needed), internal userId (policy-dependent).

Never record: Authorization headers, cookies, access/refresh tokens, passwords, service-role keys, DATABASE_URL, signed upload tokens, raw uploaded content.

Metric labels should remain low-cardinality: method, normalized route, status class, environment.

# TaskFlow Phase 30 observability snapshot
Study snapshot only. Merge into the evolving TaskFlow repository intentionally. Do not copy secrets into examples. The design keeps NestJS structured logging, Terminus health checks, Sentry error/performance monitoring, and vendor-neutral OpenTelemetry concepts separated by responsibility.

# Official references
- https://docs.nestjs.com/techniques/logger
- https://docs.nestjs.com/recipes/terminus
- https://opentelemetry.io/docs/concepts/signals/
- https://opentelemetry.io/docs/concepts/signals/metrics/
- https://prometheus.io/docs/practices/histograms/
- https://www.npmjs.com/package/@sentry/nestjs
- https://www.npmjs.com/package/@sentry/nextjs
- https://www.npmjs.com/package/@nestjs/terminus
- https://www.npmjs.com/package/@opentelemetry/api

# Phase 30 version lock
- @nestjs/terminus 12.0.0
- @sentry/nestjs 10.75.0
- @sentry/nextjs 10.75.0
- @opentelemetry/api 1.9.1
- @opentelemetry/sdk-node 0.222.0 is discussed but not hard-locked as a production dependency because the package describes itself as experimental.

{
  "dependencies": {
    "@nestjs/terminus": "12.0.0",
    "@sentry/nestjs": "10.75.0",
    "@opentelemetry/api": "1.9.1"
  }
}

import { Controller, Get } from '@nestjs/common';
import { HealthCheck, HealthCheckService, PrismaHealthIndicator } from '@nestjs/terminus';
import { PrismaService } from '../prisma/prisma.service';

@Controller('health')
export class HealthController {
  constructor(
    private readonly health: HealthCheckService,
    private readonly prismaHealth: PrismaHealthIndicator,
    private readonly prisma: PrismaService,
  ) {}

  @Get('live')
  live() { return { status: 'ok' }; }

  @Get('ready')
  @HealthCheck()
  ready() {
    return this.health.check([
      () => this.prismaHealth.pingCheck('database', this.prisma),

import * as Sentry from '@sentry/nestjs';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: Number(process.env.SENTRY_TRACES_SAMPLE_RATE ?? '0.1'),
});

import { ConsoleLogger } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import './instrument';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    logger: new ConsoleLogger({
      json: process.env.NODE_ENV === 'production',
    }),
  });

  app.enableShutdownHooks();
  await app.listen(process.env.PORT ?? 3001);
}
void bootstrap();

import { CallHandler, ExecutionContext, Injectable, Logger, NestInterceptor } from '@nestjs/common';
import type { FastifyReply, FastifyRequest } from 'fastify';
import { Observable, finalize } from 'rxjs';

@Injectable()
export class RequestLoggingInterceptor implements NestInterceptor {
  private readonly logger = new Logger('HTTP');

  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
    const http = context.switchToHttp();
    const request = http.getRequest<FastifyRequest>();
    const reply = http.getResponse<FastifyReply>();
    const started = performance.now();

    reply.header('x-request-id', request.id);

    return next.handle().pipe(
      finalize(() => {
        this.logger.log('HTTP request completed', {
          requestId: request.id,

{
  "dependencies": {
    "@sentry/nextjs": "10.75.0"
  }
}

# Observability verification matrix
- x-request-id returned on API responses.
- request completion log contains requestId, normalized route, status, duration.
- logs contain no Authorization/Cookie/secret values.
- /health/live remains 200 while process is healthy.
- /health/ready fails when test PostgreSQL is unavailable.
- synthetic error appears in non-production Sentry with requestId.
- p95/p99 latency can be derived from histogram/distribution telemetry.
- metrics contain no userId/taskId/requestId labels.
- alert test reaches the intended channel and points to a runbook.