Skip to main content

How to use winston as the Fastify logger

And why it is not a drop-in replacement for pino

Updated 12 min readMarkdown
How to use winston as the Fastify logger

Fastify ships with pino as its logger, and most of the time you never think about it: set logger: true and you get JSON lines with a request id, the URL, the status code and the response time.

But what if your company already standardized on winston? Maybe you have custom transports, a shared logging library, or a dashboard that expects winston's output shape. Throwing all of that away just to adopt a new framework is a hard sell.

The good news is that Fastify accepts any logger you give it. The less good news is that "accepts" and "works like pino" are two very different things 馃槄

So, would you like to see what happens when you swap pino for winston? Let's find out together, and let's fix every issue along the way, without touching your existing winston code.

The minimal setup

Fastify v5 has two options for the logger:

  • logger: a pino configuration object, or true
  • loggerInstance: an already built logger instance, like a winston one

If you pass a winston instance to logger, Fastify throws an error at startup, so loggerInstance is the one we need.

Before passing it, there is one requirement to satisfy. Fastify checks that the instance has these methods: info, error, debug, fatal, warn, trace and child. Winston's default levels are the npm ones (error, warn, info, http, verbose, debug, silly), so fatal and trace are missing and Fastify refuses to start with a FST_ERR_LOG_INVALID_LOGGER error.

We must define the levels ourselves:

import Fastify from "fastify";
import winston from "winston";

const loggerInstance = winston.createLogger({
  // Fastify requires the fatal and trace levels, winston does not have them by default
  levels: {
    fatal: 0,
    error: 1,
    warn: 2,
    info: 3,
    debug: 4,
    trace: 5,
  },
  level: "info",
  format: winston.format.json(),
  transports: [new winston.transports.Console()],
});

const app = Fastify({ loggerInstance });

app.get("/hello", (request, reply) => {
  request.log.info("Sending hello", { user: "manuel" });
  return { greet: "hello" };
});

app.get("/boom", () => {
  throw new Error("kaboom");
});

await app.listen({ port: 3000 });

In winston, a lower number means more severe. Pino does the opposite, trace is 10 and fatal is 60. So trace must get the highest number, otherwise setting level: 'debug' would hide all your debug lines and print the trace ones.

request.log is a winston child logger now, so in our handler we call it the winston way: message first, metadata second.

The server starts, and the logs are in JSON. Let's run a single request and look at the output.

What goes wrong

Here is what pino prints for one curl http://localhost:3000/hello (lines shortened for readability, and with the pino style call request.log.info({ user: "manuel" }, "Sending hello") in the handler):

{"level":30,"reqId":"req-1","req":{"method":"GET","url":"/hello","host":"localhost:3000","remoteAddress":"::1","remotePort":53122},"msg":"incoming request"}
{"level":30,"reqId":"req-1","user":"manuel","msg":"Sending hello"}
{"level":30,"reqId":"req-1","res":{"statusCode":200},"responseTime":12.57,"msg":"request completed"}

And here is the winston setup above, for the same request (the first and last lines are truncated, keep reading to know why):

{"level":"info","message":{"req":{"id":"req-1","log":{},"params":{},"query":{},"raw":{"_consuming":false,"_dumped":false,"_events":{},"_readableState":{...
{"level":"info","message":"Sending hello","reqId":"req-1","user":"manuel"}
{"level":"info","message":{"res":{"log":{},"raw":{"_closed":false,"_contentLength":17,"_defaultKeepAlive":true,...

Our own line is perfect, but the two lines that Fastify writes for us are a mess, and they hide four different problems.

1. The arguments order is reversed

Pino's signature is log.info(mergingObject, message), while winston's signature is log.info(message, meta).

Fastify is built around pino, so every log line it writes for you uses the pino order. These lines live in the LogController class, the layer that writes the automatic request logs, and its default implementation looks like this:

request.log.info({ req: request }, "incoming request");
reply.log.info(
  { res: reply, responseTime: reply.elapsedTime },
  "request completed",
);

You can extend this class and override each method to change the level, the payload or even drop a line. I wrote all about it in "Your health check is writing a million log lines a month", so keep it in mind, we will need it later.

Winston receives an object as the message and a string as extra metadata, so it stores the object in the message field and drops the string. So the incoming request and request completed messages are lost.

2. The serializers are not applied

Pino's req field is small because Fastify registers pino serializers for the req, res and err keys, which pick a few useful fields.

Fastify adds them by calling logger.child({}, { serializers }). Winston's child() accepts only the first argument, the default metadata, so the serializers are silently ignored. Winston then serializes the whole Fastify Request and Reply objects, including the raw Node.js socket.

I measured it on my machine (macOS, Node.js v24, Fastify v5, winston v3.19.0), with one curl request and the server startup lines excluded:

Setup Lines Bytes
pino (logger: true) 3 529
winston, naive setup 3 14.985

That is about 28 times more bytes for the same request. If your log management platform bills you by volume, you will notice it at the end of the month.

3. The errors are empty

When the /boom route throws, Fastify logs { req, res, err }. Without the err serializer, winston's JSON format turns the Error instance into {}, because the message and stack properties of an error are not enumerable.

So the error line contains thousands of characters about the socket and nothing about the error itself. Not great when you are debugging a production issue at 3 AM 馃槺

4. The route logLevel option is ignored

Fastify lets you set a log level per route or per plugin:

app.get("/quiet", { logLevel: "warn" }, handler);

Under the hood, it calls logger.child(bindings, { level: 'warn' }) to create the request.log instance. Again, winston ignores the second argument, so the route logs at the root level.

The only thing that works out of the box is the reqId binding, because it is passed as the first argument of child(). Lucky us!

Making Fastify speak winston

That sounds like a lot of issues, but don't worry, we can fix all of them with two small pieces of code:

  1. a custom LogController that writes Fastify's log lines with the winston signature and with small req, res and err objects
  2. a Fastify childLoggerFactory that applies the route log level

We could go the other way around and teach winston to understand pino calls, but you already have winston code, formats and dashboards, so the fix should adapt Fastify to your logger.

Note The logController option is available since Fastify v5.10.0.

A winston LogController

The LogController has one method for each kind of line Fastify writes, so we extend it and rewrite the lines in winston's language:

import { LogController } from "fastify";

// The same fields that the Fastify built-in serializers log
const serializeReq = (request) => ({
  method: request.method,
  url: request.url,
  host: request.host,
  remoteAddress: request.ip,
});
const serializeRes = (reply) => ({ statusCode: reply.statusCode });
const serializeErr = (error) => ({
  type: error?.constructor.name,
  message: error?.message,
  stack: error?.stack,
});

export class WinstonLogController extends LogController {
  incomingRequest(request, reply) {
    if (this.isLogDisabled(request)) {
      return;
    }

    request.log.info("incoming request", { req: serializeReq(request) });
  }

  requestCompleted(error, request, reply) {
    if (this.isLogDisabled(request)) {
      return;
    }

    const meta = { res: serializeRes(reply), responseTime: reply.elapsedTime };
    if (error) {
      reply.log.error("request errored", { ...meta, err: serializeErr(error) });
    } else {
      reply.log.info("request completed", meta);
    }
  }

  defaultErrorLog(error, request, reply) {
    if (this.isLogDisabled(request)) {
      return;
    }

    if (reply.statusCode >= 500) {
      reply.log.error(error?.message, {
        req: serializeReq(request),
        res: serializeRes(reply),
        err: serializeErr(error),
      });
    } else {
      reply.log.info(error?.message, {
        res: serializeRes(reply),
        err: serializeErr(error),
      });
    }
  }
}

The controller does three things:

  1. Every method calls this.isLogDisabled(request) first. When you override a method you replace the default gate too, so we keep it to respect the disableRequestLogging option
  2. The message is the first argument and the metadata is the second one, so winston stores them where they belong
  3. We serialize req, res and err ourselves, picking the same fields that Fastify's pino serializers log. No more sockets in your logs, and the error finally has its message and stack

The method names and the default lines are the same as Fastify's, so the output keeps the same meaning: incoming request, request completed and the error message.

The controller has a few more methods for rarer lines, such as stream errors or a failing response serializer. They follow the same pattern, and you can find all of them in the companion project.

Your own code doesn't change at all: it keeps calling request.log.info("Sending hello", { user: "manuel" }), and your formats and transports keep working as before.

A child logger factory

Fastify has a childLoggerFactory option: a function that Fastify calls every time it needs to create the request.log instance. It receives the parent logger, the bindings ({ reqId }) and the child options, which contain the level when a route defines a logLevel.

const LEVEL = Symbol.for("level");

export function childLoggerFactory(logger, bindings, opts) {
  const child = logger.child(bindings);
  if (!opts.level) {
    return child;
  }

  // Apply the route `logLevel` option, winston's child() ignores it
  const maxLevel = levels[opts.level];
  return Object.create(child, {
    write: {
      value(info) {
        if (levels[info[LEVEL]] <= maxLevel) {
          child.write(info);
        }
      },
    },
  });
}

Winston's child() itself works by creating a new object on top of the parent with a custom write method, so we use the same trick: we wrap the child and drop every line that is less severe than the route level. The levels object is the same one we passed to winston.createLogger(), and Symbol.for("level") is the key where winston stores the level name of each line.

The root level still applies, because winston's transports filter the lines too. So with this implementation a route can only be quieter than the root logger. For example, a debug route under an info root logger still prints only info and above.

Putting it all together

Now the application looks like this:

import Fastify from "fastify";
import winston from "winston";
import {
  createWinstonLogger,
  WinstonLogController,
  childLoggerFactory,
} from "./winston-fastify.mjs";

const loggerInstance = createWinstonLogger({
  level: "info",
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: "error.log", level: "error" }),
  ],
});

const app = Fastify({
  loggerInstance,
  logController: new WinstonLogController(),
  childLoggerFactory,
});

app.get("/hello", (request, reply) => {
  request.log.info("Sending hello", { user: "manuel" });
  return { greet: "hello" };
});

app.get("/quiet", { logLevel: "warn" }, (request, reply) => {
  request.log.info("You will not see this line");
  return { greet: "shhh" };
});

app.get("/boom", () => {
  throw new Error("kaboom");
});

await app.listen({ port: 3000 });

The createWinstonLogger() function is a plain winston.createLogger() call with our levels and the timestamp() and json() formats, nothing Fastify specific. The example also uses winston's transports, so every line goes to the console and the error lines go to the error.log file as well.

Let's call /hello again:

{"level":"info","message":"incoming request","req":{"host":"localhost:3000","method":"GET","remoteAddress":"::1","url":"/hello"},"reqId":"req-1","timestamp":"2026-11-21T09:30:17.000Z"}
{"level":"info","message":"Sending hello","reqId":"req-1","timestamp":"2026-11-21T09:30:17.001Z","user":"manuel"}
{"level":"info","message":"request completed","reqId":"req-1","res":{"statusCode":200},"responseTime":2.64,"timestamp":"2026-11-21T09:30:17.003Z"}

Cool! The messages are back, the req and res fields are small, and the same request now writes 459 bytes. Calling /quiet prints nothing at all, because even Fastify's own info lines respect the route level.

And the /boom error is finally useful (stack trace shortened):

{
  "err": {
    "message": "kaboom",
    "stack": "Error: kaboom\n    at Object.<anonymous> (file:///.../02-winston.mjs:30:9)...",
    "type": "Error"
  },
  "level": "error",
  "message": "kaboom",
  "req": {
    "host": "localhost:3000",
    "method": "GET",
    "remoteAddress": "::1",
    "url": "/boom"
  },
  "reqId": "req-2",
  "res": { "statusCode": 500 },
  "timestamp": "2026-11-21T09:30:17.542Z"
}

The companion project includes a few node:test tests that check all of these behaviours with app.inject(), so you can change the controller and see what breaks.

Pino vs winston in Fastify

Here are all the differences side by side:

pino winston
Fastify option logger loggerInstance
Call signature log.info(obj, 'msg') log.info('msg', meta)
Fastify's automatic log lines work out of the box need a custom LogController
Level numbers higher is more severe (fatal: 60) lower is more severe (fatal: 0)
fatal and trace levels built in must be defined
Fastify req, res, err serializers applied ignored, serialize in the LogController
Route logLevel works ignored, needs a childLoggerFactory
Message key msg message
Level format number (30) string ("info")

If you have dashboards or alerts built on top of your current logs, check the last two rows: the output shape changes, so update your queries before switching.

Even with loggerInstance, Fastify still loads pino internally, so pino stays in your dependency tree and winston only replaces the logger you call.

So, should you use winston with Fastify? It depends 馃槃 If you are starting a new project, stick with pino: it is the default, Fastify's logging features are designed around it, and you get all of them for free. If you have a good reason to keep winston, such as an existing transport or a company wide logging library, it works fine once you add the controller and the factory we built.

Summary

Plugging winston into Fastify takes one line, but making it behave correctly takes a bit more care:

  • use the loggerInstance option and define the fatal and trace levels, with trace as the highest number
  • remember that Fastify writes its own log lines with the pino signature, (obj, msg), while winston expects (msg, meta)
  • extend the LogController to rewrite those lines the winston way, with small req, res and err objects, otherwise your logs grow about 28 times in size and your errors are empty
  • use childLoggerFactory if you rely on the route logLevel option

All the runnable examples live in the bonus/winston-logger directory of this repository.

If you enjoyed this article, you might like "Accelerating Server-Side Development with Fastify". Comment, share and follow me on X/Twitter!

About the author

  • I'm Manuel and I work at NearForm as a Full Remote Software Developer from 馃嚠馃嚬 Italy. I'm one of the Fastify maintainers since 2019. Contributing to Open Source Software teaches me something new every day. You should join this extraordinary world.

Which part broke first when you swapped it in: the request serializers or the log levels?