How do I use Events Service with extensions?

[Bhuvnesh.Kumar]

Contents

• Use Case
• Configuration
  • Events Service Client
  • Creating a Schema
  • Retrieving a Schema
  • Deleting a Schema
  • Publishing Events

Use Case

The AppDynamics Metric Browser only supports numerical values for metrics. In order to store and monitor non-numerical values, AppDynamics has the Events Service platform. The Events Service can be accessed and used through extensions by using the Events Service client from the Java SDK for AppDynamics Extensions.

The Events Service client uses the AppDynamics Analytics Events API to send non-numerical values to the AppDynamics platform. Once this information is sent to the Events Store using the client, you can query it via the Controller UI.

Configuration

In order to configure the Events Service client, you need to fill in certain fields of the config.yml to initiate a connection with the Analytics Events API. These fields are configured as follow:

eventsServiceParameters:
    host:                         # Events Service Host
    port:                         # Events Service Port
    globalAccountName: # Found in Controller -> Settings -> License -> Account
    eventsApiKey:           # Generated from Controller -> Analytics -> Configuration -> API Keys
    useSsl:                      # true/false

Any existing SSL and/or proxy configurations in the config.yml are automatically used while initiating this connection.

Events Service Client

The Events Service Client can perform CRUD operations. The following section explains how a user can perform these operations through an extension.

The Events Service client can be obtained and used in the following manner:

ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager()

For purposes of this article, we'll use the Log Monitoring Extension as an example here. Previously, if the extension captured a match, it would only send the number of match occurrences to the Metric Browser. Now, the extension uses the client to send both the number of matches and the actual log matches as strings to the Events Service API.

Consider the following log snippet:

[Thread-1] 29 Apr 2014 12:31:18,647  INFO DynamicServiceManager - Scheduling DynamicServiceManager at interval of 30 seconds
[Thread-1] 29 Apr 2014 12:31:18,647  DEBUG LifeCycleManager - Started service [DynamicServiceManager]
[Thread-1] 29 Apr 2014 12:31:18,647  INFO LifeCycleManager - Starting services
[Thread-1] 29 Apr 2014 12:31:18,660  DEBUG JMXService - ###### Using config from controller for JMX operations 
[Thread-1] 29 Apr 2014 12:31:18,665  INFO ServerMBeanManagerVersion2 - Initialized MBean Finder with delay=120 secs
[Thread-1] 29 Apr 2014 12:31:18,679  DEBUG MemoryMetricGenerator - Identified minor collection bean :ParNew

Creating a Schema

The first step is to create and register a custom schema with the Analytics Events API using the below method.

public void createSchema(String schemaName, String schemaBody)

The schema defines the overall structure of an Event Type by field and data type. In this case, let's create a schema called LogSchema with the following fields:

- logDisplayName
- logDirectory
- searchPattern
- match

The schema body must be passed to the API as a JSON formatted name-value pair, as follows:

{
 "schema":
 {
   "logDisplayName":"string",
   "logDirectory":"string",
   "searchPattern":"string",
   "match":"string"
 }
}

The supported data types are string, integer, float, boolean and date in either ISO 8601 or UNIX epoch format. Note that the following two timestamp fields are automatically added to every custom schema:

- eventTimestamp (the time at which an event occurs)
- pickupTimestamp (the time at which the event is received by the Events Service)

Once you have defined all the information, this method can be called and used in the following manner: 

ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager().createSchema( schemaName, schemaBody)

Retrieving a Schema

Once a schema has been created, the below method can be used to retrieve its details. A JSON formatted name-value String representing the schema is returned, identical to the body described in point 1.

public String retrieveSchema(String schemaName)

This method can be used in the following manner:

ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager().retrieveSchema( schemaName)

Updating a Schema

This method is used to update an existing schema using an HTTP Patch operation.

public void updateSchema(String schemaName, String schemaUpdates) 

Consider replacing the logDisplayName field in the schema body with logName and adding a new field called fileEncoding. These updates are passed to the client as a String in the following format:

[
 {
   "add": {
     "fileEncoding": "string"
   },
   "rename": {
     "logDisplayName": "logName"
   }
 }
]

This method can be used in the following manner:

ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager().updateSchema( schemaName, schemaUpdates)

Deleting a Schema

These methods can be used to delete one or more previously registered schemas. They can take a single schema as input or a list of schemas.

public void deleteSchema(List<String> schemaNames)
public void deleteSchema(String schemaName)

These method can be used in the following manner:

ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager().deleteSchema( schemaName)

// OR

ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager().deleteSchema( listOfSchemaNames)

 Publishing Events

The Publish Events API call takes a collection of events and stores them in the Events Service storage. The data must comply with an existing schema. If the event data doesn't match an event schema, the API will return a 400 bad request.

public void publishEvents(String schemaName, List<String> eventsToBePublished)

For this example, consider monitoring the log snippet for two patterns:

\\.*DynamicServiceManager.*\\
\\.*JMXService.*\\

The events should look like this:

[{
   "logDisplayName":"Dynamic Service Manager Logs",
   "logDirectory":"Some directory",
   "searchPattern":"\\.*DynamicServiceManager.*\\",
   "match":"[Thread-1] 29 Apr 2014 12:31:18,647  INFO DynamicServiceManager - Scheduling DynamicServiceManager at interval of 30 seconds"
},{
   "logDisplayName":"JMX Service Log",
   "logDirectory":"Some directory",
   "searchPattern":"\\.*JMXService.*\\",
   "match":"[Thread-1] 29 Apr 2014 12:31:18,660  DEBUG JMXService - ###### Using config from controller for JMX operations"
}]

The Events Service client publishes events in batches of 1000 events to conform to the Controller's custom event ingestion limits.

This method can be used in the following manner:

ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager().publishEvents( schemaName, eventsToBePublished)

Detailed information about the Analytics Events API can be found here: Analytics Events API