---
title: "Configuration"
description: "Learn more about how to configure the SDK. These options are set when the SDK is first initialized, passed to the init method as an object."
url: https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration/
---

# Configuration | Sentry for Log4j 2.x

##### Note

A new Java SDK has superseded this deprecated version. Sentry preserves this documentation for customers using the old client. We recommend using the [updated Java SDK](https://docs.sentry.io/platforms/java.md) for new projects.

## [Setting the DSN (Data Source Name)](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#setting-the-dsn-data-source-name)

The DSN is the first and most important thing to configure because it tells the SDK where to send events. You can find your project’s DSN in the “Client Keys” section of your “Project Settings” in Sentry. It can be configured in multiple ways. Explanations of the [configuration methods are detailed below](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#configuration-methods).

In a properties file on your filesystem or classpath (defaults to `sentry.properties`):

`sentry.properties`

```text
dsn=___PUBLIC_DSN___
```

Via the Java System Properties *(not available on Android)*:

```bash
java -Dsentry.dsn=___PUBLIC_DSN___ -jar app.jar
```

Via a System Environment Variable *(not available on Android)*:

```bash
SENTRY_DSN=___PUBLIC_DSN___ java -jar app.jar
```

In code:

```java
import io.sentry.Sentry;

Sentry.init("___PUBLIC_DSN___");
```

## [Configuration methods](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#configuration-methods)

There are multiple ways to configure the Java SDK, but all of them take the same options. See below for how to use each configuration method and how the option names might differ between them.

### [Configuration via properties file](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#configuration-via-properties-file)

The Java SDK can be configured via a [.properties file](https://en.wikipedia.org/wiki/.properties) that is located on the filesystem or in your application’s classpath. By default the SDK will look for a `sentry.properties` file in the application’s current working directory or in the root of your classpath. In most server side applications the default directory to add resources to your classpath is `src/main/resources/`, and on Android the default is `app/src/main/resources/`. You can override the location of the properties file by using either the `sentry.properties.file` Java System Property or the `SENTRY_PROPERTIES_FILE` System Environment Variable.

Because this file is often bundled with your application, the values cannot be changed easily once your application has been packaged. For this reason, the properties file is useful for setting defaults or options that you don’t expect to change often. The properties file is the last place checked for each option value, so runtime configuration (described below) will override it if available.

Option names in the property file exactly match the examples given below. For example, to enable sampling, in your properties file:

```properties
sample.rate=0.75
```

### [Configuration via the runtime environment](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#configuration-via-the-runtime-environment)

This is the most flexible method for configuring the Sentry client because it can be easily changed based on the environment you run your application in. *Neither Java System Properties or System Environment Variables are available for Android applications. Please configure Sentry for Android via code or the properties file.*

Two methods are available for runtime configuration, checked in this order: Java System Properties and System Environment Variables.

Java System Property option names are exactly like the examples given below except that they are prefixed with `sentry.`. For example, to enable sampling:

```bash
java -Dsentry.sample.rate=0.75 -jar app.jar
```

System Environment Variable option names require that you replace the `.` with `_`, capitalize them, and add a `SENTRY_` prefix. For example, to enable sampling:

```bash
SENTRY_SAMPLE_RATE=0.75 java -jar app.jar
```

### [Configuration via code](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#configuration-via-code)

The DSN itself can also be configured directly in code:

```java
import io.sentry.Sentry;

Sentry.init("___PUBLIC_DSN___");
```

Sentry **will not** be able to do anything with events until this line is run, so this method of configuration is not recommended if you might have errors occur during startup. In addition, by passing a hardcoded DSN you are no longer able to override the DSN at runtime via Java System Properties or System Environment Variables.

### [Configuration via the DSN](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#configuration-via-the-dsn)

The SDK can also be configured by setting querystring parameters on the DSN itself. This is a bit recursive because your DSN itself is an option that you must set somewhere (and not in the DSN!).

Option names in the DSN exactly match the examples given below. For example, to enable sampling if you are setting your DSN via the environment:

```bash
SENTRY_DSN={DSN}/1?sample.rate=0.75 java -jar app.jar
```

You can, of course, pass this DSN in using the other methods described above.

## [Options](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#options)

The following options can all be configured as described above: via a `sentry.properties` file, via Java System Properties, via System Environment variables, or via the DSN.

### [Release](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#release)

To set the application version that will be sent with each event, use the `release` option:

```bash
release=my-project-name@2.3.12
```

#### [Distribution](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#distribution)

To set the application distribution that will be sent with each event, use the `dist` option:

```bash
release=my-project-name@2.3.12
dist=x86
```

The distribution is only useful (and used) if the `release` is also set.

### [Environment](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#environment)

To set the application environment that will be sent with each event, use the `environment` option:

```bash
environment=staging
```

### [Server Name](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#server-name)

To set the server name that will be sent with each event, use the `servername` option:

```bash
servername=host1
```

### [Tags](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#tags)

To set tags that will be sent with each event, use the `tags` option with comma separated pairs of keys and values that are joined by a colon:

```bash
tags=tag1:value1,tag2:value2
```

### [MDC Tags](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#mdc-tags)

To set tag names that are extracted from the SLF4J MDC system, use the `mdctags` option with comma separated key names. This option is only useful when you're using one of the logging integrations.

```bash
mdctags=foo,bar
```

### [Extra Data](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#extra-data)

To set extra data that will be sent with each event (but not as tags), use the `extra` option with comma separated pairs of keys and values that are joined by a colon:

```bash
extra=key1:value1,key2:value2
```

### [“In Application” Stack Frames](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#in-application-stack-frames)

Sentry differentiates stack frames that are directly related to your application (“in application”) from stack frames that come from other packages such as the standard library, frameworks, or other dependencies. The difference is visible in the Sentry web interface where only the “in application” frames are displayed by default.

You can configure which package prefixes your application uses with the `stacktrace.app.packages` option, which takes a comma separated list.

```bash
stacktrace.app.packages=com.mycompany,com.other.name
```

If you don’t want to use this feature but want to disable the warning, simply set it to an empty string:

```bash
stacktrace.app.packages=
```

#### [Same Frame as Enclosing Exception](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#same-frame-as-enclosing-exception)

Sentry can use the “in application” system to hide frames in chained exceptions. Usually when a StackTrace is printed, the result looks like this:

```bash
HighLevelException: MidLevelException: LowLevelException
        at Main.a(Main.java:13)
        at Main.main(Main.java:4)
Caused by: MidLevelException: LowLevelException
        at Main.c(Main.java:23)
        at Main.b(Main.java:17)
        at Main.a(Main.java:11)
        ... 1 more
Caused by: LowLevelException
        at Main.e(Main.java:30)
        at Main.d(Main.java:27)
        at Main.c(Main.java:21)
        ... 3 more
```

Some frames are replaced by the `... N more` line as they are the same frames as in the enclosing exception.

A similar behavior is enabled by default in Sentry. To disable it, use the `stacktrace.hidecommon` option.

```bash
stacktrace.hidecommon=false
```

### [Event Sampling](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#event-sampling)

Sentry can be configured to sample events with the `sample.rate` option:

```bash
sample.rate=0.75
```

This option takes a number from 0.0 to 1.0, representing the percent of events to allow through to server (from 0% to 100%). By default all events will be sent to the Sentry server.

### [Uncaught Exception Handler](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#uncaught-exception-handler)

By default, an `UncaughtExceptionHandler` is configured that will attempt to send exceptions to Sentry. To disable it, use the `uncaught.handler.enabled` option. Exceptions are sent asynchronously by default, and there is **no guarantee** they will be sent before the JVM exits. This option is best used in conjunction with the disk buffering system described below.

```bash
uncaught.handler.enabled=false
```

### [Buffering Events to Disk](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#buffering-events-to-disk)

Sentry can be configured to write events to a specified directory on disk anytime communication with the Sentry server fails with the `buffer.dir` option. If the directory doesn’t exist, Sentry will attempt to create it on startup and may therefore need write permission on the parent directory. Sentry always requires write permission on the buffer directory itself. This is enabled by default if the `AndroidSentryClientFactory` is used.

```bash
buffer.dir=sentry-events
```

The maximum number of events that will be stored on disk defaults to 10, but can also be configured with the option `buffer.size`:

```bash
buffer.size=100
```

If a buffer directory is provided, a background thread will periodically attempt to re-send the events that are found on disk. By default it will attempt to send events every 60 seconds. You can change this with the `buffer.flushtime` option (in milliseconds):

```bash
buffer.flushtime=10000
```

##### Security Warning

The Java SDK currently uses the native Java serialization system to write out events to the filesystem when buffering is enabled. Due to weaknesses in the Java serialization system it is possible for users that have write access to the `buffer.dir` directory to cause the Java SDK to deserialize arbitrary Java classes. In extreme cases this might lead to the ability to execute code.

#### [Graceful Shutdown of Buffering (Advanced)](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#graceful-shutdown-of-buffering-advanced)

In order to shutdown the buffer flushing thread gracefully, a `ShutdownHook` is created. By default, the buffer flushing thread is given 1 second to shutdown gracefully, but this can be adjusted via `buffer.shutdowntimeout` (represented in milliseconds):

```bash
buffer.shutdowntimeout=5000
```

The special value `-1` can be used to disable the timeout and wait indefinitely for the executor to terminate.

The `ShutdownHook` could lead to memory leaks in an environment where the life cycle of Sentry doesn’t match the life cycle of the JVM.

An example would be in a JEE environment where the application using Sentry could be deployed and undeployed regularly.

To avoid this behavior, it is possible to disable the graceful shutdown by setting the `buffer.gracefulshutdown` option:

```bash
buffer.gracefulshutdown=false
```

### [Async Connection](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#async-connection)

In order to avoid performance issues due to a large amount of logs being generated or a slow connection to the Sentry server, an asynchronous connection is set up, using a low priority thread pool to submit events to Sentry.

To disable the async mode, add `async=false` to your options:

```bash
async=false
```

#### [Graceful Shutdown of Async (Advanced)](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#graceful-shutdown-of-async-advanced)

In order to shutdown the asynchronous connection gracefully, a `ShutdownHook` is created. By default, the asynchronous connection is given 1 second to shutdown gracefully, but this can be adjusted via `async.shutdowntimeout` (represented in milliseconds):

```bash
async.shutdowntimeout=5000
```

The special value `-1` can be used to disable the timeout and wait indefinitely for the executor to terminate.

The `ShutdownHook` could lead to memory leaks in an environment where the life cycle of Sentry doesn’t match the life cycle of the JVM.

An example would be in a JEE environment where the application using Sentry could be deployed and undeployed regularly.

To avoid this behavior, it is possible to disable the graceful shutdown. This might lead to some log entries being lost if the log application doesn’t shut down the `SentryClient` instance nicely.

The option to do so is `async.gracefulshutdown`:

```bash
async.gracefulshutdown=false
```

#### [Async Queue Size (Advanced)](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#async-queue-size-advanced)

The default queue used to store unprocessed events is limited to 50 items. Additional items added once the queue is full are dropped and never sent to the Sentry server. Depending on the environment (if the memory is sparse) it is important to be able to control the size of that queue to avoid memory issues.

It is possible to set a maximum with the option `async.queuesize`:

```bash
async.queuesize=100
```

This means that if the connection to the Sentry server is down, only the 100 most recent events will be stored and processed as soon as the server is back up.

The special value `-1` can be used to enable an unlimited queue. Beware that network connectivity or Sentry server issues could mean your process will run out of memory.

#### [Async Threads Count (Advanced)](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#async-threads-count-advanced)

By default the thread pool used by the async connection contains one thread per processor available to the JVM.

It’s possible to manually set the number of threads (for example if you want only one thread) with the option `async.threads`:

```bash
async.threads=1
```

#### [Async Threads Priority (Advanced)](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#async-threads-priority-advanced)

In most cases sending logs to Sentry isn’t as important as an application running smoothly, so the threads have a [minimal priority](http://docs.oracle.com/javase/6/docs/api/java/lang/Thread.html#MIN_PRIORITY).

It is possible to customise this value to increase the priority of those threads with the option `async.priority`:

```bash
async.priority=10
```

### [Compression](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#compression)

By default the content sent to Sentry is compressed before being sent. However, compressing and encoding the data adds a small CPU and memory hit which might not be useful if the connection to Sentry is fast and reliable.

Depending on the limitations of the project (e.g. a mobile application with a limited connection, Sentry hosted on an external network), it can be useful to compress the data beforehand or not.

It’s possible to manually enable/disable the compression with the option `compression`

```bash
compression=false
```

### [Max Message Size](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#max-message-size)

By default only the first 1000 characters of a message will be sent to the server. This can be changed with the `maxmessagelength` option.

```bash
maxmessagelength=1500
```

### [Timeout (Advanced)](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#timeout-advanced)

A timeout is set to avoid blocking Sentry threads because establishing a connection is taking too long.

It’s possible to manually set the timeout length with `timeout` (in milliseconds):

```bash
timeout=10000
```

### [Using a Proxy](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#using-a-proxy)

If your application needs to send outbound requests through an HTTP proxy, you can configure the proxy information via JVM networking properties or as a Sentry option.

For example, using JVM networking properties (affects the entire JVM process),

```bash
java \
  # if you are using the HTTP protocol \
  -Dhttp.proxyHost=proxy.example.com \
  -Dhttp.proxyPort=8080 \
  \
  # if you are using the HTTPS protocol \
  -Dhttps.proxyHost=proxy.example.com \
  -Dhttps.proxyPort=8080 \
  \
  # relevant to both HTTP and HTTPS
  -Dhttp.nonProxyHosts=”localhost|host.example.com” \
  \
  MyApp
```

See [Java Networking and Proxies](http://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html) for more information about the proxy properties.

Alternatively, using Sentry options (only affects the Sentry HTTP client, useful inside shared application containers),

```bash
http.proxy.host=proxy.example.com
http.proxy.port=8080
```

## [Custom functionality](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#custom-functionality)

At times, you may require custom functionality that is not included in the Java SDK already. The most common way to do this is to create your own `SentryClientFactory` instance as seen in the example below.

### [Implementation](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#implementation)

```java
public class MySentryClientFactory extends DefaultSentryClientFactory {
  @Override
  public SentryClient createSentryClient(Dsn dsn) {
    SentryClient sentryClient = new SentryClient(createConnection(dsn), getContextManager(dsn));

    /*
     Create and use the ForwardedAddressResolver, which will use the
     X-FORWARDED-FOR header for the remote address if it exists.
     */
    ForwardedAddressResolver forwardedAddressResolver = new ForwardedAddressResolver();
    sentryClient.addBuilderHelper(new HttpEventBuilderHelper(forwardedAddressResolver));

    sentryClient.addBuilderHelper(new ContextBuilderHelper(sentryClient));
    return configureSentryClient(sentryClient, dsn);
  }
}
```

### [Usage](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#usage)

To use your custom `SentryClientFactory` implementation, use the `factory` option:

```bash
factory=my.company.MySentryClientFactory
```

Your factory class will need to be available on your classpath with a zero argument constructor or an error will be thrown.

## [Linter configuration](https://docs.sentry.io/platforms/java/guides/log4j2/legacy/configuration.md#linter-configuration)

Sometimes linters can warn about types used by the SDK that are not available in your app. This can happen, for example, when using the Android integration due to the base SDK having JNDI lookup that takes no effect in Android.

To get rid of the warning, configure your `lint.xml` as follows:

```xml
<lint>
    <issue id="InvalidPackage">
        <ignore path="**/sentry*.jar" />
    </issue>
</lint>
```

And in your Gradle plugin:

```groovy
android {
    lintOptions {
        lintConfig file("path/to/lint.xml")
    }
}
```

Where `path/to/lint.xml` is the path to the linting configuration file mentioned above.