APM (CU-based) usage: Attributes and queries

This document contains the attributes available for CU-based APM account usage (not host-based APM), and provides example NRQL queries for use in Insights or API calls.

Data generation

Once per day, an APM account will generate a NrDailyUsage Insights event for:

  • Every application instance created over the last 24 hours
  • Every unique host on which an application instance existed over the last 24 hours

These two types of events allow your usage data to be queried and analyzed in many different ways. To query the application events, use a usageType attribute value of Application. To query the host events, use a usageType attribute value of Host.

All APM events use a productLine attribute value of APM. For more information, see APM query examples.

General attributes

The following are general (not APM-specific) account-related attributes. These attributes can help you understand how your accounts and sub-accounts are using New Relic products.

Attribute Description
consumingAccountId

ID of the New Relic account that is directly responsible for the stored events, as determined from the license key used.

consumingAccountName Name of the New Relic account that is directly responsible for the stored events, as determined from the license key used.
masterAccountId

The ID of the master account that is either responsible for stored events or that is the parent of the consuming account. When a master account is the consuming account, masterAccountId is the consumingAccountId.

This attribute is present even for accounts that do not have a master account. This is to ensure continued reporting if the account is later made a master account.

masterAccountName

Name of the master account that is either responsible for stored events, or that is the parent of the consuming account. When a master account is the consuming account, masterAccountName is the consumingAccountName.

This attribute is present even for accounts that do not have a master account. This is to ensure continued reporting if the account is later made a master account.

partnershipId

Partner ID of the New Relic customer partnership associated with the account responsible for the stored events.

This attribute is only present if the consuming account is associated with a New Relic customer partnership.

partnershipName

Name of the New Relic customer partnership associated with the account responsible for the stored events.

This attribute is only present if the consuming account is associated with a customer partnership.

subAccountId

ID of the sub-account that is responsible for the stored event. When this attribute is present, subAccountId is the consumingAccountId.

This attribute is only present if the consuming account is a sub-account (not a master account).

subAccountName

Name of the sub-account responsible for stored events. When present, this attribute is the same as the consumingAccountName.

This attribute is only present if the consuming account is a sub-account (not a master account).

timestamp UNIX timestamp (seconds since epoch) of the day and time when event generation was initiated.

APM attributes (CU-based)

The following are usage-related attributes generated by CU-based APM accounts (not host-based APM). To query APM-specific data, use a productLine attribute value of APM.

Attribute Description
agentHostname ID reported by the agent to uniquely identify the host for which this usage event is reported. This value can come from several sources in the application’s environment, but commonly is the value returned by the gethostname Linux syscall. In Docker environments, this attribute can take on the value (sometimes truncated) of the Docker container ID. agentHostname is one of three possible providers for the hostId value.
apmAgentMemoryBytes Bytes of RAM available to the host, as detected by the New Relic agent from the host OS.
apmAgentProcessorCount Number of logical CPU cores available to the host, as detected by the New Relic agent from the host OS.
apmAgentVersion

Version of the New Relic APM agent running in the application instance reporting this usage. Present only for events where usageType equals Application.

To update your agent version, see Update the New Relic agent.

apmAppId ID uniquely identifying the application that is reporting this usage, as it appears in the APM product. Present only for events where usageType equals Application.
apmAppInstanceId ID uniquely identifying the application instance (the process running the New Relic APM agent).
apmAppName Name of the application reporting this usage, as it appears in the APM product. Present only for events where usageType equals Application.
apmBillingInstanceSize Size of the host, for CU-based billing purposes. Calculated as apmProcessorCount plus (apmMemoryBytes/(1024^3)), or the number of processors plus memory (GiB).
apmCloudDerivedMemoryBytes Bytes of RAM available to the host, as defined by the cloud provider for the host’s instance type.
apmCloudDerivedProcessorCount Number of logical processors available to the host, as defined by the cloud provider for the host’s instance type.
apmComputeUnits Number of compute units (CUs) recorded for the given host. CUs are calculated as apmHoursUsed multiplied by apmBillingInstanceSize. For more information, see CU-based pricing.
apmComputeUnitRule

Describes the algorithm used to calculate the host size for CU usage. Values include:

  • agent_collected_calculated_data: Use the host size data collected by the agent from the OS environment.
  • cloud_provider_data: Use the host size data from the cloud provider.
  • missing_data: Some host size data was missing. This could be due to an older agent that doesn't support reporting CPU and memory sizes, or an agent and OS combination for which CPU and memory sizes are not supported. This will result in the default host size (16) being applied.
