API de Logger de Astro

Añadido en: astro@7.0.0 Nuevo

La API de Logger proporciona mayor control sobre la infraestructura de logging de Astro. Esto te permite reemplazar el output por defecto de la consola con implementaciones de logging personalizadas y conectarte a servicios de agregación de logs.

Esta API incluye tres loggers listos para usar y te permite integrar tus propios loggers y combinarlos.

Loggers personalizados

Puedes crear un logger personalizado proporcionando la configuración correcta al ajuste logger. Acepta un objeto con un entrypoint obligatorio, el módulo donde se exporta el logger, y una configuración opcional para pasar al logger. La configuración debe ser serializable.

La función del logger debe exportarse como default.

Cuando defines un logger personalizado, eres responsable de todos los logs, incluso los emitidos por Astro.

El siguiente ejemplo define un logger personalizado exportado por el paquete @org/custom-logger y que acepta solo un parámetro para configurar el nivel de logging:

astro.config.mjs

import { defineConfig } from 'astro/config';

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

El siguiente ejemplo implementa un logger minimalista que devuelve un objeto AstroLoggerDestination con la función write() requerida:

@org/custom-logger/index.ts

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

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

export default orgLogger;

Ahora puedes añadir tus propios logs durante el renderizado de una página usando las APIs de runtime.

Nivel de log

Un nivel es una puntuación interna y arbitraria asignada a cada mensaje. Cuando un logger se configura con un cierto nivel, solo se imprimen los mensajes con un nivel igual o superior.

Hay tres niveles, de la puntuación más alta a la más baja:

1. error
2. warn
3. info

El siguiente ejemplo configura el logger JSON para imprimir solo los mensajes que tienen el nivel warn o superior:

astro.config.mjs

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

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

El paquete astro/logger expone un helper matchesLevel() para comprobar el nivel de log. Esto puede ser útil al construir un logger personalizado.

import { matchesLevel } from "astro/logger";

matchesLevel("error", "info");

Loggers integrados

Astro ofrece loggers integrados que las aplicaciones pueden usar.

logHandlers.json()

Un logger que outputa mensajes en formato JSON. Un log se vería así:

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

Opciones del logger JSON

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

Añadido en: astro@7.0.0 Nuevo

El logger json acepta las siguientes opciones:

• pretty: cuando es true, el log JSON se imprime en múltiples líneas. Por defecto es false.
• level: el nivel de logs que deberían imprimirse.

astro.config.mjs

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

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

logHandlers.console()

Un logger que imprime mensajes usando la consola como destino. Basándose en el nivel del mensaje, usa diferentes canales:

• Los mensajes de error se imprimen usando console.error().
• Los mensajes de warn se imprimen usando console.warn().
• Los mensajes de info se imprimen usando console.info().

Opciones del logger de consola

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

Añadido en: astro@7.0.0 Nuevo

El logger console acepta las siguientes opciones:

• level: el nivel de logs que deberían imprimirse.

astro.config.mjs

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

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

logHandlers.node()

Un logger que imprime mensajes a process.stdout y process.stderr. Los mensajes de nivel error se imprimen a stderr, mientras que los demás se imprimen a stdout.

Este es el logger por defecto de Astro.

Opciones del logger de Node

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

Añadido en: astro@7.0.0 Nuevo

El logger node acepta las siguientes opciones:

• level: el nivel de logs que deberían imprimirse.

astro.config.mjs

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

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

logHandlers.compose()

Una función particular que permite configurar múltiples loggers en un orden arbitrario. El mismo mensaje se transmite a todos los loggers.

El siguiente ejemplo combina el logger de consola y el logger JSON usando el nivel de log por defecto:

astro.config.mjs

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

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

Referencia de tipos

Los siguientes tipos pueden importarse desde el specifier astro.

AstroLoggerDestination

Esta es la interfaz que los loggers personalizados deben implementar.

AstroLoggerDestination.write()

Type: (message: AstroLoggerMessage) => void

Un método obligatorio llamado para cada log y que acepta un AstroLoggerMessage.

AstroLoggerDestination.flush()

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

Una función opcional llamada al final de cada petición. Esto es útil para loggers avanzados que necesitan hacer flush de los mensajes de log mientras mantienen viva la conexión con el destino.

AstroLoggerDestination.close()

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

Una función opcional llamada antes de que un servidor se apague. Esta función suele ser llamada por adapters como @astrojs/node.

AstroLoggerLevel

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

Especifica el nivel de verbosidad de los logs:

• info, warn, y error: define el nivel de log mínimo a imprimir.
• silent: esto es equivalente al flag CLI --silent y habilita logging silencioso.
• debug: esto es equivalente al flag CLI --debug y habilita logging verboso, incluyendo el logging de Vite.

AstroLoggerMessage

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

El objeto entrante de la función AstroLoggerDestination.write():

• message: el mensaje que se está registrando.
• level: el nivel del mensaje.
• label: una etiqueta arbitraria asignada al mensaje de log.
• newLine: si este mensaje debería añadir un salto de línea al final.

Referencia de APIs

Las siguientes APIs pueden importarse desde el specifier astro/logger.

matchesLevel()

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

Dados dos niveles de log, devuelve si el primer nivel coincide con el segundo nivel.

import { matchesLevel } from "astro/logger";

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