tpaga-logger

tpaga-logger

Structured logging SDK for Tpaga Node.js microservices. Emits wide-event JSON (canonical log line) to stdout for AWS CloudWatch Logs Insights, following loggingsucks.com.

Installation

pnpm add tpaga-logger

Usage

AWS Lambda

Use withLogger to wrap a Lambda handler. It automatically handles timing, correlationId extraction from headers, and emits the terminal log event on success or error.

import { createLogger, withLogger } from 'tpaga-logger';

const logger = createLogger({
  service: 'my-service',
  environment: process.env.STAGE ?? 'dev',
});

export const handler = withLogger(logger, 'createCharge', async (event, log) => {
  log.with({ orderId: event.body.orderId, amount: event.body.amount });
  const result = await chargeService.create(event.body);
  return { statusCode: 200, body: JSON.stringify(result) };
});

What withLogger does automatically:

• Extracts correlationId from x-correlation-id or x-request-id headers (generates a UUID if absent)
• Starts a timer and calculates durationMs
• Emits outcome: "success" with statusCode on completion
• Emits outcome: "error" with serialized error on failure, then re-throws

---

Express

Register two middlewares from the library — one before routes, one after. Both are zero-config.

import express from 'express';
import { createLogger, withTpagaExpressLogger, tpagaExpressErrorLogger } from 'tpaga-logger';
import { errorHandler } from './middleware/errorHandler';

const logger = createLogger({ service: 'url-signer-service', environment: process.env.NODE_ENV ?? 'dev' });

const app = express();
app.use(express.json());
app.use(withTpagaExpressLogger(logger)); // before routes: timing, correlationId, req.log

app.use('/api/v1/sign', signRouter);

app.use(tpagaExpressErrorLogger);        // after routes: serialize + log any error
app.use(errorHandler);                   // after routes: map error → HTTP response (your code)

Express error middleware must be registered after routes — this is an Express constraint.

What withTpagaExpressLogger does automatically:

• Extracts correlationId from x-correlation-id / x-request-id headers (generates UUID if absent)
• Attaches a typed WideEventBuilder to req.log and res.log
• Emits outcome: "success" for statusCode < 400, outcome: "error" otherwise
• Calculates durationMs — always matches the actual response time

What tpagaExpressErrorLogger does automatically:

• Serializes the error via serializeError — no stack, structured errorDetails for Zod-like errors
• Adds error to the log context via req.log.with({ error })
• Calls next(err) to pass the error to your errorHandler

req.log / res.log in controllers:

req.log is available anywhere in the request lifecycle — no import needed:

export const signUrl = async (req: Request, res: Response, next: NextFunction) => {
  try {
    const input = signUrlSchema.parse(req.body);
    req.log.with({ url: input.url, ttlSeconds: input.ttlSeconds });
    res.status(200).json(generateSignedUrl(input));
  } catch (err) {
    req.log.with({ attemptedUrl: req.body?.url, stage: 'signing' }); // extra context on error
    next(err);
  }
};

res.log works the same — useful in error handler middleware where req params are prefixed with _.

statusCode in the log always matches the HTTP response — it's read from res.statusCode after the response is sent.

serializeError output:

Error type	type	message	errorDetails
ZodError	ZodError	Validation failed	array of Zod issues
AppError / Error	Error	original message	—
Unknown	UnknownError	String(err)	—

---

NestJS + Fastify ^v0.0.9+

Import from tpaga-logger/fastify. Register the plugin and the global interceptor — both are zero-config.

// app.module.ts
import { Module } from '@nestjs/common';
import { TpagaLoggerModule } from 'tpaga-logger/fastify';

@Module({
  imports: [
    TpagaLoggerModule.forRoot({
      service: process.env.SERVICE_NAME ?? 'my-service',
      environment: process.env.NODE_ENV ?? 'dev',
    }),
  ],
})
export class AppModule {}