apmContainerCount The number of unique container IDs associated with this host. Present only for events where usageType equals Host.
apmHoursUsed Number of hours for which usage was recorded for the given entity. When an entity is connected to New Relic for any amount of time within a given hour, that hour is counted toward usage.
apmLanguage Name of the language that the usage-reporting application is written in, as reported by the New Relic agent. Examples: ruby, java, python. Present only for events where usageType equals Application.
apmMemoryBytes Bytes of RAM available to the host. Used to calculate apmBillingInstanceSize. The value of one of these attributes will be used: apmCloudDerivedMemoryBytes, apmAgentMemoryBytes.
apmProcessorCount Number of logical processors available to the host, used to calculate apmBillingInstanceSize. The value of one of these attributes will be used: apmCloudDerivedProcessorCount, apmAgentProcessorCount.
bootId

Linux boot ID of host for which this usage is reported, which is unique for each boot lifetime of each Linux operating system instance. Will only be present when the New Relic agent is one of the following versions:

  • Go: 1.11 or higher
  • Java: 3.42.0 or higher
  • .NET: 6.19.330.0 or higher
  • Node.js: 2.1.0 or higher
  • PHP: 7.5.0.199 or higher
  • Python: 2.90.0.75 or higher
  • Ruby: 4.4.0.336 or higher

bootId is one of three possible providers for the hostId value.

cloudInstanceId

ID uniquely identifying the cloud host instance (example: an AWS EC2 instance) for which this usage is reported. (For example, for an AWS EC2 instance, the value would look like i-1234abcd5678ef900.) This is used to uniquely identify the host if the apmComputeUnitRule is cloud_provider_data. This will not be present if no cloud provider was detected by the agent.

Agents with these versions will detect cloud provider data for AWS:

  • Go: 1.11 or higher
  • Java: 3.18.0 or higher
  • .NET: 5.1.72.0 or higher
  • Node.js: 1.21.0 or higher
  • PHP: 5.5.0 or higher
  • Python: 2.54.0.41 or higher
  • Ruby: 3.12.1.298 or higher

cloudInstanceId is one of three possible providers for the hostId value.

cloudInstanceSize Size of the cloud instance for this host for CU-based APM billing purposes, as calculated according to the formula for apmBillingInstanceSize, using the CPU and memory sizes associated with the instance type defined by the cloud provider. Will not be present if no cloud provider was detected by the agent.
cloudInstanceType Instance type of the host as defined by the cloud provider and detected by the agent. For example: c4.2xlarge. This will not be present if no cloud provider was detected by the agent.
cloudProvider Name of the cloud provider for this host. Example values: aws, azure. This will not be present if no cloud provider was detected by the agent.
cloudZone Name of the zone that a cloud provider host is located in. For example: eu-central-1b. This will not be present if no cloud provider was detected by the agent.
containerId ID of the Docker or other Linux container in which the application instance is running. This will not be present if a container was not detected by the agent. Present only for events where usageType equals Application. This attribute is not used to uniquely identify hosts for billing purposes.
hostId ID used to uniquely identify the host for which this usage is reported. Any given hour of APM usage for this host will be counted only once when calculating apmHoursUsed. There are several possible host identifiers reported by the New Relic agent. The attributes, if present, will be chosen to use in this order of precedence: cloudInstanceId, bootId, agentHostname.
instanceSizeCapped This is True if the calculated host size was greater than 16 and therefore capped.
missingCpuData This is True if the APM agent reports no CPU count.
missingRamData This is True if the APM agent reports no memory count.
productLine The New Relic product the usage data is from. APM usage data will have the value APM. Use this value when querying APM usage data.
usageType

For APM, this value can be either Application or Host, depending on the type of entity this event records usage for (other New Relic products will have different values for usageType). Events with both values are recorded so that usage can be broken down in many ways.

For Application: the event represents usage for a single unique application instance for that day. For Host: the event represents usage for a single unique host for that day.

Only Host entities are used to calculate billable usage. Application entities are useful for comparing usage between applications, but are not used for billing or contract purposes.

Query examples

Here are some examples of NRQL queries you can use with your account usage data. You can run NRQL queries with the Insights query tool, use the resulting charts in Insights dashboards, and use the NRQL with the Insights query API.

Usage for last month
SELECT sum(apmComputeUnits) 
FROM NrDailyUsage 
WHERE usageType='Host' 
AND productLine='APM' 
SINCE last month 
UNTIL this month
Monthly usage for last year
SELECT SUM(apmComputeUnits)
FROM NrDailyUsage
WHERE usageType='Host' 
AND productLine='APM'
FACET monthOf(timestamp) 
SINCE 12 month ago limit 13
Instance-CUs per application

This query measures the total number of CUs used by all instances (processes) of an application in the last 24 hours. It's useful for determining which applications are responsible for APM usage, but does not return results that match precisely how New Relic prices APM usage.

