Introduction to New Relic for Java

With New Relic's Java agent, you can track everything from performance issues to tiny errors within your code. Every minute the agent posts metric timeslice and event data to the New Relic user interface, where the owner of that data can sign in and use the data to see how their website is performing.

JSR 163 compliance

The New Relic Java agent monitors web transactions, receiving information about them and communicating that information to the New Relic user interface with strong data security measures in place. The agent is packaged as a JSR 163 compliant javaagent that is activated by the JVM through modifications to the JVM launch. Once activated, the agent inserts itself into the class loading stream and instruments class methods using byte code instrumentation (bci).

Designed to have minimal impact on your web application, all of the classes are in the newrelic package namespace so they do not collide with your own classes. The agent uses the ASM bci engine to insert software probes.

The agent receives basic information about your host environment, such as operating system, Java version, system properties, and your New Relic configuration file. The agent also polls data from the JVM and from JMX.

Startup configuration

The Java agent reads the startup configuration from the newrelic.yml file, which must be in the same directory as newrelic.jar. You can also override settings using Java system properties.

The agent needs the license_key and app_name settings at startup (bootstrap). You can customize the location of the log file and other settings in your newrelic.yml file. In addition, you can adjust the naming configuration if your app server runs multiple applications in the same JVM.

Configuration options

You can configure application reporting from the New Relic web interface using server-side configuration. Changes will be applied to all agents reporting for your application when the JVM restarts. However, if you use server-side configuration, you must still maintain required settings (license_key and app_name) in the local config file.

Both transaction traces and error snapshots can optionally record HTTP parameters. Sometimes HTTP parameters contain sensitive information, such as a credit card number. The agent has several configuration options to ensure data security, such as collecting HTTP parameters but excluding certain named parameters.

Additional instrumentation

After installing the Java agent, use any of these methods to extend your instrumentation:

If you are ignoring or expecting errors by configuring the newrelic.yml file, a JVM restart is not required. This includes adding status codes or classes to the newrelic.yml file when using the Java agent version 3.40.0 or higher. For example:

ignore_status_codes

expected_status_codes

ignore_classes

ignore_messages

expected_classes

expected_messages

All other changes require an agent restart, which means restarting the JVM.