New Relic Java APM agent: Determining effective app_name when both newrelic.yml and environment variable are set

Direct answer

For current New Relic Java agent generations, the NEW_RELIC_APP_NAME environment variable (or the equivalent JVM system property) takes precedence over the app_name value in newrelic.yml. The environment variable wins. This precedence is version-sensitive, however: some older major agent releases may ignore the environment variable for app_name and require the JVM system property instead.

Confirmed behavior vs. version-sensitive assumptions

Confirmed: The agent resolves the effective application name at startup. That resolved value is reported in the agent startup logs and reflected in the New Relic UI under the entity’s configuration details. A valid license key paired with an incorrect ingest region or endpoint can cause telemetry to be dropped silently, so region validation is as important as name validation.

Assumption requiring verification: The environment-variable-over-YAML precedence described above is the expected behavior for modern agent releases. Because the question involves a pinned, immutable artifact, the exact major version of the Java agent inside that image determines whether the environment variable is sufficient or whether the JVM system property must also be supplied.

Validating the effective name and region without modifying the image

Because the deployable image is immutable, apply overrides at runtime and inspect the result:

1. Set the environment variable and the region/endpoint variable at container start, for example:

   NEW_RELIC_APP_NAME=my-service
   # set the region/endpoint variable documented for your agent version
   java -jar app.jar

2. If the pinned agent is a legacy major version, also pass the JVM system property as a fallback so both sources agree:

   -Dnewrelic.app_name=my-service

3. Raise the agent log level to capture the resolved configuration at startup. Consult the agent’s documented logging properties for the exact key.
4. Inspect the startup logs for the effective app_name and the ingest endpoint being used.
5. Confirm in the New Relic UI that the entity appears under the expected name, in the expected account, and in the expected region.
6. If the agent exposes a local status or health endpoint, query it to retrieve the effective configuration without restarting the process.

The one detail that changes the recommendation

The exact major version of the New Relic Java agent in the image. If it is a current major generation, the environment variable alone is the standard override. If it is a legacy major version, the environment variable may be ignored for app_name, and the JVM system property becomes the reliable mechanism. Until that version is confirmed, the conservative approach is to set both the environment variable and the JVM system property to the same value.