Customizing Java APM Agent

You can customize the Atatus Java APM Agent’s behavior through Java runtime system properties or environment variables.

# Example Startup Command
java -javaagent:atatus-java-agent.jar \
     -Datatus.license_key="YOUR_LICENSE_KEY" \
     -Datatus.app_name="Java App" \
     -Datatus.notify_host="YOUR_ON_PREMISE_URL" \
     -Datatus.service_version="1.0.0" \
     -jar my-app.jar

Configurations

You can set the following configurations in the Java agent:

Option	Description	Type
`license_key`	APM License Key for your Atatus account.	`string`
`app_name`	Name of your Java project or application.	`string`
`notify_host`	URL of your on-premise Atatus server, for example `YOUR_ON_PREMISE_URL`. Environment variable: `ATATUS_NOTIFY_HOST`.	`string`
`service_version`	Application version to identify releases of your app.	`string`
`environment`	Environment name (e.g., `Production`, `Staging`) to filter data in the APM dashboard.	`string`
`log_body`	Capture request body in transaction traces.	`string`
`log_body_ignore_urls`	List of URLs to exclude from request body capture to protect sensitive data.	`list` / `string`
`ignore_urls`	List of URLs that the agent will ignore from monitoring.	`list` / `string`
`transaction_ignore_methods`	Restrict requests with specific HTTP methods from being instrumented. (Supported from v2.3.0)	`list`
`log_level`	Sets the agent logging level (`ERROR`, `WARN`, `INFO`, `DEBUG`). Case-insensitive.	`string`
`log_file`	Path of the agent log file. Defaults to `System.out` (standard output).	`string`
`log_file_size`	Maximum size of the agent log file before it rolls over (for example `50mb`). Defaults to `50mb`.	`string`
`ignore_status_codes`	List of HTTP status codes to ignore from error metrics.	`list` / `string`
`application_packages`	Package path(s) to identify in-app stack frames in Java exceptions.	`list` / `string`
`tracing`	Enable or disable distributed tracing.	`boolean`
`analytics`	Enable API Analytics to collect individual requests with contextual data.	`boolean`
`capture_body`	Capture request and response body in API Analytics (`off`, `errors`, `transactions`, `all`).	`string`
`trace_methods`	List of methods to create transactions or spans for, using pointcut syntax.	`list`
`enabled`	Enable or disable the Atatus agent.	`boolean`

All Java system properties use the prefix atatus. as shown below:

-Datatus.license_key="YOUR_LICENSE_KEY"
-Datatus.app_name="YOUR_APP_NAME"
-Datatus.notify_host="YOUR_ON_PREMISE_URL"
-Datatus.service_version=1.2.0
-Datatus.environment=Production
-Datatus.tracing=true
-Datatus.log_body=all
-Datatus.log_body_ignore_urls="/login,/signup,/card/*,*/password-reset"
-Datatus.ignore_urls="/health*,/ping,*/internal/*"
-Datatus.transaction_ignore_methods="OPTIONS,HEAD"
-Datatus.log_level=Debug
-Datatus.log_file=/var/log/atatus/atatus-java-agent.log
-Datatus.log_file_size=50mb
-Datatus.ignore_status_codes="404,429,503"
-Datatus.application_packages="com.example.app,com.example.service"
-Datatus.analytics=true
-Datatus.capture_body=all
-Datatus.enabled=true
-Dhttps.proxyHost=127.0.0.1
-Dhttps.proxyPort=8888

Set App Version

If you use a version to identify releases of your application, you can send it to Atatus using service_version. Setting service_version helps track performance regressions and errors across different releases.

// Java System Properties
-Datatus.service_version=1.2.0

// Environment Variable
export ATATUS_SERVICE_VERSION=1.2.0

Set Environment

If you are tracking multiple environments (e.g., Development, Staging, Production) within a single APM project, you can set the environment as follows:

// Java System Properties
-Datatus.environment=Production

// Environment Variable
export ATATUS_ENVIRONMENT=Production

Enable API Analytics

API Analytics collects all requests individually with rich contextual data such as request headers, response headers, request body, and response body.

// Java System Properties
-Datatus.analytics=true

// Environment Variable
export ATATUS_ANALYTICS=true

Enable Capture Body in API Analytics

The capture body option is disabled by default. If you want to view the request body in traces, you can enable this option. The body will be captured only for the following Content-Types: application/x-www-form-urlencoded, text/*, application/json, and application/xml.

// Java System Properties
-Datatus.log_body=all

// Environment Variable
export ATATUS_LOG_BODY=all

Ignore Log Body URLs

Using this option, you can avoid capturing request bodies for specific URLs. This allows you to prevent sensitive data (such as login credentials or payment details) from being sent to Atatus. Ignored URLs can be specified as strings or wildcards/regex.

// Java System Properties
-Datatus.log_body_ignore_urls="/login,/signup,/card/*,*/password-reset"

