Skip to content

feat(logs): add macro-based API#827

Merged
lcian merged 55 commits intomasterfrom
lcian/feat/logs-macros
Jun 6, 2025
Merged

feat(logs): add macro-based API#827
lcian merged 55 commits intomasterfrom
lcian/feat/logs-macros

Conversation

@lcian
Copy link
Copy Markdown
Member

@lcian lcian commented Jun 4, 2025 •
edited
Loading

Adds logging macros.

As described in the doc strings, there are technically 4 variants:

  • logging a simple message
  • logging a message with format string and args, forwards to format!
  • the two cases above but with any number of attributes coming before the message and args. The syntax is similar to the one used in tracing, but we only support the values that can be converted to a serde_json::Value.
    Full example:
warn!(
    error_code = 500,
    user.id = "12345",
    user.email = "test@test.com",
    success = false,
    "Error occurred: {}",
    "bad input"
);

Attributes containing a . will be nested in the UI.

The biggest difference with this and the tracing API is that we don't currently support an arbitrary struct as attribute. The way it works there is that it will work with any type implementing Display, calling it to get a string representation of the value, or with the special syntax ? it will call the Debug impl.

Initially I split this into various internal macros but then they would be exported too, so I've refactored it to only export the needed APIs. This leads to some repetition in the various branches.

The spec says the logging API should be available under a logger namespace.
However it doesn't look there's a way to re-export the macros only under a specific mod, it seems that with macro_export they will always be exported at the crate level too (e.g. sentry::error!).
So for now I'm just exporting them at top level.

@lcian lcian requested review from Swatinem and szokeasaurusrex June 4, 2025 17:26
@lcian
Copy link
Copy Markdown
Member Author

lcian commented Jun 4, 2025

@codecov-ai-reviewer review

@ghost
Copy link
Copy Markdown

ghost commented Jun 4, 2025

On it! We are reviewing the PR and will provide feedback shortly.

@ghost
Copy link
Copy Markdown

ghost commented Jun 4, 2025

PR Description

This pull request introduces a macro-based API for capturing structured logs within the Sentry Rust SDK. The primary goal is to provide a convenient and expressive way for developers to record log messages with associated attributes, enabling richer context and improved debugging capabilities within the Sentry platform.

Click to see more

Key Technical Changes

The key technical changes include: 1) Creation of a new logs.rs module in sentry-core containing the log!, trace!, debug!, info!, warn!, error!, and fatal! macros. These macros allow capturing log messages at different severity levels with support for formatted messages and structured attributes. 2) Modification of sentry-core/src/lib.rs to conditionally include the logs module based on the UNSTABLE_logs feature flag. 3) Addition of new test cases in sentry/tests/test_basic.rs to verify the correct behavior of the logging macros, including message formatting and attribute handling. The capture_log method in the Hub is used to send the logs.

Architecture Decisions

The architectural decisions involve using a macro-based API to provide a user-friendly logging interface. The macros leverage the Hub::current() to access the current Sentry hub and capture logs. The design supports structured attributes by parsing key-value pairs within the macro invocation and storing them in a Map within the Log structure. The use of the UNSTABLE_logs feature flag allows for controlled experimentation and prevents breaking changes in stable releases.

Dependencies and Interactions

This pull request depends on the sentry-types crate for the LogLevel and LogAttribute types. It interacts with the Hub structure in sentry-core to capture and send log messages. The new logging macros are designed to be independent of existing logging frameworks but can be integrated with them by routing log messages to the Sentry macros.

Risk Considerations

Potential risks include: 1) The UNSTABLE_logs feature flag indicates that the API is not yet finalized and may be subject to breaking changes. 2) Macro-based APIs can be complex to debug and maintain. 3) Performance overhead of macro expansion and attribute parsing should be considered, especially in high-volume logging scenarios. 4) The limitation of 8 dots in nested attributes could be restrictive and should be clearly documented. 5) Ensure thread safety of Hub::current() and capture_log method.

Notable Implementation Details

The log! macro uses a recursive internal macro (@internal) to handle attribute parsing. The macro supports simple messages, formatted messages, and messages with attributes. The attributes are stored in a Map<String, LogAttribute> within the Log structure. The sentry.message.template and sentry.message.parameter.* attributes are automatically added for formatted messages. The tests use sentry::test::with_captured_envelopes_options to capture and verify the generated Sentry envelopes.

ghost
ghost reviewed Jun 4, 2025
View reviewed changes
Comment thread sentry-core/src/logs.rs Outdated
ghost
ghost reviewed Jun 4, 2025
View reviewed changes
Comment thread sentry-core/src/logs.rs Outdated
ghost
ghost reviewed Jun 4, 2025
View reviewed changes
Comment thread sentry-core/src/logs.rs Outdated
ghost
ghost reviewed Jun 4, 2025
View reviewed changes
Comment thread sentry-core/src/logs.rs Outdated
ghost
ghost reviewed Jun 4, 2025
View reviewed changes
Comment thread sentry-core/src/logs.rs Outdated
ghost
ghost reviewed Jun 4, 2025
View reviewed changes
Comment thread sentry-core/src/logs.rs Outdated
ghost
ghost reviewed Jun 4, 2025
View reviewed changes
Comment thread sentry/tests/test_basic.rs
Swatinem
Swatinem approved these changes Jun 4, 2025
View reviewed changes
Comment thread sentry-core/src/logs.rs Outdated
Comment thread sentry-core/src/logs.rs Outdated
szokeasaurusrex
szokeasaurusrex approved these changes Jun 5, 2025
View reviewed changes
Copy link
Copy Markdown
Member

@szokeasaurusrex szokeasaurusrex left a comment

Choose a reason for hiding this comment

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

I only reviewed the API, not the macro implementation. I left some comments – I highly recommend you follow my suggestions, but I am also okay with merging this PR without changes as it is guarded by an unstable feature flag

Comment thread sentry-core/src/lib.rs Outdated
Comment thread sentry-core/src/logs.rs Outdated
Comment thread sentry-core/src/logs.rs Outdated
Comment thread sentry-core/src/logs.rs Outdated
Comment thread sentry-core/src/logs.rs Outdated
Comment thread sentry-core/src/logs.rs Outdated
Comment thread sentry-core/src/logs.rs Outdated
Comment thread sentry-core/src/logs.rs Outdated
Comment thread sentry/tests/test_basic.rs
Comment thread CHANGELOG.md Outdated
@lcian @szokeasaurusrex
Update CHANGELOG.md
27547c4 
Co-authored-by: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com>
@codecov
Copy link
Copy Markdown

codecov bot commented Jun 5, 2025 •
edited
Loading

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 72.61%. Comparing base (d668e7d) to head (d0abc4a).
Report is 1 commits behind head on master.

Additional details and impacted files 
@@           Coverage Diff           @@
##           master     #827   +/-   ##
=======================================
  Coverage   72.61%   72.61%           
=======================================
  Files          63       63           
  Lines        7598     7598           
=======================================
  Hits         5517     5517           
  Misses       2081     2081
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@lcian lcian linked an issue Jun 6, 2025 that may be closed by this pull request
[Structured logging] Macros #824
Closed
Base automatically changed from lcian/feat/logs-api to master June 6, 2025 08:04
@lcian lcian merged commit be2e04e into master Jun 6, 2025
18 checks passed
@lcian lcian deleted the lcian/feat/logs-macros branch June 6, 2025 08:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@szokeasaurusrex szokeasaurusrex szokeasaurusrex approved these changes

+2 more reviewers

@Swatinem Swatinem Swatinem approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Structured logging] Macros

3 participants

@lcian @Swatinem @szokeasaurusrex