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 four 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.
  • Web application events - These are notifications that a web path alert profile was violated or cleared
  • Network change events - These are notifications that alert you to changes in the sequence of networks (BGP Autonomous Systems) on the path between a source and a target.

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.

Prerequisites

You can use either HTTPS or HTTP to communicate between APM and your server, though we do not recommend using HTTP. HTTPS is recommended because it provides encrypted communications using Secure Socket Layer (SSL). SSL communications requires that your server has an SSL certificate. If you are using APM-Public Cloud (as opposed to APM-Private Cloud), you’ll need an SSL certificate from a recognized Certificate Authority (CA) as self-signed/untrusted certificates are not supported. Examples of low-cost CAs include:

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. In the webAlertEvents field, set the value to “true” if you want web application events to be sent.
  8. In the networkChangeEvents field, set the value to “true” if you want network change events to be sent.
  9. Click Try it out!
  10. 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,
       "webAlertEvents": false,
       "networkChangeEvents": false,
       "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.

View APM event integration configuration for all users

Note that only Organization Admin users can view APM event integration configuration for all users. If you are not sure what your user role is, see Determine your user role.

To view the APM event integration configuration for all users in an organization hierarchy using APM’s interactive API interface:

  1. In APM, navigate to > API > observer > GET /v3/observer.
  2. In the Parameters section, set allUsers to true.
  3. Click Try it out!
    • The Response Body section contains the current configuration for all users in the same organization hierarchy.
    • 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 and “false” if it is not.

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 network path target.
pathId Integer The ID of the network path the alert occurred on.
pathName String The name of the network path the alert occurred on.
pathServiceQuality String The status of the network 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.
deepLink String A link to the network path details in APM.

Web Application event object

These are notifications that a web path alert condition was violated or cleared.

Property name Type Description
type String The event type: “WEB_PATH_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 web path target.
webAppId Integer The ID of the web app the alert occurred on.
webPathId Integer The ID of the web path the alert occurred on.
workflowName String The name of the workflow the alert occurred on.
milestoneName String The name of the workflow milestone the alert occurred on.
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.
deepLink String A link to the web path details in APM.

Network change event object

These are notifications that a change in the sequence of networks (BGP Autonomous Systems) on the path between a source and a target has occurred.

Property name Type Description
type String The event type: “NETWORK_CHANGE_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 network path target.
orgId Integer The ID of the organization the monitoring point belongs to.
orgName String The name of the organization the monitoring point belongs to.
pathId Integer The ID of the network path the alert occurred on.
pathName String The name of the network path the alert occurred on.
tracerouteProtocol String The protocol this traceroute was run with (icmp, udp, or tcp).
oldAsnSequence String The list of AS networks the traceroute took on the previous test.
newAsnSequence String The list of AS networks the traceroute took on the current test (triggering this event).
deepLink String A link to the network path details in APM.
Call Support: 800-664-4401
Contact Us