--- title: Introduction to New Relic for Java source: https://docs.newrelic.com/docs/apm/agents/java-agent/getting-started/introduction-new-relic-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](https://docs.newrelic.com/docs/data-analysis/metrics/analyze-your-metrics/data-collection-metric-timeslice-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. Use the New Relic Java agent to solve your app's performance issues with our [My app is slow tutorial](https://docs.newrelic.com/docs/journey-app-slow/root-causes/). > #### 💡 TIP > > Are you curious about trends in Java? See our report [2024 State of the Java Ecosystem](https://newrelic.com/resources/report/2024-state-of-the-java-ecosystem). ## Installation [#java-installation] To use the Java agent: 1. Make sure your system meets the [Java agent's compatibility and requirements](https://docs.newrelic.com/docs/compatibility-requirements-java-agent). 2. Sign up for your free account if you haven't already. 3. Install the Java agent using our launcher, or by following the [install docs](/install/java/). [Read the install docs](https://docs.newrelic.com/docs/agents/java-agent/installation/install-java-agent) [Add Java data](https://one.newrelic.com/marketplace/install-data-source?state=f91bc85d-0574-6e23-b90a-4d89c7c12866) To [view your app's performance in the New Relic UI](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/apm-overview-page), go to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > APM & services > (select an app) > Summary**. The APM user interface includes a dedicated [**JVM metrics** page](https://docs.newrelic.com/docs/agents/java-agent/features/jvm-metrics-page), [transaction](https://docs.newrelic.com/docs/apm/transactions) and [error](https://docs.newrelic.com/docs/apm/applications-menu/error-analytics/introduction-error-analytics) details, a [thread profiler tool](https://docs.newrelic.com/docs/apm/applications-menu/events/thread-profiler-tool) to sample Java threads and report stack traces, and more. You can also [extend your agent instrumentation](#extend-instrumentation) and explore your data with other New Relic features, including our [Metrics and events explorer](https://docs.newrelic.com/docs/query-your-data/explore-query-data/data-explorer/introduction-data-explorer) and [dashboards](https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/introduction-new-relic-one-dashboards). ## Startup configuration [#h2-startup] 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](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file) 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](https://docs.newrelic.com/docs/agents/java-agent/configuration/automatic-application-naming). ## Configuration options [#h2-configuration] You can configure application reporting from the New Relic web interface using [server-side configuration](https://docs.newrelic.com/docs/agents/manage-apm-agents/configuration/server-side-agent-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](https://docs.newrelic.com/docs/agents/java-agent/getting-started/apm-agent-security-java), such as collecting HTTP parameters but excluding certain named parameters. ## View logs for your APM and infrastructure data [#logs-context] You can also bring your logs and application's data together to make troubleshooting easier and faster. With [logs in context](https://docs.newrelic.com/docs/logs/logs-context/java-configure-logs-context-all/), you can see log messages related to your errors and traces directly in your app's UI. You can also see logs in context of your [infrastructure data](https://docs.newrelic.com/docs/logs/forward-logs/forward-your-logs-using-infrastructure-agent/), such as Kubernetes clusters. No need to switch to another UI page. ## Additional instrumentation [#extend-instrumentation] After installing the Java agent, use any of these methods to extend your instrumentation: - [Custom instrumentation:](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-metrics/custom-instrumentation) Implement Java custom instrumentation via annotation or XML. - [Enable distributed tracing](https://docs.newrelic.com/docs/apm/distributed-tracing/getting-started/introduction-distributed-tracing)[:](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-metrics/collect-custom-attributes) See the paths of your requests as they spread across a distributed, multiple-services architecture. - [Collect custom attributes:](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-metrics/collect-custom-attributes) Collect custom attributes via API or XML file. - [Java agent API:](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-agent-api) Use the API to control, customize, or extend the functionality of the Java agent. - [Browser instrumentation:](https://docs.newrelic.com/docs/browser/new-relic-browser/page-load-timing-resources/page-load-timing-process) Integrate the Java agent with [browser monitoring](https://docs.newrelic.com/docs/browser/new-relic-browser/getting-started/new-relic-browser) to gain visibility into end-user activity. - [Circuit breaker for Java custom instrumentation:](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/circuit-breaker-java-custom-instrumentation) Use a circuit breaker to protect applications from over-instrumentation. - [Custom JMX instrumentation by YAML:](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/custom-jmx-instrumentation-yaml) View custom JMX metrics with a YAML custom instrumentation file. - [JVM metrics page:](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/jvm-metrics-page) Collect metrics from the most common application servers through JMX. - [Open source telemetry:](https://docs.newrelic.com/docs/integrations/open-source-telemetry-integrations/get-started/introduction-new-relics-open-source-telemetry-integrations) We offer a variety of tools, such as [Kamon Reporter](https://docs.newrelic.com/docs/integrations/open-source-telemetry-integrations/open-source-telemetry-integration-list/kamon-reporter), [OpenTelemetry exporter](https://docs.newrelic.com/docs/integrations/open-source-telemetry-integrations/open-source-telemetry-integration-list/new-relics-opentelemetry-integration), [Micrometer metrics registry](https://docs.newrelic.com/docs/integrations/open-source-telemetry-integrations/open-source-telemetry-integration-list/new-relics-micrometer-integration), and [Java Telemetry SDK](https://docs.newrelic.com/docs/data-ingest-apis/get-data-new-relic/new-relic-sdks/telemetry-sdks-send-custom-telemetry-data-new-relic). ## When to restart your JVM [#jvm_restart] When you make a change to your configuration or to your custom XML, in almost all cases you must restart your JVM. There are only four situations where a restart is **not** necessary: | **JVM restart is not required for...** | **Comments** | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Log level or audit mode changes | If you are simply changing the `log_level` or `audit_mode` in the [Java agent configuration file](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file), you do not need to restart the JVM. | | Custom instrumentation XML file | JVM restart depends on your Java agent version: - 3.15.0 or higher: If you are updating a custom instrumentation XML file in the extensions folder, the updates will be reloaded automatically within a minute. - Java agent versions lower than 3.15.0: If you using an agent version earlier than 3.15.0, you must restart the JVM. | | Circuit breaker changes | If you are [changing the circuit breaker](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/circuit-breaker-java-custom-instrumentation#troubleshooting) for Java custom instrumentation, a JVM restart is not required. | | Ignored or expected errors | 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. ## JSR 163 compliance [#jvm] 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](https://docs.newrelic.com/docs/accounts-partnerships/accounts/security/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. ## Troubleshooting procedures [#troubleshoot] If you have problems, see [No data appears](https://docs.newrelic.com/docs/apm/agents/java-agent/troubleshooting/no-data-appears-java) and other troubleshooting docs in that section.