--- title: Rules for creating metrics: requirements and tips source: https://docs.newrelic.com/docs/data-apis/convert-to-metrics/creating-metric-rules-requirements-tips --- Here are some limits, requirements, and recommendations when you create metrics from events, logs, or spans. ## Metric aggregation [#summary-and-uniquecount] Your NRQL query must use one of the following `summary`, `uniqueCount`, or `distribution` functions to aggregate metrics: | Function | Comments | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `summary` | Creates a summary metric data point for each time window (currently 1 minute). Use this if your NRQL query uses [aggregator functions](https://docs.newrelic.com/docs/insights/nrql-new-relic-query-language/nrql-reference/nrql-syntax-components-functions#functions) supported by the summary metric type, such as `average`, `sum`, `min`, or `max`. **Example rule-creation query:** ````sql SELECT summary(duration) AS 'service.responseTime' FROM Transaction WHERE appName = 'Data Points Staging' FACET name, appName, host ``` ```` | | `uniqueCount` | Creates a `uniqueCount` metric data point for each 1-minute time window. Use this if your NRQL query uses the `uniqueCount` [aggregator type](https://docs.newrelic.com/docs/insights/nrql-new-relic-query-language/nrql-reference/nrql-syntax-components-functions#functions). Example rule-creation query: ````sql FROM Transaction SELECT uniqueCount(request.headers.userAgent) AS 'server.request.header.userAgent.uniqueCount' WHERE appName = 'Browser Monitoring Router' FACET http.statusCode, name, appName, host ``` ```` | | `distribution` | Creates a distribution metric data point for each 1-minute time window. Use this if your NRQL query uses [aggregator functions](https://docs.newrelic.com/docs/insights/nrql-new-relic-query-language/nrql-reference/nrql-syntax-components-functions#functions) such as `percentile`, `histogram`, `min`, `max`, `average`, `sum`, or `count`. Use only the attribute of interest as the argument, and discard the rest of the arguments from `percentile` or `histogram`. The generated metric supports any argument on `percentile` or `histogram`. **Example of creating a `distribution` rule:** ````sql SELECT distribution(duration) AS 'service.responseTime' FROM Transaction WHERE appName = 'Data Points Staging' FACET name, appName, host ``` ```` | | Simple count: `summary(1)` and `sum` | If you want a metric that's a simple count of the events, logs, or spans that match a particular `WHERE` clause, use the `summary(1)` metric. This metric type counts the number of specified events, logs, or spans per minute. When querying the created metric, use the `sum` method to see the result. **Example:** If you want to create a metric named `foo.count` that counts the transactions named `foo`, the NRQL would look like this: ````sql FROM Transaction SELECT summary(1) AS 'foo.count' WHERE name = 'foo' ``` Then, you would query it like this: ```sql FROM Metric SELECT sum(foo.count) SINCE 30 minutes ago ``` For more information about metrics, see our documentation about [metric types](/docs/telemetry-data-platform/ingest-manage-data/understand-data/metric-data-type#metric-types). ```` | ## Rule-creation limits [#limits] These limits affect metric rules creation: | Limits | Comments | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Account limits | An account can have a maximum of 1,000 metric-creation rules. | | Metric rule limits | A rule can: - Create a [maximum of 10 metrics](#multiple-metrics). - Use only one type of data (events, logs, or spans). - Select a maximum of 20 attributes (facets) to include on a metric. | | Time window limits | 50K limit on unique metric-name/attribute-value combinations for a single metric in a 30 second time window. Normal [cardinality limits on rollups](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/metric-api-limits-restricted-attributes/#requirements) will apply. If the 50k in a 30 second window limit is exceeded, the rule is disabled and an [`NrIntegrationError` event](https://docs.newrelic.com/docs/telemetry-data-platform/manage-data/nrintegrationerror) is created in that account that includes: - The rule details - A message about having too many facets - A `newRelicFeature` attribute value of `eventToMetric` | ## Cardinality limits [#attributes-limit] [Rule-creation limits](#limits) include limits on the number of unique combinations of metric name and attribute values. This limit exists because a large number of attributes and/or attribute values can lead to an exponential increase in the size of data reported. **Example metric creation rule that attaches five attributes:** ```sql FROM ProcessSample SELECT summary(ioTotalReadBytes) WHERE entityType = 'ComputeSample' FACET awsRegion, awsAvailabilityZone, commandName, entityName, processId ``` If each of the five attributes reported ten unique values within a one-minute time window, the number of unique metric-name/attribute combinations would theoretically have a maximum of 10x10x10x10x10, or 100,000. Multiple attributes with multiple unique values can lead to a large number of unique metric entries. In practice, this isn't usually the case, because attributes are often related. For example, if one attribute is `hostname` and another is `awsRegion`, when you see hostname A, it will always be in AWS region B; you'd never see hostname A and other AWS region values. This is why it's important, during the [NRQL creation process](#create-nrql), to use the `uniqueCount` function to verify how many unique metric-name/attribute-value combinations your NRQL query is generating. ## Multiple metrics from one rule [#multiple-metrics] A rule can create up to ten metrics. There are no functional differences between metrics created one at a time and those created with a single rule. Reasons for creating multiple metrics with a single rule: - Less likely to reach [rules-per-account limit](#limits). - Easier to add the same attributes to multiple metrics. **Example creating multiple metrics with a single rule:** ```sql FROM Transaction SELECT uniqueCount(request.headers.userAgent) AS 'server.request.header.userAgent.uniqueCount', summary(duration) AS 'server.duration', summary(totalTime) AS 'server.totalTime' WHERE appName = 'Browser Monitoring Router' FACET http.statusCode, name, appName, host ``` ## Metric naming [#naming] A metric is given a name with the `AS` clause, as part of the [NRQL rule-creation process](#create-nrql). In the following NRQL example, the name of the metric is `io.totalread.bytes`: ```sql FROM ProcessSample SELECT summary(ioTotalReadBytes) AS 'io.totalread.bytes' WHERE entityType = 'ComputeSample' FACET awsRegion, awsAvailabilityZone, commandName ``` If there is no name assigned with the `AS` clause, the metric name is the name of the queried attribute. In this example, if no name was assigned, the metric name would be `ioTotalReadBytes`. | Metric names | Requirements and recommendations | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Requirements | Requirements for naming a metric: - Less than or equal to 255 (UTF-16) 16-bit code units. One way to ensure you are under the limit is to keep each string under 127 of whatever is easiest to count. - No spaces. - Start with a letter. Examples of strong metric names: - `rubyvm.memory.heap_used` - `redis.container.cpu.percent` - `memcached.process_virtual_memory.bytes` | | Length and structure | Decide on a name and structure that makes it easy for others to find, understand, and use this metric. - We recommend keeping your metric name under 40 characters for ideal readability. Longer names can get cut off or overlap with other names. - Your metric naming scheme will depend on your business logic. You may want to use namespaces to prefix your metric name, or your names may need to be more general. | | Components within the name | If you want to create components within your metric name (like the source of metrics and the thing you’re measuring), we recommend going from broad to specific (left to right): - Use a dot to separate those components in order to be consistent with our New Relic metric names. - Then, use an underscore to separate words within the dots. **Example:** ``` application.page_view.duration ``` | | Attributes | Avoid putting attributes in your metric name. Attributes are qualities of your metric that you can use to filter or facet your data, like cluster or availability zone. **Example:** If you included availability zone in your metric name, it would mean, for that metric, you wouldn’t be able to see results across all availability zones. | | Changing metric names | If you change a metric name, historical data will **not** be updated to that new name. To query or chart that historical data, you will need to specify the older metric name. |