Each application instance is counted separately in this query, even if it runs concurrently with another application instance on the same host, so the number of application instance-hours is likely to be greater than the number of host-hours (the billable quantity).

SELECT sum(apmComputeUnits) 
FROM NrDailyUsage 
WHERE usageType='Application' 
AND productLine='APM' 
FACET consumingAccountName,consumingAccountId,apmAppName 
SINCE 1 day ago 
LIMIT 2000
Legacy host usage report

This query returns data once provided in the "host usage report": a listing of applications running on each host. Note that while APM usage is counted on an hour-by-hour basis, per-hour usage data is no longer available via the API or UI.

FROM NrDailyUsage 
SELECT min(timestamp) 
AS 'Earliest reporting day',max(timestamp) 
AS 'Latest reporting day' 
FACET apmAppName,hostId,agentHostname,consumingAccountName,consumingAccountId 
WHERE usageType='Application' 
AND productLine='APM' 
SINCE 1 month ago 
LIMIT 2000
Legacy per-host usage report

This query produces a close approximation of the CSV report you would have gotten in the deprecated UI system:

FROM NrDailyUsage 
SELECT consumingAccountId 
AS 'Account ID', hostId, cloudProvider 
AS 'Host provider', cloudInstanceType 
AS 'Instance type', apmBillingInstanceSize 
AS 'Instance size', apmHoursUsed 
AS 'Hours used', apmComputeUnits 
AS 'Usage (CU)', apmMemoryBytes/(1024*1024*1024) 
AS 'Total RAM', apmProcessorCount 
AS 'Logical processors', apmContainerCount 
AS 'Container count', apmComputeUnitRule 
AS 'Business rule', missingCpuData, missingRamData, instanceSizeCapped, cloudZone, cloudInstanceId 
WHERE productLine='APM' 
AND usageType='Host' 
SINCE 1 day ago 
LIMIT 2000

This NRQL query is different than the legacy usage report:

Per-host query Comments
Time period

This query includes only the last 24 hours of usage. To see the usage aggregated over a longer time period, change the SINCE clause.

Results limited to a maximum number of rows

NRQL limits the number of rows returned. If you have more hosts than the maximum number of rows returned and want to get the complete set of hosts, you can narrow your query with more​ WHERE clauses to return subsets of the data (for example, WHERE cloudInstanceId LIKE “%0”) to divide the data into up to 16 groups, modulo the last character in the AWS instance ID.

Docker container IDs

A single Docker container ID does not appear in this report. A Docker container ID is reported only at the application instance level of granularity (usageType='Application').

For the host (usageType='Host'), a count of unique containers is reported, since there are often very many. While choosing just one container ID to report for a host had been informative, now there is more data reported at the appropriate level of granularity.

Business rule

Business rule has been replaced with two attributes:

  • apmComputeUnitRule defines how the size of the host was calculated, depending on what data was available from the agent. It no longer describes whether the agent needs to be updated to provide more accurate host naming in a container environment (update_agent_for_container_environment).
  • missingCpuData, missingRamData, and instanceSizeCapped are boolean flags describing what the value missing_data means when it is present in the apmComputeUnitRule attribute.
Agent version information

Use this query to see which agent versions are running on your applications in the last 24 hours. This information can be useful in determining whether the agent needs to be upgraded to report a more accurate host name in a Docker container environment (either a Linux boot ID or a cloud provider instance ID).

FROM NrDailyUsage 
SELECT count(*) 
WHERE productLine='APM' 
AND usageType='Application' 
FACET consumingAccountId, consumingAccountName, apmAppName, apmAgentVersion, apmLanguage 
SINCE 1 day ago 
LIMIT 2000
Agents needing updates for container tracking

This query helps identify applications where an agent is reporting a hostname that may be the same as a container ID. The result of the query is not a definitive list of such applications, but helps you determine which applications may be affected.

Hosts that are inaccurately named after a Docker container will have a hostId value that is the same as the first part of the containerId value. The apmComputeUnitRule != ‘cloud_provider_data’ clause removes from consideration hosts that are named by the cloud provider and thus not named after an ephemeral container.

FROM NrDailyUsage 
SELECT latest(hostId) 
WHERE containerId is not null 
AND apmComputeUnitRule != 'cloud_provider_data' 
AND productLine='APM' 
AND usageType='Application' 
FACET consumingAccountId,apmAppName,apmAgentVersion,apmLanguage,containerId 
SINCE 1 day ago 
LIMIT 2000
Account hierarchy

This query is useful for seeing the account hierarchy (partnership, master, sub-accounts).

SELECT count(*) 
FROM NrDailyUsage 
FACET partnershipName,masterAccountName,masterAccountId,consumingAccountName,consumingAccountId 
LIMIT 2000 SINCE 1 day ago

For more help

Recommendations for learning more: