Java agent 7.x to 8.x migration guide

This guide covers the major changes between the 7.x and 8.x series of the Java agent. It covers issues that you may encounter while upgrading and how to migrate successfully to version 8.x. The main changes include:

• Changed and removed transaction and span attributes
• Removed instrumentation

Changed and removed transaction and span attributes

To provide consistency across our APM agents and better align with industry standards, we changed transaction and span attributes in the Java agent. Starting in Java agent version 7.6.0, we introduced the new standard attributes http.statusCode and http.statusText and marked httpResponseCode, response.status, and response.statusMessage as deprecated.

Recommended Actions

• If you have alerts or dashboards using the deprecated attributes and use agent version 8.0 - 8.7, you should either update your agent to 8.8 or update references to the removed attributes. If you have updated all alerts or dashboards to the new standard attributes, you can disable the compatibility flag to only use the new standard attributes. To learn about the compatibility flag setting see the http_attribute_mode configuration.
• Update alerts and dashboards that are using deprecated attributes.

Finding impacted alert queries

To find and fix impacted alerts:

1. Use the NerdGraph Explorer and search for alerts using the queryLike operator for each attribute you are looking for. For example:

{
  actor {
    user {
      name
    }
    account(id: <ACCOUNTID>) {
      alerts {
        nrqlConditionsSearch(searchCriteria: {queryLike: "httpResponseCode"}) {
          nrqlConditions {
            nrql {
              query
            }
            id
            name
            policyId
          }
        }
      }
    }
  }
}

2. For each alert returned, you can use the id or name in the Alerts & AI > Alerts Conditions UI to find the alert.
3. Review the alert condition and signal coverage to confirm any impact to the alert.
4. Use the instructions in Fixing impacted alerts and dashboards NRQL statements to update the NRQL statements.

Finding impacted dashboard queries

To find the impacted queries for a dashboard:

1. Using the NerdGraph Explorer and the entity guid located in the metadata of a dashboard, you can get all the NRQL queries for a dashboard.

{
  actor {
    entity(guid: "[ENTITY GUID]") {
      ... on DashboardEntity {
        guid
        name
        pages {
          widgets {
            rawConfiguration
          }
        }
      }
    }
  }
}

2. The NRQL queries will return in the rawConfiguration item. You can use the text search to find removed attributes.
3. Use the instructions in Fixing impacted alerts and dashboards NRQL statements to update the NRQL statements.

You can also get the list of entity guids for all dashboards with the following query:

{
  actor {
    entitySearch(query: "domain IN ('VIZ')") {
      results {
        entities {
          guid
          accountId
        }
      }
    }
  }
}

Fixing impacted alerts and dashboards NRQL statements

http.statusCode would replace references to either httpResponseCode or response.status, which also has a different data type. Previously you would have used a reference like:

[...] WHERE (Numeric(response.status)>399 [...]

to convert the string datatype to a number. You no longer need to do this and can instead use simple numeric operations such as:

[...] WHERE (http.statusCode >399) [...]

http.statusText would replace references to response.statusMessage. The data type for this attribute has not changed.

Removed instrumentation

We removed the following instrumentation models for library versions no longer supported by their respective maintainers:

• cassandra-datastax-2.1.2
• httpclient-3.0
• jdbc-embedded-derby-10.2.1.6
• jdbc-embedded-derby-10.10.1.1
• jetty-7
• jetty-7.6
• jetty-9
• jetty-9.0.4
• jetty-9.1
• mongodb-2.12
• mongodb-2.14
• mongodb-3.0
• khttp-3.0.0
• khttp-3.4.0
• khttp-3.5.0

If your application uses one of the libraries, you will no longer receive the metrics and transactions produced by the instrumentation for that library on updating to a Java agent version v8.x.

Recommended actions

If possible, update the impacted library to a version supported by the maintainer and New Relic and update your agent. If updating the EOLed library isn't an option, you can still update your agent, but we recommend you test and review it to determine if the removed data causes any gaps in critical areas.