Send Log4j2 logs to Sentry as logs

[adinauer]

📜 Description

Allow setting a minimumLevel to our Log4j2 integration which causes logs >= that level to be sent to Sentry as logs.

Setting the minimum level can be done on the appender config in log4j2.xml:

<Sentry name="Sentry"
        dsn="your DSN"
        minimumBreadcrumbLevel="DEBUG"
        minimumEventLevel="WARN"
        minimumLevel="DEBUG"
        debug="true"
        contextTags="userId,requestId"
/>

You also have to enable the logs feature:

Either in sentry.properties:

logs.enabled=true

or when calling Sentry.init:

Sentry.init(options -> {
  ...
  options.getLogs().setEnabled(true);
});

💡 Motivation and Context

Closes #4403

💚 How did you test it?

📝 Checklist

• I added tests to verify the changes.
• No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
• I updated the docs if needed.
• I updated the wizard if needed.
• Review from the native team if needed.
• No breaking change or entry added to the changelog.
• No breaking change for hybrid SDKs or communicated to hybrid SDKs.

🔮 Next steps

[github-actions]

	Fails
🚫	Please consider adding a changelog entry for the next release.

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Instructions and example for changelog

Please add an entry to CHANGELOG.md to the "Unreleased" section. Make sure the entry includes this PR's number.

Example:

## Unreleased

- Send Log4j2 logs to Sentry as logs ([#4517](https://github.com/getsentry/sentry-java/pull/4517))

If none of the above apply, you can opt out of this check by adding #skip-changelog to the PR description.

Generated by 🚫 dangerJS against 0bd63c4

[github-actions]

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	453.72 ms	519.69 ms	65.97 ms
Size	1.58 MiB	2.09 MiB	519.08 KiB

[lcian]

strange diff, it looked like you added something to deprecate it immediately lol

[adinauer]

@sentry review

[seer-by-sentry]

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

[seer-by-sentry]

PR Description

This pull request introduces the ability to capture log messages directly as Sentry logs, in addition to the existing functionality of capturing log events as Sentry events. This allows users to leverage Sentry's logging infrastructure for structured logging and analysis, independent of error reporting.

Click to see more

Key Technical Changes

A new minimumLevel parameter is added to the SentryAppender to control the minimum log level for capturing logs. A captureLog method is introduced to create and send Sentry logs from Log4j2's LogEvent. A toSentryLogLevel method is added to convert Log4j2's Level to Sentry's SentryLogLevel. The append method is modified to check the log level against both minimumLevel (for capturing logs) and minimumEventLevel (for capturing events).

Architecture Decisions

The decision was made to use Sentry's existing logging API (Sentry.logger().log()) to capture the log messages. This ensures consistency with other Sentry logging integrations and allows users to leverage Sentry's features for log analysis. The SentryAttributes class is used to add the log message template to the log context.

Dependencies and Interactions

This change depends on the Sentry Java SDK's logging API. It interacts with the existing event capturing mechanism in SentryAppender by adding a new log capturing path. It also interacts with the Log4j2 framework to receive log events.

Risk Considerations

Introducing a new logging path could potentially increase the volume of data sent to Sentry, which might impact performance and billing. Users should carefully configure the minimumLevel parameter to avoid capturing excessive logs. There's also a risk of inconsistencies between the captured logs and events if the log levels are not configured properly. The level comparison logic uses isMoreSpecificThan which means it will capture logs at MORE specific levels, not equal or more specific. This might be counterintuitive.

Notable Implementation Details

The captureLog method extracts the formatted message and parameters from the LogEvent and sends them to Sentry as a log message. The toSentryLogLevel method maps Log4j2's Level to Sentry's SentryLogLevel. The deprecated constructor is kept for backward compatibility but marked as deprecated.

[seer-by-sentry]

The deprecated constructor should include proper JavaDoc explaining the migration path and when it will be removed. Consider adding a @since and @removal tag to provide clear versioning information.

Suggested change

	/**
	* @deprecated please use the non deprecated constructor instead.
	*/
	@Deprecated
	@SuppressWarnings("InlineMeSuggester")
	public SentryAppender(
	final @NotNull String name,
	final @Nullable Filter filter,
	final @Nullable String dsn,
	final @Nullable Level minimumBreadcrumbLevel,
	final @Nullable Level minimumEventLevel,
	/**
	* @deprecated This constructor is deprecated. Please use {@link #SentryAppender(String, Filter, String, Level, Level, Level, Boolean, ITransportFactory, IScopes, String[])} instead.
	* @since 7.0.0
	* @removal 8.0.0
	*/
	@Deprecated
	@SuppressWarnings("InlineMeSuggester")