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.service_version="1.0.0" \
     -jar my-app.jar

Configurations

You can set the following configurations in the Java agent:

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

-Datatus.license_key="YOUR_LICENSE_KEY"
-Datatus.app_name="YOUR_APP_NAME"
-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.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

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