// main.ts
import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
import { withTpagaFastifyLogger, TpagaLoggerInterceptor, TPAGA_LOGGER } from 'tpaga-logger/fastify';
import type { Logger } from 'tpaga-logger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter());

  const logger = app.get<Logger>(TPAGA_LOGGER);
  await app.register(withTpagaFastifyLogger(logger)); // before routes: timing, correlationId, request.tpagaLog
  app.useGlobalInterceptors(new TpagaLoggerInterceptor()); // catch errors before exception filters

  await app.listen(3000, '0.0.0.0');
}
bootstrap();

What withTpagaFastifyLogger does automatically:

• Extracts correlationId from x-correlation-id / x-request-id headers (generates UUID if absent)
• Attaches a typed WideEventBuilder to request.tpagaLog
• Emits outcome: "success" for statusCode < 400, outcome: "error" otherwise
• Calculates durationMs — always matches the actual response time

What TpagaLoggerInterceptor does automatically:

• Wraps every route handler and catches thrown exceptions before NestJS exception filters run
• Serializes the error via serializeError and adds it to the log context via request.tpagaLog.with({ error })
• Re-throws so NestJS exception handling continues normally

Use request.tpagaLog (not request.log) — Fastify already attaches its own pino logger to request.log.

request.tpagaLog in controllers:

import { Controller, Get, Param, Req } from '@nestjs/common';
import type { FastifyRequest } from 'fastify';

@Controller('charges')
export class ChargesController {
  @Get(':id')
  async getCharge(@Req() req: FastifyRequest, @Param('id') id: string) {
    req.tpagaLog.with({ chargeId: id });
    const charge = await this.chargesService.findById(id);
    req.tpagaLog.with({ merchantId: charge.merchantId });
    return charge;
  }
}

---

API

tpaga-logger (Express + Lambda)

Export	Description
createLogger(config)	Creates a logger instance for a service
withLogger(logger, name, handler)	Lambda handler wrapper
withTpagaExpressLogger(logger)	Express middleware (register with app.use)
tpagaExpressErrorLogger	Express error middleware (register after routes)
getLog(res)	Gets the WideEventBuilder from an Express response
serializeError(err)	Serializes an unknown error to a structured object
LOG_LEVELS	['info', 'warn', 'error', 'debug']
OUTCOMES	['success', 'error', 'validation_failed', ...]

tpaga-logger/fastify (NestJS + Fastify)

Export	Description
withTpagaFastifyLogger(logger)	Fastify plugin — register with app.register()
TpagaLoggerInterceptor	NestJS interceptor — register with app.useGlobalInterceptors()
TpagaLoggerModule	NestJS dynamic module — import in AppModule
TPAGA_LOGGER	Injection token to retrieve the Logger instance via DI

LoggerConfig

type LoggerConfig = {
  service: string;
  environment?: string;
  redactKeys?: readonly string[]; // paths redacted with '[REDACTED]'
};

WideEventBuilder (log)

type WideEventBuilder = {
  with: (fields: Record<string, unknown>) => void;   // add context fields
  emit: (level: LogLevel, message: string, terminal: TerminalFields) => void; // send the log line
};

emit is called automatically by withLogger and withTpagaExpressLogger. Call it manually only when using startOperation directly.

---

Local development (pretty logs)

pino-pretty is bundled in the library — no extra install needed in your service. Just start with LOG_PRETTY=true:

LOG_PRETTY=true node dist/index.js
# or for Lambda local testing:
LOG_PRETTY=true npx ts-node src/handler.ts

Output in the console:

[09:11:00.142] INFO: createCharge completed
    service: "cash-in-manager"
    correlationId: "abc-123"
    orderId: "ORD-456"
    amount: 50000
    outcome: "success"
    durationMs: 142

In production, leave LOG_PRETTY unset — raw JSON goes to stdout and CloudWatch Logs Insights queries it natively.

---

Development

pnpm install
pnpm typecheck
pnpm lint
pnpm test
pnpm build

Docs

• Log contract: .agents/docs/SERF-5797_LOG_STRUCTURE_CONTRACT.md
• Implementation plan: .agents/docs/SERF-5796_TPAGA_LOGGER_IMPLEMENTATION_PLAN.md

Repo

https://bitbucket.org/tpaga/tpaga-logger/src/main/