Skip to content

Latest commit

 

History

History
327 lines (258 loc) · 12.6 KB

create-metrics-other-data-types.mdx

File metadata and controls

327 lines (258 loc) · 12.6 KB
Raw
title tags metaDescription redirects freshnessValidatedDate
Create metrics from other data types
Ingest and manage data
Convert data to metrics
How to create a rule in New Relic to turn data for events, logs, or spans into metric data.
/docs/telemetry-data-platform/convert-to-metrics/create-metrics-other-data-types
/docs/events-metrics-api-create-metrics
/docs/events-metrics-service-create-metrics
/docs/data-ingest-apis/get-data-new-relic/metric-api/events-metrics-service-create-metrics
/docs/accounts/accounts/data-management/events-metrics-create-metrics
/docs/telemetry-data-platform/ingest-manage-data/convert-event-data-metrics/events-metrics-create-metrics
/docs/telemetry-data-platform/ingest-manage-data/convert-data-metrics/events-metrics-create-metrics
/docs/telemetry-data-platform/ingest-manage-data/convert-data-metrics/create-metrics-other-data-types
never

Use New Relic's metrics API service to define rules for creating metrics from your other types of data, such as events, logs, or spans. Recommendation: Before you begin, review our requirements and tips for creating rules.

Create a metrics rule [#overview-process]

To create a rule for creating metrics from events, logs, or spans:

  1. Construct the metrics rule using NRQL.
  2. Construct a NerdGraph (GraphQL format) API request that contains your NRQL rule.
  3. Create the metric by making the API request.

Once a metric is created, you can query and chart it using NRQL.

Step 1. Create NRQL query rule [#create-nrql]

The most important part of creating a metrics rule is constructing the NRQL query that defines the metric for your data from events, logs, or spans. You can create up to 10 metrics with a single NRQL query by following this procedure:

  1. Using New Relic's NRQL interface, construct a query for the metric you want to create. For example:

    FROM ProcessSample SELECT average(ioTotalReadBytes)
WHERE nr.entityType = 'HOST'
[Events to metrics](/docs/data-apis/convert-to-metrics/analyze-monitor-data-trends-metrics/) rules don't support the `WITH ... AS` clause in [NRQL queries](/docs/query-your-data/nrql-new-relic-query-language/get-started/introduction-nrql-new-relics-query-language/).

  1. Edit the query to use one of the three available metric types:

    • summary: Use if the query's function is min, max, sum, count, or average.

    • uniqueCount: Use if the query's function is uniqueCount.

    • distribution: Use if the query's function is percentile or histogram.

      This example query uses average, so use summary:

      FROM ProcessSample SELECT summary(ioTotalReadBytes)
WHERE nr.entityType = 'HOST'

      This example query uses count on a non-numeric field:

      FROM ProcessSample SELECT count(hostname)
WHERE hostname LIKE '%prod%'

      For summary on a non-numeric field use summary(1):

      FROM ProcessSample SELECT summary(1)
WHERE hostname LIKE '%prod%'
      For more detailed information on using these metric types in rules, see [Creating metric rules: requirements and tips](/docs/telemetry-data-platform/ingest-manage-data/convert-data-metrics/creating-metric-rules-requirements-tips).

  2. Decide on the attributes you want to attach to the metric, following the limits on the cardinality of unique metric-name/attribute-value combinations.

    Recommendation: Run a separate query to ensure the maximum cardinality isn't over 50,000 for a 30 second window. For example, the following query will find the maximum cardinality encountered in a 30 second period over the last 3 hours for the ProcessSample event when including the awsRegion, awsAvailabilityZone, and commandName attributes:

    FROM (FROM ProcessSample
SELECT rate(uniqueCount(awsRegion, awsAvailabilityZone, commandName), 30 seconds) AS 'cardinalityRate'
WHERE nr.entityType = 'HOST' TIMESERIES 30 seconds) SELECT max(cardinalityRate) AS 'maxCardinalityRate' SINCE 3 hours AGO

  3. To be able to aggregate and filter your metrics, add the attributes you want to attach to the metric using the FACET clause. For example:

    FROM ProcessSample
SELECT summary(ioTotalReadBytes) WHERE nr.entityType = 'HOST'
FACET awsRegion, awsAvailabilityZone, commandName

  4. Set the name of the metric using the AS function. For example:

    FROM ProcessSample SELECT summary(ioTotalReadBytes) AS 'io.totalread.bytes'
WHERE nr.entityType = 'HOST' FACET awsRegion, awsAvailabilityZone, commandName

Once your NRQL rule is complete, use it to create the API request.

Step 2. Create API request [#create-request]

After you build the NRQL rule to convert data from events, logs, or spans to metrics, continue with building the API request. You can use our NerdGraph API tool to explore the data structure and to construct and make your request.

To check that the rule was created correctly, you can run a query to return that rule using its ID. For tips on querying the metrics you've created, see Query and chart your metrics.

The following example NerdGraph API request uses the same NRQL rule from step 1. The `IO Total Read Bytes Rule` creates a metric named `io.totalread.bytes`. (The rule name can have spaces, which differs from the [metric naming rules](#naming).) 
```graphql
mutation {
  eventsToMetricsCreateRule(
    rules: {
      name: "io.totalread.bytes for computeSample entities",
      description: "Created by Zach on March 27, 2019. Used by team Network.",
      nrql: "FROM ProcessSample SELECT summary(ioTotalReadBytes) AS 'io.totalread.bytes' WHERE nr.entityType = 'ComputeSample' FACET awsRegion, awsAvailabilityZone, commandName",
      accountId: 123456
    }
  ) {
    successes {
      id
      name
      nrql
      enabled
    }
    failures {
      submitted {
        name
        nrql
        accountId
      }
      errors {
        reason
        description
      }
    }
  }
}
```

In this request:

<table>
  <thead>
    <tr>
      <th style={{ width: "200px" }}>
        Request elements
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `mutation`
      </td>

      <td>
        One of the basic [API operation types](/docs/apis/graphql-api/getting-started/introduction-new-relic-graphql-api#tutorials).
      </td>
    </tr>

    <tr>
      <td>
        `eventsToMetricsCreateRule`
      </td>

      <td>
        The method being called to create a rule.
      </td>
    </tr>

    <tr>
      <td>
        `rules`
      </td>

      <td>
        Takes four parameters:

        * `name`: The [name of the rule](#naming).
        * `description`: Optional. The description of the rule. We recommend you include information about who created the metric data and who will be using the data.
        * `accountId`: The [New Relic account ID](/docs/accounts/install-new-relic/account-setup/account-id) where the events, logs, or spans live and the metrics will be created.
        * `nrql`: The NRQL query that creates the rule. For more on this, see [Create NRQL query](#create-nrql).
      </td>
    </tr>

    <tr>
      <td>
        `successes` and `submitted` blocks
      </td>

      <td>
        Here you define the data returned by a successful or failed response. Available parameters for these blocks include:

        * `id` (`ruleId` for `submitted`)
        * `name`
        * `description`
        * `nrql`
        * `enabled` (enabled/disabled status)
        * `accountId`
      </td>
    </tr>

    <tr>
      <td>
        `ruleId` and `accountId`
      </td>

      <td>
        If a failure occurs, then the submitted `ruleId` and `accountId` will be returned along with the error reason and error description.
      </td>
    </tr>
  </tbody>
</table>

<Collapser id="example-response" title="Example NerdGraph API response"

Here's an example of a returned response:

```json
{
  "data": {
    "eventsToMetricsCreateRule": {
      "failures": [],
      "successes": [
        {
          "enabled": true,
          "id": "46",
          "name": "io.totalread.bytes for computeSample entities",
          "nrql": "FROM ProcessSample SELECT summary(ioTotalReadBytes) AS 'io.totalread.bytes' WHERE nr.entityType = 'ComputeSample' FACET awsRegion, awsAvailabilityZone, commandName"
        }
      ]
    }
  }
}
```

Step 3. Create a metrics rule with API request [#graphql-api-request]

When your API request is ready, you can use the NerdGraph API to make the request, which will create the metrics.

Query and chart your metrics [#find-your-data]

After you create a metrics rule to convert data for your events, logs, or spans, you can view the new metric data in the New Relic UI. To view your data:

  1. Go to New Relic's NRQL query interface.

  2. Run the following query to see the name of all your metrics:

    SELECT uniques(metricName) FROM Metric

  3. Pick the metric of interest, then run the following query to see the available attributes:

    SELECT * FROM Metric WHERE metricName = 'yourMetric'

  4. If you don't see expected data, follow the troubleshooting procedures.

The available NRQL aggregator functions depend on the metric type you created. Here are some examples.

If you created a summary metric type, you can use the `count`, `sum`, `max`, `min`, and `average` aggregator functions, as shown in the following query: 
```
SELECT count(appStartResponseTime), sum(appStartResponseTime), max(appStartResponseTime), min(appStartResponseTime),  average(appStartResponseTime) FROM Metric
```

<Collapser id="uniqueCount" title="Count metric example"

If you created a `uniqueCount` metric type, you can only use the `uniqueCount` function, as shown in the following query:

```sql
SELECT uniqueCount(playbackErrorStreamUniqueCount) * 100 / uniqueCount(streamUniqueCount) AS '% of Streams Impacted' FROM Metric
```

<Collapser id="distribution" title="Distribution metric example"

If you created a `distribution` metric type, use the `percentile` or `histogram` functions, as shown in the following queries:

```sql
SELECT percentile(service.responseTime, 95) FROM Metric
```

OR

```sql
SELECT histogram(service.responseTime, 10, 20) FROM Metric
```

Troubleshooting

If your NerdGraph call is not constructed correctly, you may receive a message like this:

Cannot parse the unexpected character "\u201C”

Verify the quotes in the NerdGraph call are not smart quotes (curly quotes). Our NerdGraph API only accepts straight quotes.