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:
- Generate a for the account you want to report data to.
- Before you get started creating custom attributes, review the Event API's limits and restricted characters.
- Generate the JSON for your incident event that follows our JSON format guidelines.
- 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 |
---|---|
string, number, or timestamp | REQUIRED Any attribute prefixed with 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
|
enum: (trigger, resolve) | REQUIRED Whether the event should trigger a new incident or resolve an existing one. Updates to the incident can also be sent using trigger. |
enum: (low, medium, high, critical) | The incident's priority. Default: high. Highest priority will be used when different priorities are sent. |
string | REQUIRED, when The triggering event's title. |
string | REQUIRED, when The origin of the incident, or the monitoring system that triggered it (not the entity that faulted). |
string | The triggering event's description. |
string | A deep link to a page related to the incident. |
string | A runbook URL. |
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. |
string | The name of the entity that generated the incident. |
string | The ID of the entity that generated the incident. |
float | The current format's version. |