Winston Transport

If you already use Winston, add the Squasher transport to ship logs and errors to your project without changing how you call logger.info() or logger.error().

Installation

npm install @squasher/winston winston

Configuration

Create one SquasherTransport and add it to your Winston logger. Using winston.format.metadata() is recommended so structured fields land in Squasher as searchable metadata.

src/logger.ts

import winston from "winston";
import { SquasherTransport } from "@squasher/winston";

export const squasherTransport = new SquasherTransport({
  apiKey: process.env.SQUASHER_API_KEY ?? "",
  projectId: process.env.SQUASHER_PROJECT_ID ?? "",
  endpoint: "https://ingest.squasher.ai",
  level: "error",
});

export const logger = winston.createLogger({
  level: "info",
  format: winston.format.combine(winston.format.timestamp(), winston.format.metadata()),
  transports: [new winston.transports.Console(), squasherTransport],
});

Option	Type	Default	Description
`apiKey`	`string`	Required	Your project ingest key
`projectId`	`string`	Required	Your Squasher project ID
`endpoint`	`string`	`https://ingest.squasher.ai`	Override the ingest base URL for local or staging environments
`level`	`string`	Winston default	Minimum Winston level forwarded by this transport

Call await squasherTransport.close() during shutdown so any queued events are flushed before the process exits.

The transport automatically splits multi-event request bodies at 1 MB so large log bursts use bounded requests without dropping the remaining buffered events.

Usage Example

src/app.ts

import { logger, squasherTransport } from "./logger";

logger.error("Database connection failed", {
  requestId: "req_123",
  host: "db-primary",
  retryable: true,
});

process.on("SIGTERM", async () => {
  await squasherTransport.close();
  process.exit(0);
});

The transport sends events to POST /v1/ingest/{projectId} with tags.transport = "winston", so you can filter transport-originated logs in Squasher.

Advanced

Custom Levels

The transport maps Winston’s built-in levels to Squasher levels:

warn → warning
error → error
fatal → fatal
debug, verbose, and silly → debug
Any other custom level → info

If you use custom levels, normalize them before the transport sees them:

src/logger.ts

import winston from "winston";

const normalizeLevels = winston.format((info) => {
  if (info.level === "critical") {
    info.level = "fatal";
  }

  return info;
});

const logger = winston.createLogger({
  levels: { critical: 0, warn: 1, info: 2 },
  format: winston.format.combine(
    normalizeLevels(),
    winston.format.timestamp(),
    winston.format.metadata(),
  ),
  transports: [new winston.transports.Console(), squasherTransport],
});

Metadata

When you use winston.format.metadata(), the transport forwards info.metadata as the event’s extra payload in Squasher.

logger.warn("Checkout is retrying", {
  orderId: "ord_123",
  region: "us-east-1",
  attempts: 2,
});

If you do not use format.metadata(), extra Winston fields are still forwarded, but metadata() gives you the most predictable shape for nested context.

Agent handoff

Install @squasher/winston and winston. Add SquasherTransport beside the existing transports, keep apiKey and projectId in environment variables, call close() during shutdown, and verify with one logger.error event.

Get Started

SDKs

Integrations

Migrations

Cloud Log Drains

Features

API Reference

Winston Transport

Installation

Configuration

Usage Example

Advanced

Custom Levels

Metadata

Agent handoff

​Installation

​Configuration

​Usage Example

​Advanced

​Custom Levels

​Metadata

​Agent handoff

Installation

Configuration

Usage Example

Advanced

Custom Levels

Metadata

Agent handoff