Skip to content

doc: Fix logging documentation examples and add macro explanation #342

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xerial merged 4 commits into from
Jan 20, 2026
Merged

doc: Fix logging documentation examples and add macro explanation #342

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
61aa85c
doc: Fix logging documentation examples and add macro explanation
claude Jan 20, 2026
49e07c0
doc: Fix timestamp format to include milliseconds and timezone
claude Jan 20, 2026
941c380
doc: Fix log level to lowercase and use timezone offset
claude Jan 20, 2026
93662b0
doc: Remove unnecessary isDebugEnabled example
claude Jan 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions docs/core/logging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,30 +69,30 @@ catch
error(s"Unexpected error: ${e.getMessage}", e)
```

## Conditional Logging
## Zero-Overhead Logging with Scala Macros

Avoid expensive computations when log level is disabled:
The logging methods use Scala 3 `inline` macros, which means:
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This is a great explanation of the benefits of using macros. To further help readers who might not be familiar with this Scala 3 feature, consider adding a link to the official documentation for inline macros. This will provide valuable context for those who want to understand the underlying mechanism.

Suggested change
The logging methods use Scala 3 `inline` macros, which means:
The logging methods use Scala 3 [`inline` macros](https://docs.scala-lang.org/scala3/reference/metaprogramming/inline.html), which means:


```scala
if logger.isDebugEnabled then
debug(s"Expensive computation: ${computeDetails()}")
```

Or use by-name parameters (evaluated lazily):
1. **Automatic lazy evaluation**: The message is only evaluated if the log level is enabled
2. **Zero overhead**: If the log level is disabled, there is no runtime cost for creating log messages

```scala
// expensiveComputation() is only called if DEBUG is enabled
debug(s"Result: ${expensiveComputation()}")
// Only computed if DEBUG is enabled
```

Unlike traditional logging frameworks, you don't need to wrap expensive computations with level checks.

## Source Location

Log messages automatically include source location:
Log messages automatically include source location at the end of the message:

```
2024-01-15 10:30:45 INFO [MyService.scala:25] Processing: data
2024-01-15 10:30:45.123+0900 info [MyService] Processing: data - (MyService.scala:14)
```

The source code location `(file:line)` is captured at compile time using Scala macros.

## Best Practices

1. **Use appropriate levels** - Don't log everything as INFO
Expand Down
Loading