// Environment Variable
export ATATUS_LOG_BODY_IGNORE_URLS="/login,/signup,/card/*,*/password-reset"

Ignore URLs

Using this option, you can exclude specific URLs from being monitored by Atatus. For example, you may want to exclude health check endpoints such as /health, /ping, heartbeat, or internal admin routes. Ignored URLs can be strings with wildcard patterns or regular expressions.

// Java System Properties
-Datatus.ignore_urls="/health*,/ping,*/internal/*"

// Environment Variable
export ATATUS_IGNORE_URLS="/health*,/ping,*/internal/*"

Ignore HTTP Methods

Used to restrict requests with certain HTTP methods from being instrumented. This property should be set to a comma-separated list or an array containing one or more HTTP method names. When an incoming HTTP request is detected, its method will be tested against each element in this list.

// Java System Properties
-Datatus.transaction_ignore_methods="OPTIONS,HEAD,PRI*"

// Environment Variable
export ATATUS_TRANSACTION_IGNORE_METHODS="OPTIONS,HEAD,PRI*"

Enable Debug Log Level

If you are facing issues with Java APM (e.g., missing data, agent initialization issues), you can enable the debug log level in JVM options and share the logs with success@atatus.com. The available log levels are ERROR, WARN, INFO, and DEBUG.

// Java System Properties
-Datatus.log_level=Debug

// Environment Variable
export ATATUS_LOG_LEVEL=Debug

Set log file

By default, the agent writes its logs to standard output. To write them to a file instead, set log_file to the full path of the log file. You can pass it as a Java system property:

$ java -javaagent:atatus-java-agent.jar \
       -Datatus.log_file=/var/log/atatus/atatus-java-agent.log \
       -jar my-app.jar

Or set it as an environment variable:

$ export ATATUS_LOG_FILE=/var/log/atatus/atatus-java-agent.log

You can use _AGENT_HOME_ in the path as a placeholder for the folder that contains atatus-java-agent.jar, for example _AGENT_HOME_/logs/atatus-java-agent.log. When the log file reaches log_file_size (default 50mb), the agent rolls it over and keeps one older file, so the logs use about twice that size on disk. To change the size, pass log_file_size as a Java system property:

$ java -javaagent:atatus-java-agent.jar \
       -Datatus.log_file=/var/log/atatus/atatus-java-agent.log \
       -Datatus.log_file_size=100mb \
       -jar my-app.jar

Or set it as an environment variable:

$ export ATATUS_LOG_FILE_SIZE=100mb

Make sure the user running your application can write to the log file’s folder.

Ignore Status Codes

Using this option, you can add a list of HTTP status codes that you don’t want to see in error metrics. This option accepts comma-separated 4xx and 5xx status codes.

// Java System Properties
-Datatus.ignore_status_codes="404,429,503"

// Environment Variable
export ATATUS_IGNORE_STATUS_CODES="404,429,503"

Set Application Package Path

You can configure your application package path so Atatus can accurately identify in-app stack frames and pinpoint the exact source line in Java exceptions.

// Java System Properties
-Datatus.application_packages="org.example,org.another.example"

// Environment Variable
export ATATUS_APPLICATION_PACKAGES="org.example,org.another.example"

Trace Methods

Using this option, you can create transactions or spans for specific methods using a pointcut-like syntax. This is useful for instrumenting custom code or unsupported frameworks.

// Java System Properties
-Datatus.trace_methods="org.example.MyClass#myMethod"

// Environment Variable
export ATATUS_TRACE_METHODS="org.example.MyClass#myMethod"

For detailed syntax, matching patterns, and examples, see Trace Methods.

Disable Agent

Using this option, you can completely disable the agent, including instrumentation and remote config polling. Set enabled to false to disable the agent.

// Java System Properties
-Datatus.enabled=false

// Environment Variable
export ATATUS_ENABLED=false

Proxy Configuration

You can configure the Atatus Java Agent to connect via a proxy server when direct internet access is restricted by a firewall. HTTPS Proxy:

// Java System Properties
-Dhttps.proxyHost=127.0.0.1
-Dhttps.proxyPort=8888

HTTP Proxy:

// Java System Properties
-Dhttp.proxyHost=127.0.0.1
-Dhttp.proxyPort=8888

​Configurations

​Set App Version

​Set Environment

​Enable API Analytics

​Enable Capture Body in API Analytics

​Ignore Log Body URLs

​Ignore URLs

​Ignore HTTP Methods

​Enable Debug Log Level

​Set log file

​Ignore Status Codes

​Set Application Package Path

​Trace Methods

​Disable Agent

​Proxy Configuration

Configurations

Set App Version

Set Environment

Enable API Analytics

Enable Capture Body in API Analytics

Ignore Log Body URLs

Ignore URLs

Ignore HTTP Methods

Enable Debug Log Level

Set log file

Ignore Status Codes

Set Application Package Path

Trace Methods

Disable Agent

Proxy Configuration