Skip to content

feat(java): Document contextTags for logs #15245

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
merged 6 commits into from
Oct 21, 2025
Merged

feat(java): Document contextTags for logs #15245

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c9334f6
feat(java): Document contextTags for logs
lcian Oct 16, 2025
69adeab
Merge branch 'master' into lcian/feat/java-context-tags-logs
lcian Oct 16, 2025
6c622a4
Update advanced-usage.mdx
lcian Oct 21, 2025
6c3dd2e
Update advanced_usage.mdx
lcian Oct 21, 2025
7234244
Add context-tags configuration for Sentry
lcian Oct 21, 2025
e770789
Merge branch 'master' into lcian/feat/java-context-tags-logs
lcian Oct 21, 2025
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
5 changes: 4 additions & 1 deletion docs/platforms/java/guides/jul/usage/advanced-usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,8 +158,11 @@ class MyClass {

## Context Tags

Starting with Sentry version 6.0.0 and up, you can define a list of `MDC tags` that will be viewable as `Tags` in the Sentry UI. `MDC Tags` not in this list will be viewable as `Context Data`. To define tags, add a `context-tags` entry with the tags as comma-separated items to the `sentry.properties` file.
Starting with Sentry version 6.0.0 and up, you can define a list of `MDC tags` that will be viewable as `Tags` in the Sentry UI. `MDC Tags` not in this list will be viewable as `Context Data`.

As of Sentry Java SDK version 8.24.0, `contextTags` also applies to [structured logs](https://docs.sentry.io/product/explore/logs/). MDC properties matching the configured `contextTags` will be attached to log entries as attributes, prefixed with "mdc.".

To define a tag that shall be sent with events and logs, add a `context-tags` entry with the tags as comma-separated items to the `sentry.properties` file.

```properties {tabTitle:Properties}
dsn=___PUBLIC_DSN___
Expand Down
5 changes: 4 additions & 1 deletion docs/platforms/java/guides/log4j2/advanced_usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,8 +141,11 @@ class MyClass {

## Context Tags

Starting with Sentry version 6.0.0 and up, you can define a list of `MDC tags` that will be viewable as `Tags` in the Sentry UI. `MDC Tags` not in this list will be viewable as `Context Data`. To define tags, add a `contextTags` attribute to the `<Sentry>` tag in your `log4j2.xml` with the tags as comma-separated items.
Starting with Sentry version 6.0.0 and up, you can define a list of `MDC tags` that will be viewable as `Tags` in the Sentry UI. `MDC Tags` not in this list will be viewable as `Context Data`.

As of Sentry Java SDK version 8.24.0, `contextTags` also applies to [structured logs](https://docs.sentry.io/product/explore/logs/). MDC properties matching the configured `contextTags` will be attached to log entries as attributes, prefixed with "mdc.".

To define a tag that shall be sent with events and logs, add a `contextTags` attribute to the `<Sentry>` tag in your `log4j2.xml` with the tags as comma-separated items.

```xml {tabTitle:XML}
<Sentry name="Sentry"
Expand Down
5 changes: 4 additions & 1 deletion docs/platforms/java/guides/logback/usage/advanced-usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,8 +140,11 @@ class MyClass {

## Context Tags

Starting with Sentry version 6.0.0 and up, you can define a list of `MDC tags` that will be viewable as `Tags` in the Sentry UI. `MDC Tags` not in this list will be viewable as `Context Data`. To define a tag, add a `<contextTag>` entry inside the `<options>` of the Sentry appender configuration in `logback.xml`
Starting with Sentry version 6.0.0 and up, you can define a list of `MDC tags` that will be viewable as `Tags` in the Sentry UI. `MDC Tags` not in this list will be viewable as `Context Data`.

As of Sentry Java SDK version 8.24.0, `contextTags` also applies to [structured logs](https://docs.sentry.io/product/explore/logs/). MDC properties matching the configured `contextTags` will be attached to log entries as attributes, prefixed with "mdc.".

To define a tag that shall be sent with events and logs, add a `<contextTag>` entry inside the `<options>` of the Sentry appender configuration in `logback.xml`.

```xml {tabTitle:XML}
<appender name="sentry" class="io.sentry.logback.SentryAppender">
Expand Down
8 changes: 8 additions & 0 deletions docs/platforms/java/guides/spring-boot/logging-frameworks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,10 @@ However, if errors that may appear during startup should to be sent to Sentry, t

</Alert>

#### Mapped Diagnostic Context (MDC)

Starting with Sentry Java SDK version 8.24.0, you can use the <PlatformLink to="/configuration/options/#contextTags">`contextTags`</PlatformLink> option to include specific properties from the Mapped Diagnostic Context (MDC) as attributes on log entries sent to Sentry.

### Log4j 2

To use Sentry's Log4j 2 integration in Spring Boot application, you must include a dependency to the `sentry-log4j2` module:
Expand Down Expand Up @@ -125,3 +129,7 @@ You do not need to configure your DSN in the Log4j 2 configuration file since Se
However, if errors that may appear during startup should to be sent to Sentry, the DSN must be provided to <i>both</i> the Log4j 2 and Spring Boot configurations.

</Alert>

#### Mapped Diagnostic Context (MDC)

Starting with Sentry Java SDK version 8.24.0, you can use the <PlatformLink to="/configuration/options/#contextTags">`contextTags`</PlatformLink> option to include specific properties from the Mapped Diagnostic Context (MDC) as attributes on log entries sent to Sentry.
6 changes: 6 additions & 0 deletions platform-includes/logs/options/java.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,9 @@ Sentry.init { options ->


The `beforeSend` function receives a log object, and should return the log object if you want it to be sent to Sentry, or `null` if you want to discard it.

#### contextTags

You can use the <PlatformLink to="/configuration/options/#contextTags">`contextTags`</PlatformLink> option to include specific properties from the Mapped Diagnostic Context (MDC) as attributes on log entries sent to Sentry.

For detailed configuration examples, see the Advanced Usage documentation for your logging framework.
Loading