feat(logger): docs and runtime

.changeset/silver-berries-send.md

@@ -0,0 +1,55 @@
+---
+'astro': minor
+---
+
+Adds experimental support for configurable log handlers.
+
+This experimental feature provides better control over Astro's logging infrastructure by allowing users to replace the default console output with custom logging implementations (e.g., structured JSON). This is particularly useful for users using on-demand rendering and wishing to connect their log aggregation services such as Kibana, Logstash, CloudWatch, Grafana, or Loki.
+
+By default, Astro provides three built-in log handlers (`json`, `node` and `console`), but you can also create your own.
+#### JSON logging
+
+JSON logging can be enabled via the CLI for the `build`, `dev`, and `sync` commands using the `experimentalJson` flag:
+
+
+```js
+// astro.config.mjs
+import { defineConfig, logHandlers } from "astro/config";
+
+export default defineConfig({
+  experimental: {
+    logger: logHandlers.json({
+      pretty: true,
+      level: 'warn'
+    }) 
+  }
+})
+```
+
+#### Custom logger
+
+You can also create your own custom logger by implementing the correct interface:
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+
+export default defineConfig({
+  experimental: {
+    logger: {
+      entrypoint: "@org/custom-logger"
+    }
+  }
+})
+```
+
+```ts
+// @org/custom-logger.js
+import type { AstroLoggerDestination, AstroLoggerMessage } from "astro"
+
+const customLogger: AstroLoggerDestination = {
+  write(message: AstroLoggerMessage) {
+    // write message somewhere
+  }
+} 
+export default customLogger

packages/astro/package.json

@@ -82,6 +82,7 @@
     "./errors": "./dist/core/errors/userError.js",
     "./middleware": "./dist/core/middleware/index.js",
     "./virtual-modules/*": "./dist/virtual-modules/*",
+    "./logger": "./dist/core/logger/public.js",
     "./logger/json": "./dist/core/logger/impls/json.js",
     "./logger/node": "./dist/core/logger/impls/node.js",
     "./logger/compose": "./dist/core/logger/impls/compose.js",

packages/astro/src/actions/runtime/types.ts

@@ -105,6 +105,7 @@ export type ActionAPIContext = Pick<
 	| 'session'
 	| 'cache'
 	| 'csp'
+	| 'logger'
 >;
 
 export type MaybePromise<T> = T | Promise<T>;

packages/astro/src/container/index.ts

@@ -181,6 +181,7 @@ function createManifest(
 		experimentalQueuedRendering: manifest?.experimentalQueuedRendering ?? {
 			enabled: false,
 		},
+		experimentalLogger: manifest?.experimentalLogger ?? false,
 	};
 }
 
@@ -273,6 +274,7 @@ type AstroContainerManifest = Pick<
 	| 'assetsDir'
 	| 'image'
 	| 'experimentalQueuedRendering'
+	| 'experimentalLogger'
 >;
 
 type AstroContainerConstructor = {

packages/astro/src/core/app/types.ts

@@ -158,6 +158,8 @@ export type SSRManifest = {
 	};
 	internalFetchHeaders?: Record<string, string>;
 	logLevel: AstroLoggerLevel;
+	// This is temporary, and only used while the logger is experimental
+	experimentalLogger: boolean;
 };
 
 export type SSRActions = {

packages/astro/src/core/build/plugins/plugin-manifest.ts

@@ -388,5 +388,6 @@ async function buildManifest(
 		internalFetchHeaders,
 		logLevel: settings.logLevel,
 		shouldInjectCspMetaTags: shouldTrackCspHashes(settings.config.security.csp),
+		experimentalLogger: !!settings.config.experimental?.logger,
 	};
 }

packages/astro/src/core/logger/core.ts

@@ -1,18 +1,26 @@
 import colors from 'piccolore';
 
