Astro Logger API

Agregado en: astro@7.0.0

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

If you do not wish to use one of the built-in loggers, you can build your own.

A custom logger is made of two parts:

• The logger config, which lets Astro know what implementation to use and what config to forward
• The logger implementation, which handles the logging logic

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

The logger config

The logger config is an object containing a required entrypoint and an optional config.

The following example configures a custom logger exported by the @org/custom-logger package and passes it a level option:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  logger: {
    entrypoint: "@org/custom-logger",
    config: {
      level: "warn"
    }
  }
});

The logger implementation

The logger implementation handles the logging logic. You implement it in your logger module by exporting a default function that takes the config as a parameter and returns an AstroLoggerDestination object with the required write() function.

The following example implements a minimal logger that takes the log level from its config into account:

@org/custom-logger/index.ts

import type { AstroLoggerLevel, AstroLoggerDestination } from "astro";
import { matchesLevel } from "astro/logger";

type LoggerOptions = {
  level: AstroLoggerLevel
}

function orgLogger(options: LoggerOptions = {}): AstroLoggerDestination {
  const { level = 'info' } = options;
  return {
    write(message) {
      // 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
      }
    }
  }
}

export default orgLogger;

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:

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.json({ level: "warn" })
});

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

import { matchesLevel } from "astro/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' }

Agregado en: astro@7.0.0

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.

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.json({ pretty: true })
});

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' }

Agregado en: astro@7.0.0

The console logger accepts the following options:

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

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.console({ level: 'warn' })
});

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' }

Agregado en: astro@7.0.0

The node logger accepts the following options:

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

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.node({ level: 'warn' })
});

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:

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.compose(
    logHandlers.console(),
    logHandlers.json()
  )
});

Types reference

The following types can be imported from the astro specifier.

AstroRuntimeLogger

Type: { info: (message: string) => void; warn: (message: string) => void; error: (message: string) => void; }

Agregado en: astro@7.0.8

Describes the logger methods available at runtime for adding additional logs during page rendering.

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.

import { matchesLevel } from "astro/logger";

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