Introduction to events-to-metrics service

Original
pricing
plan

This doc is for accounts on our original product-based pricing. If you're on our newer pricing plan, see New Relic One pricing plan. Not sure which you're on? See Overview of pricing plans.

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

This document explains:

Why create metrics from event data?

Historically, in New Relic, 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 provide 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.

For more on how metrics and events are different, see Understand data types.

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 querying/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 with NRQL using the Metric event type.

Start creating an events-to-metrics rule.

Available operations

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

The events-to-metrics feature’s operations fall under two basic 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 NerdGraph, 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 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 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 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 NerdGraph GraphiQL API tool

You can use our 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

If you need more help, check out these support and learning resources: