[RFC] Blitz logging

[beerose]

Improved and customizable logging system for Blitz

Problems & considerations

1. Currently, logging in is not customizable. We used to have a way to customize the log level and format, but it's not supported in Blitz 2.0. We could bring this back and, for example, add log property to setupBlitzServer:

const { gSSP, gSP, api } = setupBlitzServer({
  plugins: [],
  log: {
    level: "info",
  }
})

Though, long term, it's not configurable enough. It still relies on the logger that Blitz uses internally and doesn't provide with a way to bring your own logger.

2. There's no way to bring your own logger. We should provide a way for people to specify a custom logger and use it internally in Blitz modules instead of tslog (the current logger used in Blitz). For example:

const winstonLogger = winston.createLogger({...});

const { gSSP, gSP, api } = setupBlitzServer({
  plugins: [],
  // pass winstonLogger to the Blitz configuration
})

3. There's no easy way to disable logging unless you patch package particular modules.

4. Currently, internally, we're using tslog, and we should provide a way to customize it fully. Whether we stick to tslog or not, we should expose a way to configure whatever logging tool we use.

const { gSSP, gSP, api } = setupBlitzServer({
  plugins: [],
  log: {
    // be able to pass full tslog settings
  }
})

5. For the default Blitz logger (tslog, currently) we could specify a destination. For example, tslog allows to attach a transport. We should expose a way to support this.

function logToTransport(logObject: ILogObject) {
  // custom transport logic
}

const logger: Logger = new Logger();
logger.attachTransport(
  {
    silly: logToTransport,
    debug: logToTransport,
    trace: logToTransport,
    // ...
  },
  "silly"
);

6. Sometimes, it's necessary to log more metadata related to, for example, Blitz RPC. Can we expose some kind of metadata for people to decide what and where to log? Thinking about something like this:

```ts
const { gSSP, gSP, api } = setupBlitzServer({
  plugins: [],
  logger: {
    error: (message, source, metadata) => {
      switch (source):
        case "rpc":
          console.log("> RPC", metadata, message)
          break
        case "auth":
          console.debug(metadata)
          console.log("> AUTH", message)
          break
    }
  }
})

Goals

• Don't require configuration unless someone wants to change how logging work. Meaning — have reasonable defaults.
• Be configurable.
• Make it easy to hook up external logging systems.

Solution

I was initially thinking about having a logging plugin. Something like this:

const { gSSP, gSP, api } = setupBlitzServer({
  plugins: [
    AuthServerPlugin({}),
    LoggingPlugin({
      // general options
      // ...
      // can pass a custom logger here:
      logger: winstonLogger
    })
  ],
})

However, that kind of forces to always have it blitz-server.ts. You may not want to see it if you don't want to change anything in the logging configuration. The advantage of LoggingPlugin is that we could have all the logging setup within the LogginPlugin function. That would be slightly similar to how auth DB adapters work. Ie:

declare function LoggingPlugin(options: LoggingPluginOptions): BlitzLogger {
  // store logger on context so that it can be used in other plugins/modules
  // create and configure logger
  // process the options
  return logger
}

But we can also do it on the setupBlitzServer level:

type LogSettings = 
| { // tslog settings }
| { logger: Logger } // plug in a custom logger. Logger type tbd

const { gSSP, gSP, api } = setupBlitzServer({
  plugins: [AuthServerPlugin({})],
  log: {
    // object of type LogSettings   
  }
})

Action point: currently, the logger is being created in log.ts file in Blitz package, and it's independent from the modules/plugins concept. We should move the initialization somewhere so that the config can be passed from setupBlitzServer. Possibly blitz could expose a function to handle that, and this new function could be used inside setupBlitzServer.

type LogSettings = 
| { // tslog settings }
| { logger: Logger } // plug in a custom logger. Logger type tbd

import {createLogger} from 'blitz'
// createLogger: (options: LogSettings) => BlitzLogger

export const setupBlitzServer = ({plugins, onError, log}: SetupBlitzOptions) => {
  createLogger(log)
  // ..
}

createLogger (or however we decide to call it) would store the logger on context or global or somewhere else. It can also return the logger.

Default API

By default, you don't have to provide any configuration. Blitz will use tslog with Blitz's own config.

Configuration

If you want to configure tslog, you can do it inside setupBlitzServer:

const { gSSP, gSP, api } = setupBlitzServer({
  plugins: [AuthServerPlugin({})],
  log: {
    level: "info",
    type: "pretty",
    instanceName: "custom",
    exposeStack: true,
    colorizePrettyLogs: true,
    stdOut: // Overwrite default std out,
    // and more...
  }
})

Custom logging

Example of custom logging with winston:

const winstonLogger = winston.createLogger({...});

const { gSSP, gSP, api } = setupBlitzServer({
  plugins: [AuthServerPlugin({})],
  log: {
    logger: winstonLogger
  }
})

Now, what about types? What should the logger property's type be? Firstly, it should satisfy an object with the following methods:

• error
• warn
• info
• debug
• silly

For example, winston's logger does have these methods. In case a different tool has a different API, it would be required to cover that manually:

const loggingToolLogger = loggingTool.createLogger({...}); // tool that doesn't have `debug`.

const { gSSP, gSP, api } = setupBlitzServer({
  plugins: [AuthServerPlugin({})],
  log: {
    logger: {
      ...loggingToolLogger,
      debug: (...args) => loggingTool.info(args)
    }
  }
})

Example with adze:

import adze from 'adze';

const config = {
  logLevel: 11,
  useEmoji: true,
  ...
};

const { gSSP, gSP, api } = setupBlitzServer({
  plugins: [AuthServerPlugin({})],
  log: {
    logger: {
      info: adze(config).log,
      debug: (...args) => adze(config).custom('DEBUG', ...args),
      error: adze(config).fail
    }
  }
})

Questions

• Will the be a case to have different logging systems per each Blitz module? E.g. using logging system A for RPC and system B for Auth. Should we make logging customizable per module or stick to a generic logging solution? Would exposing a source as in one of the previous examples be enough?
• What about client-side logging? A separate configuration?
• Should we expose logging adapters or make it possible to pass logger? I wonder whether there aren't too many conceptual differences between e.g. winston and adze to make it agnostic.
• Should we accept something like destinations? E.g. [stdout, new-relic, ...]. Or should we let users deal with that when they are creating/declaring custom loggers? Or should we do both in case someone uses a default Blitz logger (tslog)? Is this solved by tslog's attachTransport?
• Should we also export it from setupBlitzServer so that people can use it somewhere else, e.g. inside queries?
• What properties should the logging adapter include?
• Should we also return a logger from setupBlitzServer? So that people can reuse it in their code? Or is that redundant?

[itsdillon]

Really like the solution. Regarding creating a LoggingPlugin. Couldn't we check if the plugin is present in the array? Otherwise use default configuration?

I also personally don't see a need for using something like wintson or adze. We could probably accomplish the basic customization needs just with tslog (ie. attachTransport), but this is just my opinion.

What about client-side logging? A separate configuration?

I think this could be useful

Should we also export it from setupBlitzServer so that people can use it somewhere else, e.g. inside queries

This can also be very helpful

Any way, this is a great writeup. Very curious on the communities opinion on this.

[beerose]

I also personally don't see a need for using something like wintson or adze.

Well, it's not about us but the community as a whole. There are people who are already using winston or adze or something else and would like to continue using it and blitz. I wrote this based on the feedback and considering multiple use cases.

[itsdillon]

Yup agree 100%. Just sharing my thoughts and encouraging discussion.