Astro Logger API

The Logger API provides greater control over Astro's logging infrastructure. This allows you to replace the default console output with custom logging implementations and connect to log aggregation services.

This API includes three ready-to-use loggers and allows you to integrate your own loggers and compose them.

Custom loggers

You can create a custom logger by providing the correct configuration to the logger setting. It accepts an object with a mandatory entrypoint, the module where the logger is exported, and an optional configuration to pass to the logger. The configuration must be serializable.

The logger function must be exported as default.

When you define a custom logger, you are in charge of all logs, even the ones emitted by Astro.

The following example defines a custom logger exported by the @org/custom-logger package and accepting only one parameter to configure the logging level:

The following example implements a minimal logger returning an AstroLoggerDestination object with the required write() function:

type LoggerOptions = {
  level: AstroLoggerLevel
}

function orgLogger(options: LoggerOptions = {}): AstroLoggerDestination {
  const { level = 'info' } = options;
  return {
    write(message: AstroLoggerMessage) {
      // Use this utility to understand if the message should be printed 
      if (matchesLevel(message.level, level)) {
        // log message somewhere and take the level into consideration
      }
    }
  }
}

You can now add your own logs during the rendering of a page using the runtime APIs.

Log level

A level is an internal, arbitrary score assigned to each message. When a logger is configured with a certain level, only the messages with a level equal to or higher are printed.

There are three levels, from the highest to the lowest score:

1. error
2. warn
3. info

The following example configures the JSON logger to print only messages that have the warn level or higher:

The astro/logger package exposes a matchesLevel() helper to check the log level. This can be useful when building a custom logger.

matchesLevel("error", "info");

Built-in loggers

Astro offers built-in loggers that applications can use.

logHandlers.json()

A logger that outputs messages in a JSON format. A log would look like this:

{ "message": "<the message>", "label": "router", "level": "info", "time": "<UNIX timestamp>"  }

JSON logger options

**Type:** `{ pretty: boolean; level: AstroLoggerLevel; }`
**Default:** `{ pretty: false, level: 'info' }`

The json logger accepts the following options:

• pretty: when true, the JSON log is printed on multiple lines. Defaults to false.
• level: the level of logs that should be printed.

logHandlers.console()

A logger that prints messages using the console as its destination. Based on the level of the message, it uses different channels:

• error messages are printed using console.error().
• warn messages are printed using console.warn().
• info messages are printed using console.info().

Console logger options

**Type:** `{ level: AstroLoggerLevel }`
**Default:** `{ level: 'info' }`

The console logger accepts the following options:

• level: the level of logs that should be printed.

logHandlers.node()

A logger that prints messages to process.stdout and process.stderr. Level error messages are printed to stderr, while the others are printed to stdout.

This is Astro's default logger.

Node logger options

**Type:** `{ level: AstroLoggerLevel }`
**Default:** `{ level: 'info' }`

The node logger accepts the following options:

• level: the level of logs that should be printed.

logHandlers.compose()

A particular function that allows configuring multiple loggers in an arbitrary order. The same message is broadcast to all loggers.

The following example composes the console logger and JSON logger using the default log level:

Types reference

The following types can be imported from the astro specifier.

AstroLoggerDestination

This is the interface that custom loggers must implement.

AstroLoggerDestination.write()

Type: (message: AstroLoggerMessage) => void

A mandatory method called for each log and accepting an AstroLoggerMessage.

AstroLoggerDestination.flush()

Type: () => Promise<void> | void

An optional function called at the end of each request. This is useful for advanced loggers that need to flush log messages while keeping the connection to the destination alive.

AstroLoggerDestination.close()

Type: () => Promise<void> | void

An optional function called before a server is shut down. This function is usually called by adapters such as @astrojs/node.

AstroLoggerLevel

Type: 'debug' |'info' |'warn' | 'error' | 'silent'

Specifies the verbosity level of logs:

• info, warn, and error: defines the minimal log level to print.
• silent: this is equivalent to the --silent CLI flag and enables silent logging.
• debug: this is equivalent to the --debug CLI flag and enables verbose logging, including Vite logging.

AstroLoggerMessage

Type: { label: string | null; level: AstroLoggerLevel; message: string; newLine: boolean; }

The incoming object from the AstroLoggerDestination.write() function:

• message: the message being logged.
• level: the level of the message.
• label: an arbitrary label assigned to the log message.
• newLine: whether this message should add a trailing newline.

APIs reference

The following APIs can be imported from the astro/logger specifier.

matchesLevel()

Type: matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel) => boolean

Given two log levels, it returns whether the first level matches the second level.

matchesLevel("error", "info"); // true
matchesLevel("info", "error"); // false