• Log inStart now

Incident event REST API

You can use the Event API to report custom applied intelligence incident events to New Relic.

The API is an asynchronous endpoint. This means you can send a large volume of POSTS, reliably, with low-response latency.

Using the API: an overview

Here's the general process for sending custom incident events to New Relic via the incident event API:

  1. Generate a license key for the account you want to report data to.
  2. Before you get started creating custom attributes, review the Event API's limits and restricted characters.
  3. Generate the JSON for your incident event that follows our JSON format guidelines.
  4. Submit a compressed JSON payload (for example, gzip or deflate) to the HTTPS endpoint using curl in a POST request.

Once you've started sending incident event data to New Relic, we recommend that you set up NRQL alert conditions to get notifications about parsing errors.

Example JSON

Your JSON payload may look something like this example.

[
{
"eventType": "NrAiIncidentExternal",
"title": "Test",
"description": "The latency is above threshold of 500000 MS",
"state": "trigger",
"source": "luna",
"entityName": "testEntity",
"entity.guid": "testEntity123",
"aggregationTag.serviceId": 5,
"aggregationTag.environment": "testing",
"aggregationTag.errorId": 10543,
"tag.stackTrace": "some stack trace...",
"version": 1
}
]

The eventType field must use NrAiIncidentExternal.

Send your incident event from the command line

Here's an example of how to use curl to send your JSON payload.

gzip -c example_incidents.json | curl --data-binary @- -X POST -H "Content-Type: application/json" -H "Api-Key: YOUR_LICENSE_KEY" -H "Content-Encoding: gzip"
https://insights-collector.newrelic.com/v1/accounts/YOUR_ACCOUNT/events
Response
{"success":true, "uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}%

Once you've successfully sent your incident event data, you can see it in the applied intelligence UI or by querying that data.

Example query for incident events

You can query your data with Nerdgraph API.

Here's an example of a NerdGraph query and its result.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      nrql(query: "SELECT * FROM NrAiInternalIncident since 3 days ago") {
        results
      }
    }
  }
}
"results": [
  {
    "timestamp": 1641910123824,
    "totalViolations": 3,
    "violationIds": "[416e2e55069764086ad83e97a1160be0cb4c545b7950522f7c86baaa2a11b9b6]",
    "triggeredAt": 1641909163980,
    "entitiesData.ids": "testEntity123",
    "entitiesData.types": "unknown",
    "labelsHash": "91f938318e899dcd62965e2724548f4844f2898f3cf1c5411397ecc0eec87fc1",
    "annotations.description": "[\"The latency is above threshold of 500000 MS\"]",
    "labels.originalAccountIds": "YOUR_ACCOUNT_ID",
    "entitiesData.names": "testEntity",
    "entitiesData.entities": "{\"id\":\"testEntity123\",\"name\":\"testEntity\",\"type\":\"unknown\"}",
    "priority": "HIGH",
    "labels.serviceId": "5",
    "labels.environment": "testing",
    "closedAt": "",
    "updatedAt": 1641910123824,
    "annotations.title": "[\"Test\",\"Test2222\",\"Test3\"]",
    "nrAccountId": YOUR_ACCOUNT_ID,
    "accumulations": "{\"source\":[\"rest\"],\"origin\":[\"luna\"],\"entity_guid\":[\"testEntity123\"],\"tag.stackTrace\":[\"some stack trace...\"]}",
    "labels.accountIds": "YOUR_ACCOUNT_ID",
    "createdAt": 1641909163997,
    "priority.order": 2,
    "labels.aggregationKeys": "416e2e55069764086ad83e97a1160be0cb4c545b7950522f7c86baaa2a11b9b6",
    "accumulations.origins": "[\"luna\"]",
    "accumulations.entity_guid": "[\"testEntity123\"]",
    "incidentId": "a06ffb92-2f7e-473b-953f-151ff4777cb0",
    "labels.errorId": "10543",
    "dataMLModules": "{}",
    "triggerEvent": "VIOLATION_ADDED",
    "accumulations.tag.stackTrace": "[\"some stack trace...\"]",
    "isIint": false,
    "accumulations.sources": "[\"rest\"]",
    "entitiesData": "{\"name\":\"testEntity\",\"id\":\"testEntity123\",\"type\":\"unknown\",\"entities\":\"{\\\"id\\\":\\\"testEntity123\\\",\\\"name\\\":\\\"testEntity\\\",\\\"type\\\":\\\"unknown\\\"}\"}",
    "annotations": "{\"title\":[\"Test\",\"Test2222\",\"Test3\"],\"description\":[\"The latency is above threshold of 500000 MS\"]}",
    "labels": "{\"accountId\":\"XXXXXXX\",\"originalAccountId\":\"XXXXXXX\",\"entityId\":\"testEntity123\",\"entityName\":\"testEntity\",\"entityType\":\"unknown\",\"aggregationKey\":\"416e2e55069764086ad83e97a1160be0cb4c545b7950522f7c86baaa2a11b9b6\",\"serviceId\":\"5\",\"errorId\":\"10543\",\"environment\":\"testing\"}",
    "state": "CREATED"
  }
]

Incident event API specification

The incident event API uses the Event API's value types. For descriptions of these value types and guidelines on using them, see our event API JSON guidelines.

Field

Description

aggregationTag.*

string, number, or timestamp

REQUIRED

Any attribute prefixed with aggregationTag will be used to aggregate trigger events together.

In other words, two trigger events with the same aggregation tags are aggregated to the same incident. (This assumes there's no resolve event between them).

When resolving incidents, it’s important that the resolve event include the same aggregation tags.

Aggregations tags with reserved keywords are filtered out. For example, in a JSON payload with aggregationTag.priority: 2 this key-value pair will be omitted in the incident event with these reserved keywords:

reserved_key: {"priority", "accountId", "originalAccountId", "policyId", "conditionId", "aggregationKey", "entityType", "entityName", "entityId", "violationUuid", "violationId", "nrIncidentId" }

state

enum: (trigger, resolve, acknowledge)

REQUIRED

Whether the event should trigger a new incident or resolve an existing one.

priority

enum: (low, medium, high, critical)

The incident's priority. Default: high.

Highest priority will be used when different priorities are sent.

title

string

REQUIRED, when state is trigger

The triggering event's title.

source

string

REQUIRED, when state is trigger

The origin of the incident, or the monitoring system that triggered it (not the entity that faulted).

description

string

The triggering event's description.

deepLinkUrl

string

A deep link to a page related to the incident.

runbookUrl

string

A runbook URL.

externalId

string

An external ID you can attach to the event.

For example, it can be used to query for errors related to ingesting this event.

entityName

string

The name of the entity that generated the incident.

entity.guid

string

The ID of the entity that generated the incident.

version

float

The current format's version.

Copyright © 2022 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.