feat: stable logger

[ematipico]

Description (required)

This PR adds documentation for the logger APIs, which will be stable soon

For Astro version: 6.4.0. See astro PR #16745.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	90dde15
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6a0c83735624ca0008037e0a
😎 Deploy Preview	https://deploy-preview-13907--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/reference/api-reference.mdx	Source changed, localizations will be marked as outdated.
en/reference/logger-reference.mdx	Localization added, will be marked as complete.
ko/reference/experimental-flags/logger.mdx	Localization removed, will be marked as missing.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[ArmandPhilippot]

Already! Ahah, you move too fast for the French reviewers... I guess I can close #13830 😅

Speaking of that, the link error is because of the Korean translation. We usually delete the translations as well when we stabilize an experimental feature.

I know the content hasn't changed much... maybe we should consider renaming the translation and using a Lunaria directive in a case like this. But, I believe Junseong is able to easily browse the Git history to recover its translation so we can remove it for now.

I left a few suggestions to be consistent with our other references (a bit more verbose in some places, functions notation).

Is Astro.logger particularly useful with custom loggers? If so, maybe we should add a link to /en/reference/api-reference/#logger to improve its discoverability. If not, no change needed!

Also, I noticed we now have loggerConfig in SSRManifest. We'll need a new section in https://docs.astro.build/en/reference/integrations-reference/#ssrmanifest

[ematipico]

Is Astro.logger particularly useful with custom loggers? If so, maybe we should add a link to /en/reference/api-reference/#logger to improve its discoverability. If not, no change needed!

It's the whole point! Ahahaha. Dufus me that I completely overlooked this important connection. The important thing is that the runtime APIs are always at user's disposal regardless of a custom logger, but with a custom logger users have more control.

My last commit added a small paragraph with the link

[ArmandPhilippot]

I was double checking, and I think this is almost ready.

• In the SSRManifest reference, we need a section for loggerConfig. And, now we have a section for log levels, we should update the SSRManifest.logLevel description with a link to that section.
• I left a question about log levels because debug and silent are also available but we do not explain how they differ.

Edit: I found another place https://docs.astro.build/en/reference/modules/astro-config/#imports-from-astroconfig we'll need to add logHandlers there. A good occasion to create a link to the Logger API there!

[ArmandPhilippot]

I missed this one, parentheses for consistency:

Suggested change

	### `logHandlers.compose()`

[ArmandPhilippot]

I was going to say I'm a bit confused by this because in AstroLoggerLevel we also have debug and silent. So, 5 and not 3 levels. But, I just saw the unresolved question in the RFC:

debug info level has been kept out of the picture because we use obug for it, which is noisy and completely different from the rest of the logs. Should we keep it out? Docs should address the differences from normal logging.

It seems in the end we'll keep it? I guess this does not contribute to the score and this is a special case like silent, as this is not available in the runtime API. And, these two levels match the verbose and silent flags. Am I right?

In any case, we should probably have something explaining they are also available and how they differ.

[ematipico]

They were kept out on purpose because:

• debug logging isn't astro logging. It involves obug, which also enables vite logging. It's a mess. I wanted to keep users out of it. Perhaps we could mention how our/users logging interact with debug logging
• silent logging isn't really a level that you want to configure and/or use, right? Specifically Astro.logger.silent. Perhaps we could expand the docs of --silent to explain that users logs are hidden too

[ArmandPhilippot]

Well, I was referring to levels because this is a value allowed by AstroLoggerLevel. Naming... 😄 But, yeah, I agree those are not levels. I just feel there is something missing and that could be confusing for the users too.

Maybe this section is fine as it is because this is about the real levels. And, maybe, the AstroLoggerLevel description should be reworked a little instead? I mean to link the possible values ​​and what they refer to. This way we can link back to the Log Level section for info, warn, and error, and to the CLI flags for silent and debug.

I'm not yet sure about the wording to make a suggestion (too late to have a clear head 😴 ) but it might make more sense than updating the Log level section...

But, yes, updating --silent sounds like a good idea!

[ematipico]

I'll look into it, we shouldn't provide silent and debug levels to the user

[ArmandPhilippot]

So, what I meant last night in #13907 (comment) was that the AstroLoggerLevel section could look something like this:

Suggested change

	### `AstroLoggerLevel`
	<p>
	**Type:** `'debug' |'info' |'warn' | 'error' | 'silent'`
	</p>
	Specifies the verbosity level of logs:
	- `info`, `warn`, and `error`: defines the minimal [log level](#log-level) to print.
	- `silent`: this is equivalent to the [`--silent` CLI flag](/en/reference/cli-reference/#--silent) and enables silent logging.
	- `debug`: this is equivalent to the [`--debug` CLI flag](/en/reference/cli-reference/#--verbose) and enables verbose logging, including Vite logging.