+/**
+ *
+ */
 export interface AstroLoggerDestination<T = unknown> {
 	/**
 	 * It receives a message and writes it into a destination
 	 */
 	write: (chunk: T) => void;
-	// NOTE: will document once we actually use it
+	/**
+	 * It dumps logs without closing the connection to the destination.
+	 * Method that can be used by specialized loggers.
+	 */
 	flush?: () => Promise<void> | void;
-	// NOTE: will document once we actually use it
+	/**
+	 * It dumps logs and closes the connection to the destination.
+	 * Method that can be used by specialized loggers.
+	 */
 	close?: () => Promise<void> | void;
 }
 
 // NOTE: this is a public type
-
 /**
  * The level of logging. Priority is the following:
  * 1. debug

packages/astro/src/core/logger/handlers.ts

@@ -1,24 +1,78 @@
 import type { LoggerHandlerConfig } from './config.js';
 import type { JonsHandlerConfig } from './impls/json.js';
+import type { NodeHandlerConfig } from './impls/node.js';
+import type { ConsoleHandlerConfig } from './impls/console.js';
 
 export const logHandlers = {
+	/**
+	 * It uses the built-in Astro JSON logger.
+	 * @example
+	 * ```js
+	 * export default defineConfig({
+	 *   experimental: {
+	 *     logger: logHandlers.json({ pretty: true })
+	 *   }
+	 * })
+	 * ```
+	 */
 	json(config?: JonsHandlerConfig): LoggerHandlerConfig {
 		return {
 			entrypoint: 'astro/logger/json',
 			config,
 		};
 	},
-	node(): LoggerHandlerConfig {
+	/**
+	 * It uses the built-in Astro Node.js logger.
+	 *
+	 * @example
+	 * ```js
+	 * export default defineConfig({
+	 *   experimental: {
+	 *     logger: logHandlers.node({ pretty: true })
+	 *   }
+	 * })
+	 * ```
+	 */
+	node(config?: NodeHandlerConfig): LoggerHandlerConfig {
 		return {
 			entrypoint: 'astro/logger/node',
+			config,
 		};
 	},
-	console(): LoggerHandlerConfig {
+	/**
+	 * It uses the built-in Astro console logger.
+	 *
+	 * @example
+	 * ```js
+	 * export default defineConfig({
+	 *   experimental: {
+	 *     logger: logHandlers.console({ pretty: true })
+	 *   }
+	 * })
+	 * ```
+	 */
+	console(config?: ConsoleHandlerConfig): LoggerHandlerConfig {
 		return {
 			entrypoint: 'astro/logger/console',
+			config,
 		};
 	},
 
+	/**
+	 * It allows composing different loggers
+	 *
+	 * @example
+	 * ```js
+	 * export default defineConfig({
+	 *   experimental: {
+	 *     logger: logHandlers.compose([
+	 *       logHandlers.console(),
+	 *       logHandlers.json(),
+	 *     ])
+	 *   }
+	 * })
+	 * ```
+	 */
 	compose(...loggers: LoggerHandlerConfig[]): LoggerHandlerConfig {
 		return {
 			entrypoint: 'astro/logger/compose',

packages/astro/src/core/logger/impls/console.ts

@@ -6,18 +6,25 @@ import {
 	type AstroLoggerLevel,
 	AstroLogger,
 } from '../core.js';
+import type { NodeHandlerConfig } from './node.js';
+import { matchesLevel } from '../public.js';
+
+export type ConsoleHandlerConfig = {
+	level?: AstroLoggerLevel;
+};
 
 function consoleLogDestination(
-	level: AstroLoggerLevel = 'info',
+	config: ConsoleHandlerConfig = {},
 ): AstroLoggerDestination<AstroLoggerMessage> {
+	const { level = 'info' } = config;
 	return {
 		write(event: AstroLoggerMessage) {
 			let dest = console.error;
 			if (levels[event.level] < levels['error']) {
 				dest = console.info;
 			}
 
-			if (levels[event.level] < levels[level]) {
+			if (!matchesLevel(event.level, level)) {
 				return;
 			}
 
@@ -37,9 +44,6 @@ export function createConsoleLogger({ level }: { level: AstroLoggerLevel }): Ast
 	});
 }
 
-type Options = {
-	level?: AstroLoggerLevel;
-};
-export default function (options?: Options): AstroLoggerDestination<AstroLoggerMessage> {
-	return consoleLogDestination(options?.level ?? 'info');
+export default function (options?: NodeHandlerConfig): AstroLoggerDestination<AstroLoggerMessage> {
+	return consoleLogDestination(options);
 }

packages/astro/src/core/logger/impls/json.ts

@@ -7,9 +7,16 @@ import {
 } from '../core.js';
 import type { Writable } from 'node:stream';
 import type { AstroInlineConfig } from '../../../types/public/index.js';
+import { matchesLevel } from '../public.js';
 
 export type JonsHandlerConfig = {
+	/**
+	 * Whether the JSON line should format on multiple lines
+	 */
 	pretty?: boolean;
+	/**
+	 * The level of logs that should be printed by the logger.
+	 */
 	level?: AstroLoggerLevel;
 };
 
@@ -30,7 +37,7 @@ export default function jsonLoggerDestination(
 				dest = process.stdout;
 			}
 
-			if (levels[event.level] < levels[level]) {
+			if (!matchesLevel(event.level, level)) {
 				return;
 			}
 

packages/astro/src/core/logger/impls/node.ts

@@ -8,22 +8,28 @@ import {
 } from '../core.js';
 import type { Writable } from 'node:stream';
 import type { AstroInlineConfig } from '../../../types/public/index.js';
+import { matchesLevel } from '../public.js';
 
 type ConsoleStream = Writable & {
 	fd: 1 | 2;
 };
 
+export type NodeHandlerConfig = {
+	level?: AstroLoggerLevel;
+};
+
 function nodeLogDestination(
-	level: AstroLoggerLevel = 'info',
+	config: NodeHandlerConfig = {},
 ): AstroLoggerDestination<AstroLoggerMessage> {
+	const { level = 'info' } = config;
 	return {
 		write(event: AstroLoggerMessage) {
 			let dest: ConsoleStream = process.stderr;
 			if (levels[event.level] < levels['error']) {
 				dest = process.stdout;
 			}
 
-			if (levels[event.level] < levels[level]) {
+			if (!matchesLevel(event.level, level)) {
 				return;
 			}
 
@@ -37,11 +43,8 @@ function nodeLogDestination(
 	};
 }
 
-type Options = {
-	level?: AstroLoggerLevel;
-};
-export default function (options?: Options): AstroLoggerDestination<AstroLoggerMessage> {
-	return nodeLogDestination(options?.level ?? 'info');
+export default function (options?: NodeHandlerConfig): AstroLoggerDestination<AstroLoggerMessage> {
+	return nodeLogDestination(options);
 }
 
 export function createNodeLoggerFromFlags(inlineConfig: AstroInlineConfig): AstroLogger {

packages/astro/src/core/logger/public.ts

@@ -0,0 +1,16 @@
+// This is public module with functions exported to the user
+
+import { type AstroLoggerLevel, levels } from './core.js';
+
+/**
+ * Returns `true` if `messageLevel` has a level equals or higher than `configuredLevel`
+ *
+ * @param messageLevel The level of the incoming message
+ * @param configuredLevel The level the logger is configured with
+ */
+export function matchesLevel(
+	messageLevel: AstroLoggerLevel,
+	configuredLevel: AstroLoggerLevel,
+): boolean {
+	return levels[messageLevel] >= levels[configuredLevel];
+}

packages/astro/src/core/logger/shared.ts

@@ -8,7 +8,7 @@ export const RESOLVED_LOGGER_MODULE_ID = '\0' + LOGGER_MODULE_ID;
 /**
  * Generates virtual module code for a logger factory given a `LoggerHandlerConfig`.
  * Handles built-in loggers (node, console, json), the compose meta-logger,
- * and arbitrary user-provided entrypoints.
+ * and arbitrary user-provided entrypoint.
  */
 export function generateLoggerCode(config: LoggerHandlerConfig): string {
 	switch (config.entrypoint) {

packages/astro/src/core/middleware/index.ts

@@ -121,6 +121,7 @@ function createContext({
 		session: undefined,
 		cache: new DisabledAstroCache(),
 		csp: undefined,
+		logger: undefined,
 	};
 	return Object.assign(context, {
 		getActionResult: createGetActionResult(context.locals),