Introduction to the events-to-metrics service

New Relic provides an events-to-metrics service that lets you create metrics from your event-type data. Metrics are aggregates of your event data and are ideal for analyzing and monitoring trends over long time periods.

This document explains:

Why create metrics from event data?

Historically, in New Relic Insights, NRQL queries and charts were created only with event-type data. With the new events-to-metrics feature, you can create metrics from your event data and create queries and charts from those metrics. Using metrics allows for more efficient data storage, which in turn allows for faster, more efficient data queries and chart-builds.

Here's an explanation of these two types of data:

  • Events: Event data represents a record of a single event at a specific moment in time. For example, you may have an event for every request to the system. This data is ideal for in-depth troubleshooting and analysis.
  • Metrics: These provided an aggregated view of your event data. Metrics are better for showing trends over longer time ranges. For example, you could aggregate the total number of requests per service to one metric and then examine this month-over-month.

Note that creating metrics from events will not delete events; this feature creates metrics from the event data without altering the events.

More details on what makes metrics unique and better for longer-range queries and charting:

  • Metrics are dimensional; you get to choose what metadata (like host name or app name) is attached to them.
  • The data has already been pre-aggregated into longer-period time buckets.
  • Common metric measurements, like average, sum, minimum, and maximum, are already calculated
  • Data retention is 13 months.
  • Metrics are queryable in Insights via the Metric event type.

Get started creating an events-to-metrics rule.

Available operations

To perform events-to-metrics operations, you'll use the New Relic GraphQL API. Before performing any operation, we recommend reading Intro to GraphQL API and exploring your data with the GraphiQL API tool.

The events-to-metrics feature’s operations fall under two basic GraphQL request types:

  • Mutations, which are operations that make changes to existing rules or settings (for example, creating a new events-to-metrics rule).
  • Queries, for fetching existing data (for example, fetching existing events-to-metrics rules).

All metrics-to-events operations are role-based. When performed via the GraphQL API, they'll be made under the currently logged-in New Relic user.

Mutations

Mutation operations include:

Create an events-to-metrics rule

See Create metrics.

Delete a rule

This operation modifies production settings, so we recommend thoroughly reviewing your changes before you run the operation.

To delete a rule, you need the rule ID and the New Relic account ID. Here's an example request:

mutation {
  eventsToMetricsDeleteRule(deletes: {ruleId: "12", accountId: 123456}) {
    successes {
      id
      name
      nrql
    }
    failures {
      errors {
        description
        reason
      }
      submitted {
        ruleId
        accountId
      }
    }
  }
} 

Let's look at some elements of this request:

  • mutation: one of the basic GraphQL API operation types.
  • eventsToMetricsDeleteRule: The method being called to delete a rule.
  • deletes takes two parameters:

  • In the successes and submitted blocks, you define the data returned by a success or failure. Available parameters for these blocks: id (ruleId for submitted), name, description, nrql, enabled, and accountId.

Here's an example response for the above example request:

{
  "data": {
    "eventsToMetricsDeleteRule": {
      "failures": [],
      "successes": [
        {
          "id": "12",
          "name": "Test Rule",
          "nrql": "select summary(duration) as 'server.responseTime' from Transaction where appName = 'Data Points Staging' facet name, appName, host"
        }
      ]
    }
  }
}
Enable/disable a rule

This operation modifies production settings, so we recommend thoroughly reviewing your changes before you run the operation.

To disable or enable an existing events-to-metrics rule, you use the same eventsToMetricsUpdateRule operation, with the only difference being whether enabled is set to true or false Here's an example request for enabling an existing events-to-metrics rule:

mutation {
  eventsToMetricsUpdateRule(updates: {ruleId: "12", accountId: 123456, enabled: true}) {
    successes {
      id
      name
      nrql
    }
    failures {
      errors {
        description
        reason
      }
      submitted {
        ruleId
        accountId
      }
    }
  }
} 

Let's go through some elements of this request:

  • mutation: one of the basic GraphQL API operation types.
  • eventsToMetricsUpdateRule: The method being called to update an existing rule and either enable it or disable it.
  • updates takes three required parameters:
    • ruleId: The ID of the events-to-metrics rule.
    • accountId: The New Relic account ID.
    • enabled: To enable a disabled rule, set this to true. To disable a rule, set this to false.
  • In the successes and submitted blocks, you define the data returned by a success or failure. Available parameters for these blocks:
    • id (ruleId for submitted)
    • name
    • description
    • nrql
    • enabled
    • accountId

Queries

Query operations include:

List all rules for a New Relic account

You can choose to list all rules in a New Relic account, or return a specific rule. Below is an example of listing of all rules for an account 123456:

query {
  actor {
    account(id:123456) {
      eventsToMetrics{
        allRules{
          rules{
            id
            name
            enabled
            nrql
            description
          }
        }
      }
    }
  }
}

Let's go through some elements of this request:

  • query: one of the basic GraphQL API operation types, used for querying but not making changes.
  • actor: This specifies the current user.
  • account(id: 123456): Specify the ID for the New Relic account to retrieve data from.
  • eventsToMetrics: Scope the data to only events-to-metrics rules.
  • allRules: Returns all rules for that account.
  • rules: In the rules block, you can define what data you want returned. Available fields include:
    • id
    • name
    • description
    • nrql
    • accountId
    • enabled

Here's an example response:

{
  "data": {
    "actor": {
      "account": {
        "eventsToMetrics": {
          "allRules": {
            "rules": [
              {
                "description": "Metric for total time",
                "enabled": true,
                "id": "1",
                "name": "Total Time Tx",
                "nrql": "select summary(totalTime) as 'server.totalTime' from Transaction where appName = 'Data Points Staging' facet name, appName, host"
              },
              {
                "description": "Metric for duration",
                "enabled": true,
                "id": "2",
                "name": "Duration Rule",
                "nrql": "select summary(duration) as 'server.responseTime' from Transaction where appName = 'Data Points Staging' facet name, appName, host"
              }
            ]
          }
        }
      }
    }
  }
}
List rule by rule ID

If you know the exact ID for a rule, then you can query for a specific rule. For example, you may have just created a rule and now want to list its contents to review it. Below is an example listing rule number 36 for New Relic account 123456:

query {
  actor {
    account(id: 123456) {
      eventsToMetrics {
        rulesById(ruleIds:  "36") {
          rules {
            id
            name
            enabled
            nrql
            description
            accountId
          }
        }
      }
    }
  }
}

For more detail about the elements in this query, see List all rules.

Here's an example response:

{
  "data": {
    "actor": {
      "account": {
        "eventsToMetrics": {
          "rulesById": {
            "rules": [
              {
                "accountId": 123456,
                "description": "Metric for total time",
                "enabled": true,
                "id": "36",
                "name": "Total Time Tx",
                "nrql": "select summary(totalTime) as 'server.totalTime' from Transaction where appName = 'Data Points Staging' facet name, appName, host"
              }
            ]
          }
        }
      }
    }
  }
}

Use the GraphiQL API tool

You can use the GraphiQL API tool to explore the data structure, and to build and run the events-to-metrics operations. To use this tool:

  1. Once you have an operation's request created with the required parameters, go to the GraphiQL API tool and paste your query into the box on the left.
  2. Execute the operation by pressing Play. (Optionally, you can get the cURL format by selecting Copy as cURL.)
  3. Validate the response in the response box on the right side. If you'd like to verify a rule-creation operation was performed successfully, you can run a list query for that rule ID.

Related reading:

For more help

Recommendations for learning more: