Events API

Agents capture different types of information, known as events. These events are sent to a single endpoint which then sorts and processes the events. Events can be:

  • Transactions
  • Spans
  • Errors
  • Metrics

You can learn more about events in the APM Data Model.

Endpoint

Send an HTTP POST request to the APM Server intake/v2/events endpoint:

http(s)://{hostname}:{port}/intake/v2/events

For RUM send an HTTP POST request to the APM Server intake/v2/rum/events endpoint instead:

http(s)://{hostname}:{port}/intake/v2/rum/events

Response

On success, the server will respond with a 202 Accepted status code and no body.

Keep in mind that events can succeed and fail independently of each other. Only if all events succeed does the server respond with a 202.

Errors

There are two types of errors that the APM Server may return to an agent:

  • Event related errors (typically validation errors)
  • Non-event related errors

The APM Server processes events one after the other. If an error is encountered while processing an event, the error encountered as well as the document causing the error are added to an internal array. The APM Server will only save 5 event related errors. If it encounters more than 5 event related errors, the additional errors will not be returned to agent. Once all events have been processed, the error response is sent.

Some errors, not relating to specific events, may terminate the request immediately. For example: queue is full, IP rate limit reached, wrong metadata, etc. If at any point one of these errors is encountered, it is added to the internal array and immediately returned.

An example error response might look something like this:

{
  "errors": [
    {
      "message": "<json-schema-err>", 
      "document": "<ndjson-obj>" 
    },{
      "message": "<json-schema-err>",
      "document": "<ndjson-obj>"
    },{
      "message": "<json-decoding-err>",
      "document": "<ndjson-obj>"
    },{
      "message": "queue is full" 
    },
  ],
  "accepted": 2320 
}

An event related error

The document causing the error

An immediately returning non-event related error

The number of accepted events

If you’re developing an agent, these errors can be useful for debugging your agent while building it.

Event API Schemas

The APM Server uses a collection of JSON Schemas for validating requests to the intake API: