Diagnosing New Relic Java Agent Connectivity and Data Reporting Gaps

The condition: your app runs, but APM shows nothing (or shows gaps)

You deployed the New Relic Java agent, the application starts fine, and yet the APM dashboard shows no data, stale data, or intermittent gaps in throughput and error charts. The application itself is healthy, which makes this easy to deprioritize — until an incident happens and you have no telemetry.

The useful takeaway: in practice, almost every Java agent reporting failure comes down to one of five causes — the agent never attached, the license key is wrong, the collector is unreachable over the network, the agent is silently dropping data under JVM pressure, or the agent version is incompatible with your JDK. The checks below are ordered from cheapest to most involved, and each fix is tied to a specific finding.

Assumptions: New Relic Java agent 8.x, a standard newrelic.yml configuration, and a Linux host or container. Exact log messages vary slightly by agent version, so treat quoted strings as patterns to search for, not exact matches.

Cause and diagnostic quick reference

Check 1: confirm the agent actually attached

The most common failure is the simplest: the -javaagent flag never made it into the JVM arguments. This happens frequently with container images where an entrypoint script was overridden, or with systemd units where an environment file was not loaded.

On the host or in the container, inspect the running process (requires read access to the process list):

ps -ef | grep java | grep newrelic

You should see -javaagent:/path/to/newrelic.jar in the command line. If the flag is missing, the agent never started — fix the startup script, Dockerfile ENTRYPOINT/CMD, or orchestrator spec (for Kubernetes, confirm the JAVA_TOOL_OPTIONS environment variable is actually set on the pod and not stripped by a security policy).

If the flag is present, check the application startup log for the agent initialization banner, typically containing "New Relic Java Agent" and a version number. Absence of the banner despite the flag usually means the JAR path is wrong or unreadable — check file permissions for the user running the JVM.

Check 2: read newrelic.log before anything else

The agent writes its own log, separate from your application log, at logs/newrelic.log inside the agent directory (the directory containing newrelic.jar). This file is the primary diagnostic source for every remaining check.

Search for connection and authentication failures:

grep -iE "error|exception|license|connect" logs/newrelic.log | tail -50

What to look for:

• HTTP 403 or license-key errors — the collector is reachable but rejecting your data. Go to Check 3.
• Connection timeouts, UnknownHostException, or SSL handshake failures — a network path problem. Go to Check 4.
• Messages about queue overflow or dropped events — resource pressure. Go to Check 5.

Do not raise the agent log level to FINEST/DEBUG in a high-traffic production environment as a first move — the volume can exhaust disk space and add I/O overhead. The default INFO level already records connection and harvest failures, which cover the causes in this guide.

Check 3: verify the license key

Open newrelic.yml (or check the NEW_RELIC_LICENSE_KEY environment variable, which overrides the file) and compare the value against the key shown in your New Relic account under the license key settings. Common mistakes:

• Using an ingest key from a different account in the same organization.
• Trailing whitespace or a stray newline introduced by a secrets manager.
• A placeholder value left in a templated config that the deployment pipeline never substituted.

Fix: correct the key, then restart the JVM — the agent reads the license key at startup, so a restart is required for the change to take effect. Verify by watching newrelic.log during startup for a successful connection followed by harvest cycles (periodic "sending" or metric-reporting entries) rather than 403 responses.

Check 4: test egress to the collector

The agent communicates with the New Relic collector over HTTPS on port 443. From the host or container running the JVM (no special privileges needed), test the path:

curl -sv https://collector.newrelic.com -o /dev/null --max-time 10

You do not need a valid response body — you are checking whether the TCP connection and TLS handshake complete. A timeout or "connection refused" means egress is blocked. If your account is in the EU data center region, test the EU collector endpoint instead, since the region endpoints differ.

Fixes depend on the finding:

• Blocked egress: have your network team allow outbound 443 to the New Relic collector endpoints for your region. In Kubernetes, check for a restrictive NetworkPolicy or egress gateway.
• Corporate proxy required: configure proxy_host and proxy_port in newrelic.yml, or pass -Dhttps.proxyHost/-Dhttps.proxyPort JVM flags.
• TLS interception: if a proxy performs SSL inspection, the agent may fail the handshake. You may need to add the proxy's CA to the JVM truststore, or configure the agent to use a custom truststore via its config.

Risk note: modifying the JVM truststore affects all TLS connections from that JVM, not just the agent. Prefer a dedicated truststore referenced only by the agent configuration where possible.

Check 5: rule out resource pressure and version incompatibility

If data appears but drops out during load peaks, the agent may be shedding work to protect the application. The agent is designed to drop events rather than destabilize the JVM when memory or CPU is constrained. Correlate the gap windows in APM with your GC logs, heap usage, and container memory limits. A container that is being CPU-throttled or approaching its memory limit will starve the agent's harvest threads.

Fixes: raise the container memory limit, tune the heap so the JVM is not in constant GC, or reduce agent overhead by lowering the transaction trace threshold count or disabling high-cost features (for example, high-security mode constraints or excessive custom instrumentation) until the pressure is resolved.

Separately, if the agent fails at startup with linkage or class-cast errors, check the agent release notes for supported JDK versions. Running a very new JDK with an old agent (or a very old agent on a modern JDK) is a known source of instrumentation failures. The fix is a controlled agent upgrade in a staging environment first — agent upgrades change instrumentation behavior, so verify key transactions still report before promoting to production.

How to confirm the fix worked

After any change and JVM restart, verify in this order:

1. Startup log contains the agent banner with the expected version.
2. newrelic.log shows a successful collector connection and repeating harvest cycles with no errors for at least 10 minutes.
3. The application entity in APM shows live throughput within a few minutes of generating traffic.

When to escalate

Open a New Relic support case when: the collector connection succeeds and the license key is accepted but no data appears after 15 minutes of traffic; the agent log shows internal errors you cannot map to configuration; or you suspect agent/JDK incompatibility on a supported combination. Attach the full newrelic.log from startup, your sanitized newrelic.yml (license key redacted), the exact agent and JDK versions, and the output of your egress test. That bundle eliminates the first two rounds of support questions.