advanced-usage.mdx

title	Advanced Usage
sidebar_order	20
description	Learn about adding extra data using the MDC system provided by Logback.

It’s possible to add extra data to events thanks to the MDC system provided by Logback.

Mapped Tags

By default all MDC parameters are stored under the “MDC” tab in Sentry.

import org.slf4j.MDC;

void logWithExtras() {
  // MDC extras
  MDC.put("Environment", "Development");
  MDC.put("OS", "Linux");

  // This sends an event where the Environment and OS MDC values are set as MDC entries
  logger.error("This is a test");
}

import org.slf4j.MDC

fun logWithExtras() {
  // MDC extras
  MDC.put("Environment", "Development")
  MDC.put("OS", "Linux")

  // This sends an event where the Environment and OS MDC values are set as MDC entries
  logger.error("This is a test")
}

Note that MDC manages data on a per-thread basis, and that a child thread does not automatically inherit MDC properties from its parent.

In Practice

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;

public class MyClass {
  private static final Logger logger = LoggerFactory.getLogger(MyClass.class);

  void logSimpleMessage() {
    // This sends a simple event to Sentry
    logger.error("This is a test");
  }

  void logWithBreadcrumbs() {
    // Record a breadcrumb that will be sent with the next event(s),
    // by default the last 100 breadcrumbs are kept.
    Sentry.addBreadcrumb("User made an action");

    // Log entries below `minimumEventLevel` and above or equal to `minimumBreadcrumbLevel`
    // are recorded as breadcrumbs
    logger.info("User made another action");

    // This sends a simple event to Sentry
    logger.error("This is a test");
  }

  void logWithExtras() {
    // MDC extras
    MDC.put("extra_key", "extra_value");
    // This sends an event with extra data to Sentry
    logger.error("This is a test");
  }

  void logException() {
    try {
      unsafeMethod();
    } catch (Exception e) {
      // This sends an exception event to Sentry
      logger.error("Exception caught", e);
    }
  }

  void unsafeMethod() {
    throw new UnsupportedOperationException("You shouldn't call this!");
  }
}

import io.sentry.core.Sentry
import org.slf4j.LoggerFactory
import org.slf4j.MDC

class MyClass {
  companion object {
    private val logger = LoggerFactory.getLogger(Main::class.java)
  }

  fun logSimpleMessage() {
    // This sends a simple event to Sentry
    logger.error("This is a test")
  }

  fun logWithBreadcrumbs() {
    // Record a breadcrumb that will be sent with the next event(s),
    // by default the last 100 breadcrumbs are kept.
    Sentry.addBreadcrumb("User made an action")

    // Log entries below `minimumEventLevel` and above or equal to `minimumBreadcrumbLevel`
    // are recorded as breadcrumbs
    logger.info("User made another action")

    // This sends a simple event to Sentry
    logger.error("This is a test")
  }

  fun logWithExtras() {
    // MDC extras
    MDC.put("extra_key", "extra_value")
    // This sends an event with extra data to Sentry
    logger.error("This is a test")
  }

  fun logException() {
    try {
      unsafeMethod()
    } catch (e: Exception) {
      // This sends an exception event to Sentry
      logger.error("Exception caught", e)
    }
  }

  fun unsafeMethod() {
    throw UnsupportedOperationException("You shouldn't call this!")
  }
}

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.

As of Sentry Java SDK version 8.24.0, contextTags also applies to structured 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.

  <appender name="sentry" class="io.sentry.logback.SentryAppender">
    <options>
      <!-- NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry project/dashboard -->
      <dsn>___PUBLIC_DSN___</dsn>
      <contextTag>userId</contextTag>
      <contextTag>requestId</contextTag>
    </options>
  </appender>

When you call MDC.put("userId", "myUserId") with the above configuration in place, the userId will show up as a tag on the event in the Sentry UI.