> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Winston Transport

> Send Winston logs to Squasher with a transport that batches events and flushes on shutdown.

If you already use [Winston](https://github.com/winstonjs/winston), add the Squasher transport to ship logs and errors to your project without changing how you call `logger.info()` or `logger.error()`.

## Installation

```bash theme={null}
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.

```typescript src/logger.ts theme={null}
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              |

<Note>
  Call `await squasherTransport.close()` during shutdown so any queued events are flushed before the
  process exits.
</Note>

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

```typescript src/app.ts theme={null}
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:

```typescript src/logger.ts theme={null}
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.

```typescript theme={null}
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

```text theme={null}
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.
```