Add Custom Attributes to New Relic Java Agent Transactions

Desired outcome

Each monitored web request should include custom key‑value pairs (for example, user-role or tenant-id) so they appear in New Relic Transaction traces and can be used in NRQL queries, dashboards, and alert conditions.

Prerequisites

• New Relic Java agent version 6.0 or later installed and configured with a valid license key.
• The application is already instrumented by the agent (no extra SDK required).
• Access to the application source code to add New Relic API calls.
• A test or staging environment to validate changes before production.
• Build tool (Maven or Gradle) and deployment pipeline access.

Procedure

1. Add the New Relic API dependency (if not already present).

   <!-- Maven example -->
   <dependency>
       <groupId>com.newrelic.agent.java</groupId>
       <artifactId>newrelic-api</artifactId>
       <version>6.0.0</version> 
   </dependency>
   

   For Gradle: implementation 'com.newrelic.agent.java:newrelic-api:6.0.0'.
2. Import the API classes in the Java file where you handle the request:

   import com.newrelic.api.agent.NewRelic;
   import com.newrelic.api.agent.Trace;

3. Instrument the request‑handling method. Add the attribute calls inside the method (or a helper method) that processes the request:

   @Trace(dispatcher = true) // ensures the transaction is started if not already
   public void handleRequest(HttpServletRequest req, HttpServletResponse resp) {
       String role = determineUserRole(req); // your logic
       String tenant = extractTenantId(req); // your logic
       NewRelic.getAgent().getTransaction().addAttribute("user-role", role);
       NewRelic.getAgent().getTransaction().addAttribute("tenant-id", tenant);
       // existing request processing …
   }
   

   If you already have a transaction started elsewhere, you can omit @Trace and just call the API.
4. Rebuild and redeploy the application using your normal build and release process.
5. Verify the agent logs for any errors related to attribute addition. Look for lines like Finished adding attribute or error stack traces in newrelic.log.

Expected checks

1. In the New Relic UI, go to APM > (your app) > Transactions, select a recent transaction, and open the trace details. The custom attributes should appear under the Attributes section.
2. Run an NRQL query to confirm the attribute is being indexed:

   SELECT * FROM Transaction WHERE user-role IS NOT NULL LIMIT 5
   

3. Optionally create a dashboard chart using the attribute, e.g., SELECT count(*) FROM Transaction FACET user-role TIMESERIES.

Recovery options

• If the attributes cause issues (high cardinality, unexpected costs), comment out or remove the addAttribute calls, rebuild, and redeploy.
• Alternatively, disable all custom attribute collection for the agent by setting attributes.enabled = false in newrelic.yml and restarting the application.
• Monitor newrelic.log after rollback for any errors and confirm the previous known‑good state is restored.

Limitations and cautions

• Each transaction can have at most 64 custom attributes. Adding more will be silently dropped by the agent.
• Avoid high‑cardinality values (e.g., request IDs, timestamps) as they increase storage costs and may hit the attribute limit.
• Do not include personally identifiable information (PII) or sensitive data unless you have configured appropriate masking or compliance controls in New Relic.
• Attribute names must start with a letter and contain only letters, numbers, underscores, or hyphens; otherwise the agent will reject them.

Practical verification

After deployment, perform the following steps to confirm success:

1. Check newrelic.log for the message Finished adding attribute (or any error).
2. Open a transaction trace in the UI and verify that user-role and tenant-id appear under Attributes.
3. Execute the NRQL query SELECT count(*) FROM Transaction FACET user-role TIMESERIES and ensure a non‑zero result set appears.