feat(logs): add macro-based API

[lcian]

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 = "[email protected]",
    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]

@codecov-ai-reviewer review

[codecov-ai]

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

[codecov-ai]

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.

[szokeasaurusrex]

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

[codecov]

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.