Review of log level usage: promote certain trace! logs to info! to improve observability

[ognis1205]

As seen in issues like #1189 and #1181, it appears that some log messages that could aid in understanding git-cliff’s behavior or detecting misconfigurations early are currently logged at the trace! level.

This effectively hides them unless users explicitly pass -vv, which might not be intuitive for many users and may hinder:

• Early detection of configuration or tagging issues
• Understanding how git-cliff is interpreting tags, commits, or configs
• General user confidence in how git-cliff is working under the hood

💡 Proposal

Review current trace! log usage and consider promoting messages that reflect high-level behavior (e.g., tag skipping, changelog generation decisions, applied filters) to info!.

This would make git-cliff -v (or even no -v) much more informative without overwhelming the user, while still preserving trace! for deeply internal logic.

✅ Benefits

• Easier for users to understand what git-cliff is doing
• Faster troubleshooting

[orhun]

That's actually a pretty good idea! I would love to see this happen :D

Do you have time/interest to work on this after the upcoming release maybe?

[ognis1205]

Sounds good — I’m happy to take this on after the upcoming release!

Before that, I’ll put together a quick guideline on what kind of logs we want and at what level, and share it here so we’re on the same page.

[orhun]

Sounds perfect, thanks!

[ognis1205]

TODO: Reminder to initiate this task following the release.

[orhun]

Yeah, would be nice to have this for the next release!

[ognis1205]

Just a reminder: I’m planning to open a PR related to this discussion within the next few days.

[ognis1205]

Basic Guidelines

• error! -> Represents a critical failure
  • When the program cannot or should not continue
  • Example: Corrupted configuration file, fatal initialization failure
• warn! -> Indicates a problematic state, but the system continues running
  • When something unexpected happens but execution can still continue
  • Example: Use of deprecated settings, retryable failure, partial data loss
• info! -> General informational messages
  • When you want to inform users or operators about normal system operations
  • Example: Job completion, successful connection to an external service
• debug! -> Diagnostic messages for debugging
  • When you want to output internal state useful for development or troubleshooting
  • Example: Loaded configuration values, branch selection during processing
• trace! -> Highly detailed, step-by-step tracing
  • When you want to trace the execution flow step by step (usually for development or investigation only)
  • Example: Function entry/exit, detailed loop progress

Check List

• git-cliff/src/bin/completions.rs
• git-cliff/src/bin/mangen.rs
• git-cliff/src/args.rs
• git-cliff/src/lib.rs
• git-cliff/src/logger.rs
• git-cliff/src/main.rs
• git-cliff/src/profiler.rs
• git-cliff-core/src/remote/bitbucket.rs
• git-cliff-core/src/remote/gitea.rs
• git-cliff-core/src/remote/github.rs
• git-cliff-core/src/remote/gitlab.rs
• git-cliff-core/src/remote/mod.rs
• git-cliff-core/src/changelog.rs
• git-cliff-core/src/command.rs
• git-cliff-core/src/commit.rs
• git-cliff-core/src/config.rs
• git-cliff-core/src/contributor.rs
• git-cliff-core/src/embed.rs
• git-cliff-core/src/error.rs
• git-cliff-core/src/lib.rs
• git-cliff-core/src/release.rs
• git-cliff-core/src/repo.rs
• git-cliff-core/src/statistics.rs
• git-cliff-core/src/tag.rs
• git-cliff-core/src/template.rs

[ognis1205]

Hey @orhun ,

I am considering migrating from env_logger to tracing and tracing-subscriber for the following reasons:

• Spans: Logs have a start and end time, forming a tree of nested events that capture the journey of a request through different system components.
• Structured data: tracing supports richer data for events and spans, allowing for more detailed analysis.
• Causality and temporality: It captures the temporal relationships between events and the causal flow of execution, which is essential for understanding complex interactions.
• Function-level instrumentation: Using the #[instrument] attribute, tracing can automatically include function arguments and return values in logs, making it easy to trace the flow of execution across functions.

For these reasons, I believe that moving from env_logger to tracing and tracing-subscriber is appropriate. What do you think?

[orhun]

Sure, that's reasonable.

Please note that I'm using env_logger in a special way. It triggers the progress bar for fetching the data for the remotes. See the logger module for more details.

I think the first step would be to get rid of env_logger and find a less hacky solution. It's the same reason why I can't update env_logger dependency because something has changed in the new version and that's not compatible with how I use their API as of now.