REST API for New Relic AI

The incident events API allows you to report any related activities from your own proprietary incident management systems to New Relic for advanced correlation and reasoning. The API supports a generic way of announcing an incident with full flexibility. The more information your system can provide, the better our decision engine works to surface more relevant information to you. Use the attributes field to push your specific information in addition to the mandatory fields.

Authentication

New Relic AI is totally agnostic to the event type, so you can send any type of data straight from your own systems or applications. The REST API supports secure token-based authentication and accepts JSON content as input.

Batching data

We currently support up to 10 events or metrics in the same API call. In order to batch, just append new event or metric data to the body.

A batch must be POSTed as {"events": [{"event_source": "Snap", ...}]} with each event part in a list that is the value of "events", as the following sample shows.

Sample JSON

{
    "events": [{
        "application": "Name of my application",
        "attributes": {
            "alert/description": "Add a description about the alert itself",
            "state": "alarm",
            "application/state": "MAJOR",
            "environment": "prod"
        },
        "event_description": "Add a description about the incident",
        "event_source": "List the application that created the incident",
        "host": "host-name",
        "value": "medium"
    }]
}

Our collector REST deserializer will see if events is the key in the root object and if so, extract and iterate.

Default data size limits

  • Batch – up to 10 messages inside the body.

  • We support up to 20 attributes per metric or event.

  • Each string value field size is limited to 1024 characters.

  • Each attribute name field size is limited to 128 characters.

If you have different requirements for data size/restrictions please contact us as those parameters can be tuned for you.

Make API calls

From the Sources page, click on REST API. Choose the correct account and click on the clipboard icon to copy the New Relic collector URL. The security token should be used in the Authorization: Bearer HTTP header.

Here is an example cURL command using this interface:

curl https://collectors.signifai.io/v1/incidents -XPOST -H"Authorization: Bearer xxxxxxxxxx" -H"Content-Type: application/json" -d '{"application":"myapp","attributes":{"alert/description":"Platform myapp health down","annotations/description":"Service status for myapp","cluster/name":"myapp_001","datacenter/name":"US-EAST-1","health_check/entity_name":"app","service/name":"greatapp","service/status":"down", "state": "alarm"},"event_description":"Myapp is not working","event_source":"status check name","value":"critical","label/namespace":"application namespace"}'

API specifications

Method

API Endpoint

Description

POST

https://collectors.signifai.io/v1/incidents

Sends incident events to New Relic AI (formerly SignifAI) for processing.

Field Description

event_source

String

REQUIRED. Your own representation for the system or application that is generating the event.

Example: {"event_source": "sensu"}

host/service/application

String

REQUIRED. What generated the event. Can be the associated host or, if a host isn't relevant, a service or an application. Note: only one is mandatory.

Example: {"host": "payments001"}

value

String, Boolean (only true is supported)

REQUIRED. Incident priority. String must be one of: critical, high, medium, low
Use a boolean to indicate an event happened

Example: {"value": "high"}

timestamp

Long

Time in UTC that the event occurred since the epoch. Negative timestamps are not supported.

Default: the time our server receives the event

Example: {"timestamp": 1468949954}

event_description (REQUIRED)

String

Free text information that describes this event. Must be set. We recommend setting this field with useful information, as it will get displayed in the UI.

Example: {"event_description": "Deploying my-webservice-1 to the AWS production cluster"}

attributes

JSON Object

A flat key/value mapping of additional attributes about the incident. We currently don't support nested documents or lists.

Any attributes added here will be used by New Relic to perform better correlations.

Example: {"attributes": {"affected_systems": "payment cluster 2", "notify": "bob"}}

De-duplication and identifications

To better support our system’s advanced de-duplication and correlations' capabilities, we recommend supplying a set of labels or an alert ID, as part of the incident’s attributes. Any attribute prefixed with label/ is considered as a label. The combination of the labels, event_source, host, application, and server are used to create unique incidents. If labels are not provided, provide an alert/id attribute which will be used as a de-duplication key.

Significant incident attributes (hints)

Some attributes have enhanced capabilities offered by New Relic. Sending these allows us to give smarter data processing.

Attribute Name Description

service/name

Service name that reported the incident. Assigned from the service field in the payload.

service/status

Instrumented service status.
Can be either up or down.

alert/description

Additional details that describe the specific incident.

annotations/description

The incident description that will be used for representation in the UI.

cluster/name

Identify the cluster name impacted.

datacenter/name

Identify the datacenter name impacted.

health_check/entity_name

The name of the health check originally triggered the incident if available.

runbook_url

In case there is a link for a runbook.

host/name

Instrumented hostname assigned from the host field in the payload.

environment

Environment kind (dev, prod).

application/name

Instrumented application name assigned from the application field in the payload.

application/id

Instrumented application identification.

cloud/region

Region hosting the service (for example: us-east-1).

health_check/id

Health check identification.

health_check/type

Health check type.

health_check/name

Health check name.

health_check/probe_id

Identification of the probe id used for health check.

health_check/probe_name

Name of the probe name used for health check.

organization/name

Organization name (in cases there are more than one).

alert/policy_id

Policy id of the alert.

alert/policy_name

Policy name of the alert.

availability_zone

Instrumented incident availability zone.

instance/type

Instrumented instance type.

instance/name

Instrumented instance name.

alert/id

Alert identification - used to deduplicate incidents (every incident that is received with the same alert/id will be aggregated to the same open incident).

Important: Specifying alert/id manually will deactivate New Relic automatic creation of an alert ID.

alert/metric_name

Metric name that triggered the incident.

label/*

Any attribute prefixed with label/ will be considered as part of the incident deduplication key and will be used to identify the incident.

For more help

Recommendations for learning more: