The APM event integration functionality provides you the ability to have APM events sent to a server or servers of your choice so that you can process the events as required. There are three different event types that can be sent:

  • Test events - These are notifications that a diagnostic test has completed (or was halted).
  • Sequencer events - These are notifications that APM lost or reestablished connectivity with a monitoring point.
  • Service quality events - These are notifications that an alert condition was violated or cleared.

Each event that is sent consists of data in JSON format. There is a different JSON object for each event type. The properties within each object are described in Event data.

In addition, as it is possible for APM to blacklist your server if it is not responding for an extended period, there is a way to determine if your server is blacklisted.

APM event integration is configured using the observer API endpoint in the APM API.

Configure APM event integration

Configuring APM event integration consists of specifying the URL of the server you want to send the events to and the type of events you want to send there. You can send all event types to a single server or different event types to different servers by creating a separate configuration for each server.

To configure APM event integration using APM’s interactive API interface:

  1. In APM, navigate to > API > observer > POST /v3/observer.
  2. In the Parameters section, click the box under Model Schema on the right.
    • The JSON is copied to the body field.
  3. In the url field, replace “string” with the URL of the server to send events to.
  4. In the testEvents field, set the value to “true” if you want test events to be sent.
  5. In the seqEvents field, set the value to “true” if you want sequencer events to be sent.
  6. In the sqaEvents field, set the value to “true” if you want service quality events to be sent.
  7. Click Try it out!
  8. Confirm that the configuration change was made successfully.
    • The Response Body section should contain the values you entered.
    • The Response Code should be 200.

Repeat the above procedure for each server you want events sent to.

Example

The following example is the JSON required to send Sequencer and Service Quality events to https://myserver.myorg.org.

   [
     {
       "url": "https://myserver.myorg.org",
       "testEvents": false,
       "seqEvents": true,
       "sqaEvents": true,
       "blacklisted": false
     }
   ]

View APM event integration configuration

To view the APM event integration configuration using APM’s interactive API interface:

  1. In APM, navigate to > API > observer > GET /v3/observer.
  2. Click Try it out!
    • The Response Body section contains the current configuration.
    • The Response Code should be 200.

Delete APM event integration configuration

Deleting the APM event integration configuration removes the configurations for all servers you have specified.

To delete the APM event integration configuration using APM’s interactive API interface:

  1. In APM, navigate to > API > observer > DELETE /v3/observer.
  2. Click Try it out!
    • The Response Body section contains the response.
    • The Response Code should be 200.

Determine if a server is blacklisted

If an APM event integration server you have configured goes offline and does not respond to 10 events in a row (by default), the server will be blacklisted and no more events will be sent to it. If you want to remove it from the blacklist, see Remove a server from the blacklist.

To determine if a server is blacklisted:

  1. In APM, navigate to > API > observer > GET /v3/observer.
  2. Click Try it out!
    • The Response Body section contains the current configuration.
    • The Response Code should be 200.
    • The blacklisted field is “true” if the server is blacklisted.

Remove a server from the blacklist

To remove a server from the blacklist you must delete its configuration. See Delete APM event integration configuration.

To have a server or servers receive events again they must be reconfigured. See Configure APM event integration.

Event data

APM sends an APM event integration server different JSON objects for each different event type. The properties in each object are described below.

Test event object

These are notifications that a diagnostic test has completed (or was halted).

Property name Type Description
type String The event type: “TEST_EVENT”.
description String A description of the event.
eventTime Long The time the event occurred in “UNIX time” (the number of seconds elapsed since midnight (UTC) on January 1, 1970).
sequencerName String The name (in APM) of the monitoring point that initiated the diagnostic test.
sequencerHost String The hostname of the monitoring point that initiated the diagnostic test.
target String The URL of the target for the diagnostic test.
testId Integer The test ID.
name String The user-specified name of the test.
testStatus String The test status. Valid values include:
- UNKNOWN
- RUNNING
- COMPLETED
- STOPPED
- STARTED
- FAILED
- QUEUED
- INITIALIZING
- SKIPPED
dataReadiness String The path’s suitability to handle data intensive applications. Valid values include:
- NA
- UNKNOWN
- NO_CONNECTIVITY
- VERY_POOR
- POOR
- MARGINAL
- GOOD
- EXCELLENT
voiceReadiness String The path’s suitability to handle voice traffic. Valid values include:
- NA
- UNKNOWN
- NO_CONNECTIVITY
- VERY_POOR
- POOR
- MARGINAL
- GOOD
- EXCELLENT
orgId Integer The ID of the organization the monitoring point belongs to.
orgName String The name of the organization the monitoring point belongs to.

Sequencer event object

These are notifications that APM lost or reestablished connectivity with a monitoring point.

Property name Type Description
type String The event type: “SEQUENCER_EVENT”.
description String A description of the event.
eventTime Long The time the event occurred in “UNIX time” (the number of seconds elapsed since midnight (UTC) on January 1, 1970).
sequencerName String The name (in APM) of the monitoring point that lost or regained connectivity.
sequencerHost String The hostname of the monitoring point that lost or regained connectivity.
sequencerStatus String Monitoring point status. Valid values include:
- AVAILABLE
- UNAVAILABLE
- REMOVED
- NEW
- BLOCKED
orgId Integer The ID of the organization the monitoring point belongs to.
orgName String The name of the organization the monitoring point belongs to.

Service Quality event object

These are notifications that an alert condition was violated or cleared.

Property name Type Description
type String The event type: “SQA_EVENT”.
description String A description of the event.
eventTime Long The time the event occurred in “UNIX time” (the number of seconds elapsed since midnight (UTC) on January 1, 1970).
sequencerName String The name (in APM) of the monitoring point that had the alert condition.
sequencerHost String The hostname of the monitoring point that had the alert condition.
target String The URL of the path target.
pathId Integer The ID of the path the alert occurred on.
pathName String The name of the path the alert occurred on.
pathServiceQuality String The status of the path with respect to its Alert Profile. Valid values include:
- SKIPPED
- NONE
- SQA_NOT_VIOLATED
- INDETERMINATE
- SQA_VIOLATED
- DISABLED
measuredParam String The parameter the alert occurred on.
measuredValue Float The value of the parameter when the alert occurred.
orgId Integer The ID of the organization the monitoring point belongs to.
orgName String The name of the organization the monitoring point belongs to.