Port logging to `log` #3042

kleinesfilmroellchen · 2025-12-11T23:50:36Z

As per discussion in #3038 (comment), we want to move to using log for all of our logging needs. This PR does both the backend work, and also adds an env_logger configured with:

default level zola=info, so that only Zola’s output is visible by default (and no debugging)
respecting terminal color configuration (CLICOLOR/NO_COLOR/terminal detection etc.)
simple output format <Level> <Message> matching mdBook, except for INFO which only prints the message

Also migrate to anstyle which is more flexible than termcolor and also provides a utility for color mode auto-detection.

Caveats:

Some commands have slightly changed output (e.g.
removed “warning” text for log::warn), but a lot
of them might still contain formatting symbols
like “->” and “>”.
Init command (and its tooling) is unchanged, as
it should be a nice interactive command.
There is no log::success, so the success-info
distinction has been lost in some places.
Separate prints close to each other have been
transformed into one log call each. They might
look less related than they did before.
No new logging is added. Many components might
benefit from extra logging within them.

Sanity check:

Have you checked to ensure there aren't other open Pull Requests for the same update/change?

Code changes

(Delete or ignore this section for documentation changes)

Are you doing the PR on the next branch?

If the change is a new feature or adding to/changing an existing one:

Have you created/updated the relevant documentation page(s)?

Keats

I think this is a bit too much. A lot of it that we always want to show should stay as println. I think logs is going to be used mostly for perf/what's happening at the info level and warnings like in your PR. I don't have a clear view of what it would look like yet but I'm fairly sure everything we're printing during a normal run (such as link checking, timing etc) should stay println

components/site/src/lib.rs

Keats · 2025-12-12T08:15:23Z

components/site/src/link_checking.rs

            });

-            println!(
+            log::info!(


i think all that functions should stay println? it's stuff we always want the end user to see, logs should be reserved to things like debugging or warnings

As long as the logging framework is configured correctly, it’s very easy to always show these messages. Possibly using a special target for log.

Keats · 2025-12-12T08:16:00Z

src/cmd/serve.rs

                let local_addr = listener.local_addr().unwrap();

-                println!(
+                log::info!(


anything in src should stay println/eprintln

kleinesfilmroellchen · 2025-12-12T13:39:28Z

I take issue with the current printing approach because it is sometimes hard to guess which subsystem is doing what unless the messages are very clear, and whether certain messages are even related. mdbook, which has a very similar CLI to zola, also uses log for printing its regular CLI output, using only a very basic style that includes the warning level and the message. (Technically, they use tracing, which is basically just a more advanced log. See e.g. here.)

Keats · 2025-12-13T20:21:56Z

it is sometimes hard to guess which subsystem is doing what unless the messages are very clear

I don't want the classic [2017-11-09T02:12:24Z DEBUG main] for the main output of zola. We can define a basic formatter with env_logger (let's say just the message and changing colour for the level warning/error). We do lose the possibility of putting different colour inside a message but i guess that's fine. Can you add the formatting you had in mind in this PR as well?

kleinesfilmroellchen · 2025-12-14T11:05:57Z

it is sometimes hard to guess which subsystem is doing what unless the messages are very clear

I don't want the classic [2017-11-09T02:12:24Z DEBUG main] for the main output of zola.

Me neither!

We can define a basic formatter with env_logger (let's say just the message and changing colour for the level warning/error). We do lose the possibility of putting different colour inside a message but i guess that's fine.

I’m fairly certain you can still inject ANSI codes into the log message, AFAIK there’s quite a bit of support around that (color macros, detecting terminal color support, etc.). I’m not sure where we do that right now though, didn’t see it when going through the print statements. If I missed something please point it out and I’ll definitely add it back.

Can you add the formatting you had in mind in this PR as well?

Okay, so I will add an env_logger with default config (so RUST_LOG works as above) and mdbook-like formatting, no coloring of the message, and colored log level. I won’t add an env_logger to the testing infra or any other binaries that may be floating around, just the main CLI.

Keats · 2025-12-14T14:45:37Z

Cargo.toml

 # For essence_str() function, see https://github.com/getzola/zola/issues/1845
 mime = "0.3.16"
+env_logger = "0.11"
+anstyle = "1"


we are already using termcolor in components/console
It's fine to replace it but let's not have both

Yes we can remove the anstyle dependency, at least when disabling the color feature of env_logger. (That might require us to detect terminals manually tho, I will see.)

After looking into this more, we should use anstyle instead of termcolor. It also has a utility crate (anstream) which provides auto-color-detection, pretty much matching the manual logic in console but more accurate (and compatible with old Windows terminals). So I now also ported console to anstyle which was simple enough.

Keats · 2025-12-14T14:45:50Z

I'll have a look at the output tomorrow

Keats · 2025-12-15T10:30:54Z

Looking at the output:

we should default to showing at least warn when env var not set
no need for INFO label. Ideally no need for WARN label as well but coloring the text is a bit trickier...

kleinesfilmroellchen · 2025-12-15T11:20:23Z

Looking at the output:

1. we should default to showing at least warn when env var not set

I noticed this too earlier when testing, so now we fall back to zola=info as a logging configuration. This prevents other crates from adding their own confusing INFO prints by default (though I have not observed this so far).

2. no need for INFO label. Ideally no need for WARN label as well but coloring the text is a bit trickier...

I personally disagree, but will do

This change ports all println and console::* users to use log::* with the appropriate level. Caveats: - Some commands have slightly changed output (e.g. removed “warning” text for log::warn), but a lot of them might still contain formatting symbols like “->” and “>”. - Init command (and its tooling) is unchanged, as it should be a nice interactive command. - There is no `log::success`, so the success-info distinction has been lost in some places. - Separate prints close to each other have been transformed into one log call each. They might look less related than they did before. - No new logging is added. Many components might benefit from extra logging within them.

As per discussion, this only prints the log level with basic coloring as well as the message. Additionally, replace termcolor by anstyle+anstream which provides accurate terminal detection and more formatting capabilities. (anstyle is already a dependency, and termcolor is mainly present in some older package versions.)

Keats · 2025-12-23T21:25:41Z

Sorry can you rebase? The giallo branch merge created a bunch of conflicts

EvanCarroll · 2025-12-23T23:43:48Z

This doesn't make sense, if you're using Axum and Tokio why aren't you tracing for logging?

Keats · 2025-12-24T20:06:56Z

We wouldn't use anything from tracing other than the logs so it wouldn't make sense to use it

EvanCarroll · 2025-12-24T20:12:56Z

Tracing would allow you to run debugging information on a span covering thinks like shortcode expansion or calls to cmark, and get comprehensive reporting -- when desired -- about what took time in generating the site. It would also allow you to get comprehensive timings for requests and it easily flows with axum/tokio (it's the support mechanism of doing this). Not to mention, I think it's probably already in the req stack somewhere by way of hyper-util and axum. So it's basically more power and free.

If you want a patch to show it off and see, accept my axum patch and I'll provide an alternative for you to A-B.

Keats · 2025-12-24T20:52:28Z

We dont care about the dev server at all for logging. I don't care particularly about spans or instrumenting or multiple sinks either, zola is a basic CLI we can easily handle it with basic logging.

…

On Wed, 24 Dec 2025, 21:13 Evan Carroll, ***@***.***> wrote: *EvanCarroll* left a comment (getzola/zola#3042) <#3042 (comment)> Tracing would allow you to run debugging information on a span covering thinks like shortcode expansion or calls to cmark, and get comprehensive reporting -- when desired -- about what took time in generating the site. It would also allow you to get comprehensive timings for requests and it easily flows with axum/tokio (it's the support mechanism of doing this). Not to mention, I think it's probably already in the req stack somewhere by way of hyper-util and axum. So it's basically more power and free. If you want a patch to show it off and see, accept my axum patch and I'll provide an alternative for you to A-B. — Reply to this email directly, view it on GitHub <#3042 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFGDI4IQLCQ3BVPC6XVDUL4DLXV3AVCNFSM6AAAAACOZMQKWSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMOJQGQ2TCOJVGQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

EvanCarroll · 2025-12-24T21:06:00Z

I'm not trying to be standoffish and it's not just about the dev server either (though I don't know why you wouldn't want the things you don't care about).

It's no more difficult to use the free macros in tracing and.
The framework is already in use by our deps.
It will allow you to benchmark across async tasks and provide debugging about compilation speed.

It's literally switching log::info! to tracing::info!. There is even a note about migration to tracing from log just to ease the difficulty since everyone is moving that direction https://docs.rs/tracing/latest/tracing/#for-log-users

Keats · 2025-12-26T13:33:01Z

I'll well aware of tracing, but since we won't use any of it right now, there's no point adding it. As you said, it's easy to swap later if we want to

kleinesfilmroellchen force-pushed the logging branch from 318a6fc to 9f8e045 Compare December 11, 2025 23:52

Keats requested changes Dec 12, 2025

View reviewed changes

Keats reviewed Dec 14, 2025

View reviewed changes

kleinesfilmroellchen force-pushed the logging branch from 7f9c5f7 to 7555bbd Compare December 15, 2025 11:16

kleinesfilmroellchen force-pushed the logging branch 2 times, most recently from d781f82 to 433e75f Compare December 15, 2025 11:47

kleinesfilmroellchen added 3 commits December 15, 2025 12:48

Add documentation for using RUST_LOG

083ded1

kleinesfilmroellchen force-pushed the logging branch from 433e75f to 083ded1 Compare December 15, 2025 11:48

Port logging to log #3042

Are you sure you want to change the base?

Port logging to log #3042

Uh oh!

Conversation

kleinesfilmroellchen commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code changes

Uh oh!

Keats left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Keats Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

kleinesfilmroellchen Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

Keats Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

kleinesfilmroellchen commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Keats commented Dec 13, 2025

Uh oh!

kleinesfilmroellchen commented Dec 14, 2025

Uh oh!

Keats Dec 14, 2025

Choose a reason for hiding this comment

Uh oh!

kleinesfilmroellchen Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

kleinesfilmroellchen Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

Keats commented Dec 14, 2025

Uh oh!

Keats commented Dec 15, 2025

Uh oh!

kleinesfilmroellchen commented Dec 15, 2025

Uh oh!

Keats commented Dec 23, 2025

Uh oh!

EvanCarroll commented Dec 23, 2025

Uh oh!

Keats commented Dec 24, 2025

Uh oh!

EvanCarroll commented Dec 24, 2025

Uh oh!

Keats commented Dec 24, 2025 via email

Uh oh!

EvanCarroll commented Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Keats commented Dec 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Port logging to `log` #3042

Port logging to `log` #3042

kleinesfilmroellchen commented Dec 11, 2025 •

edited

Loading

kleinesfilmroellchen commented Dec 12, 2025 •

edited

Loading

EvanCarroll commented Dec 24, 2025 •

edited

Loading