Events Query

Overview

The BIG-IQ Events Query API enables you to retrieve the number of events which have occurred during a time interval and fetch information about specific events. The BIG-IQ monitors the system by tracking events. An event is a single occurrence of something we may wish to understand which itself does not have a numerical value and which is not dependent upon any other event. For example, the occurrence of a server not responding in the system can be tracked as a “server not responding” event. An event can also possess properties, for example, a HTTP transaction event can have properties like “Server-Latency” or “Request-Size”.

The Events Query API can be used to get information about events, whereas the BIG-IQ Metrics API can be used to fetch statistical information about system metrics. The BIG-IQ HTTP Traffic Query API enables you to retrieve information about HTTP transactions.

REST Endpoint: /mgmt/ap/query/v1/tenants/{tenant-id}/event-query

If there are multiple tenants, the placeholder {tenant-id} represents the ID of the specific tenant being queried. If there is only one tenant this value can be default.

Requests

POST /mgmt/ap/query/v1/tenants/{tenant-id}/event-query

You can send a POST request to the event-query endpoint to retrieve a summary of events or the event details.

Request Parameters

The JSON in the body of the POST request can include the following parameters.

Name Type Required Description
aggregationGroups array False A list of aggregationGroup items which are counts grouped together. For example, the list can include the category, logLevel and type groups. Optional, but can be used to request an event summary.
fields array False A list of event fields. If showAllFields is false, the response includes only the default fields and fields provided in the fields list. Can be used to request some, but not all, event details.
filter object False A filter constrains which event properties are queried. Basic filter types are Binary Predicate, In Predicate and Match Filter. A filter can be a simple constraint or a complex logical expression. For more explanation, see the Filters section.
     args array False Used to combine basic filters into complex filters. The type of arg can be “and” or “or”.
     field string Required with a filter. The event field that the filter compares to value.
     type string Required with a filter. Specifies the kind of filter. For more explanation see the Filters section.
     value string Required with a filter. The string, number or boolean value the filter compares to the event field specified in field.
isListDisplay boolean True For true, the query returns only the total number of events per aggregation group. For false, the query also returns the event distribution across points in time. Used when making a request for a summary of events.
isStatisticsBounded boolean False True binds the results for events to the same time frames as would be returned by the BIG-IQ Metrics API used for metrics. This can be useful when displaying events and metrics information on the same chart. Optional, but can be used when making a request for event details.
kind string True A keyword which identifies the kind of event query. Use “ap:query:event:eventSummary” to request a summary of events that returns the total and a series of data points through time. Use “ap:query:event:eventDetails” to request event details. See the Examples section for examples of a events summary and an event details query.
limit number False Limits the maximum number of results returned. This can be useful to improve performance when queries for event details return a large amount of information. Used when making a request for event details.
showAllFields boolean False If true, the response includes all fields which exist for each event. If false, the response includes only default fields and fields in the fields list. Used when making a request for event details.
skip number False The starting point for reporting events. Can be used to perform multiple queries by providing the number of events as limit and specifying the next number of events as skip with each query. The default value is 0. Optional, but can be used when making a request for event details.
timeGranularity object True The time granularity is a value which controls the time interval between one data point and another. It is approximately the size of the bucket used to aggregate several data points. Optional, but can be used when making a request for an event summary. Note that the response can have an actual time granularity different from that which was requested. See the section below about Requested versus actual time granularity and range.
     duration number Required with timeGranularity. Duration of the time interval in units specified by unit.
     unit string Required with timeGranularity. Possible values: “SECONDS”, “MINUTES”, “HOURS” or “DAYS”.
timeRange object True Specifies the start and end times for the query. Can be formatted as epoch time, for example, the time range can be specified as “from”: “1437584763000000” and “to”: “1437584773000000”. The time range can also be specified relative to current time. For example, a time interval of between 12 hours ago and now can be formatted as “from”: “-P12H”, “to”: “now”. A time interval of between 2 days ago and yesterday can be formatted as: “from”: “-P2D”, “to”: “-P1D”. See the section below about Requested versus actual time granularity and range.
     from string True The start time of the time interval.
     to string True The end time of the time interval.

Query Parameters

None

Response

The JSON in the body of the response can contain the following parameters.

HTTP/1.1 200 OK

Name Type Description
requestDurationInMillis number Time taken to generate the response in milliseconds. Returned by an event summary or an event details query.
result array The results of the query. Returned by an event summary or an event details query.
     aggregatedValues object This object holds the aggregated events. Returned by an event summary query.
          timeFrameAggregated object array The count of events per time frame and time granularity. In each time frame, the count is also aggregated by group. Returned with aggregatedValues.
                    timeFrameValues array An array of aggregationGroupCount objects, each one representing a group. Returned with timeFrameAggregated.
                              aggregationGroup object Object containing fields and values for the counted group, for example {“field1”: “value1”, “field2”: “value2, …}. Returned with timeFrameValues.
                              count number The total number of events for the entire time frame of the query for the aggregationGroup group. Returned with timeFrameValues.
                    timeMillis number Indicates the time this time frame is referencing. Returned with timeFrameAggregated.
          total array A list of the total number of events for the entire time frame and for each aggregationGroup group. Returned with aggregatedValues.
                    aggregationGroup object Object containing fields and values for the counted group, for example {“field1”: “value1”, “field2”: “value2, …}. Returned with total.
                    count number The total number of events for the entire time frame of the query for the aggregationGroup group. Returned with total.
     events array All the event fields related to the event. Each type of event can have different fields. Returned by an event details query.
          category string Events can belong to a category, such as “system”, “security” or “network”. Returned with events.
          description string A description of the event. Returned with events.
          logLevel string The log level of the event, for example, “error”. Returned with events.
          title string A short descriptive title for the event. Returned with events.
          type string tells the type of event, for example scaled out failed. Returned with events.
     timeGranularity object This is the actual time granularity and it applies to all the data points mentioned in aggregatedValues. Can be returned by query for an event summary. The result can have a different time granularity from that requested. See the section below about Requested versus actual time granularity and range.
          duration number Duration of the time interval in units specified by unit. Returned with timeGranularity.
          unit string Possible values: “SECONDS”, “MINUTES”, “HOURS” or “DAYS”. Returned with timeGranularity.
     timeRange object Specifies the start and end times for the query. Formatted as epoch time, for example, the interval can be formatted as “from”: “1437584763000000” and “to”: “1437584773000000”. The time range can also be specified relative to current time. For example, a time interval of between 12 hours ago and now can be formatted as “from”: “-P12H”, “to”: “now”. A time interval of between 2 days ago and yesterday can be formatted as: “from”: “-P2D”, “to”: “-P1D”. See the section below about Requested versus actual time granularity and range.
          from string The start time of the time interval. Returned with timeRange.
          to string The end time of the time interval. Returned with timeRange.
     totalHits number Number of events in the time frame that matched the filters. This can be more than the number of events mentioned in the response because of the limit clause. Returned by an event details query.

Permissions

Role Allow
admin Yes

Filters

The basic filters are Binary Predicate, In Predicate and Match Filter. A filter can be specified using the type, field and value fields.

Name type field value
Binary Predicate Specifies the logical operator as one of: “eq”, “neq”, “lt”, “gt”, “lte” or “gte”. The event field to be compared to value. The string, number or boolean value to be compared to events.
In Predicate Use “in” to determine if an event contains any of the values specified in value. The event field to be compared to values. The array of string, number or boolean value to be compared to events.
Match Filter Use “match-phrase-prefix” to match events with the prefix specified in value. Use “like” to match events with the word specified in value, it does not need to be a prefix. The event field to be compared to value. Required if type is “like”. Optional if type is “match-phrase-prefix”. If `field is absent, this matches any event. The prefix or word to match.

You can combine the basic filters into complex logical filters using “and” and “or” and taking basic filters for arguments. For example, the following example combines basic Binary Predicate and In Predicate filters to make a complex filter.

{
    "filter": {
            "type": "and",
            "args": [{
                            "type": "or",
                            "args": [{
                                            "type": "eq",
                                            "field": "url",
                                            "value": "http://domain1.com"
                                    },
                                    {
                                            "type": "eq",
                                            "field": "rc",
                                            "value": "200"
                                    }
                            ]
                    },
                    {
                            "type": "and",
                            "args": [{
                                            "type": "in",
                                            "field": "url",
                                            "values": [
                                                    "http://domain1.com",
                                                    "http://domain2.com"
                                            ]
                                    },
                                    {
                                            "type": "neq",
                                            "field": "rc",
                                            "value": "200"
                                    }
                            ]
                    }
            ]
    }
}

Requested versus actual time granularity and range

The time granularity of the result can be different than requested because the actual time interval depends upon the largest interval available over the total requested time range. Data is collected at 30 second intervals and after 10 hours this data is aggregated into a 1 hour resolution. This means if your requested time range is less than 1 hour, and your requested time granularity is less than 30 seconds, the actual interval in the response will be for 30 second intervals. If your requested range is between 30 seconds and 1 hour, the actual interval in the result will be rounded down to the closest multiple of 30 seconds. If your requested interval is greater than 1 hour, the actual interval of the result will be rounded down to the number of hours closest to the requested time granularity.

Similarly, the actual time range of the result can be different than requested by the values of to and from provided in the request. The actual time range is always 30 seconds or larger. If your requested range is between 30 seconds and 1 hour, the actual range in the result will be rounded up to the closest multiple of 30 seconds. If your requested time range is greater than 1 hour, the actual range of the result will be rounded up to the number of hours closest to the requested time range.

Examples

POST to query for event summary

A query for an event summary returns a count of events for the total and a series of data points in time. This type of query is identified by a kind value of “ap:query:event:eventSummary”.

In the following example the placeholder {tenant-id} represents the ID of a particular tenant if there are multiple tenants. At first versions before there is multi-tenant support, this value will be “default”

POST https://192.0.2.242/mgmt/ap/query/v1/tenants/{tenant-id}/event-query

The JSON in the body of the POST can look similar to the following example.

{
    "kind": "ap:query:event:eventSummary",
    "isListDisplay": false,
    "timeRange": {
            "from": 1558024167842,
            "to": 1558027767842
    },
    "timeGranularity": {
            "duration": 36,
            "unit": "SECONDS"
    },
    "aggregationGroups": [
            "category"
    ],
    "isStatisticsBounded": true,
    "filter": {
            "type": "and",
            "args": [{
                            "type": "or",
                            "args": [{
                                            "type": "eq",
                                            "field": "category",
                                            "value": "security"
                                    },
                                    {
                                            "type": "eq",
                                            "field": "category",
                                            "value": "traffic"
                                    }
                            ]
                    },
                    {
                            "type": "or",
                            "args": [{
                                            "type": "eq",
                                            "field": "logLevel",
                                            "value": "critical"
                                    },
                                    {
                                            "type": "eq",
                                            "field": "logLevel",
                                            "value": "cleared"
                                    }
                            ]
                    }
            ]
    }
}

Response

The JSON in the body of the response can look similar to the following.

{
    "result": {
            "timeRange": {
                    "from": "1558024140000",
                    "to": "1558027710000",
                    "timezone": "Asia/Tel_Aviv",
                    "durationInSec": 3570,
                    "durationInMillis": 3570000
            },
            "timeGranularity": {
                    "duration": 60,
                    "unit": "SECONDS"
            },
            "aggregatedValues": {
                    "total": [{
                            "aggregationGroup": {
                                    "category": "system"
                            },
                            "count": 2
                    }],
                    "timeFrameAggregated": [{
                                    "timeMillis": 1558024200000,
                                    "timeFrameValues": [],
                                    "allIncludedTimeRange": {
                                            "from": "1558024140000",
                                            "to": "1558024200000",
                                            "durationInSec": 60,
                                            "durationInMillis": 60000
                                    }
                            },
                            {
                                    "timeMillis": 1558024260000,
                                    "timeFrameValues": [],
                                    "allIncludedTimeRange": {
                                            "from": "1558024200000",
                                            "to": "1558024260000",
                                            "durationInSec": 60,
                                            "durationInMillis": 60000
                                    }
                            },
                            {
                                    "timeMillis": 1558027710000,
                                    "timeFrameValues": [],
                                    "allIncludedTimeRange": {
                                            "from": "1558027680000",
                                            "to": "1558027710000",
                                            "durationInSec": 30,
                                            "durationInMillis": 30000
                                    }
                            }
                    ]
            }
    },
    "requestDurationInMillis": 8
}

POST to query for event details

A query for event details returns an object that has all the fields which are related to an event. Some of the fields returned depend upon the type of event. All events return the following fields: type, category, logLevel, title and description. This type of query is identified by the kind value of “ap:query:event:eventDetails”.

In the following example the placeholder {tenant-id} represents the ID of a particular tenant if there are multiple tenants. At first versions before there is multi-tenant support, this value will be “default”

POST https://192.0.2.242/mgmt/ap/query/v1/tenants/{tenant-id}/event-query

The JSON in the body of the POST can look similar to the following example.

{
    "kind": "ap:query:event:eventDetails",
    "showAllFields": true,
    "timeRange": {
            "from": 1558119600000,
            "to": 1558123200000
    },
    "limit": 50,
    "skip": 0,
    "isStatisticsBounded": true,
    "filter": {
            "type": "and",
            "args": [{
                            "type": "or",
                            "args": [{
                                    "type": "eq",
                                    "field": "category",
                                    "value": "system"
                            }]
                    },
                    {
                            "type": "or",
                            "args": [{
                                            "type": "eq",
                                            "field": "logLevel",
                                            "value": "critical"
                                    },
                                    {
                                            "type": "eq",
                                            "field": "logLevel",
                                            "value": "error"
                                    },
                                    {
                                            "type": "eq",
                                            "field": "logLevel",
                                            "value": "warning"
                                    },
                                    {
                                            "type": "eq",
                                            "field": "logLevel",
                                            "value": "cleared"
                                    }
                            ]
                    }
            ]
    }
}

Response

The response to the POST can look similar to the following.

{
    "result": {
            "timeRange": {
                    "from": "1558119600000",
                    "to": "1558123200000",
                    "timezone": "Asia/Tel_Aviv",
                    "durationInSec": 3600,
                    "durationInMillis": 3600000
            },
            "events": [{
                            "publish": "true",
                            "tenantId": "default",
                            "sourceId": "bigiq_internal",
                            "type": "scale-out-failed",
                            "category": "system",
                            "subCategory": "ssg-scale-out",
                            "logLevel": "error",
                            "module": "bigiq-ssg",
                            "description": "Failed scale-out on SSG exampleSSG",
                            "title": "Failed scale-out",
                            "correlationId": "",
                            "startTime": 1558121591000,
                            "timestamp": 1558123131000,
                            "severity": "Critical",
                            "severityLevel": 2,
                            "reportedObjectType": "constantstring:Service Scaling Group",
                            "reportedObject": "exampleSSG",
                            "producerType": "ssg",
                            "alertContext": "scaling",
                            "timeWindow": {
                                    "timeInterval": 0,
                                    "end": 1558123131000
                            },
                            "dimensions": {
                                    "workflow": "scale-out",
                                    "ssg": "exampleSSG"
                            },
                            "properties": {
                                    "delta": "1.0"
                            }
                    },
                    {
                            "publish": "true",
                            "tenantId": "default",
                            "sourceId": "bigiq_internal",
                            "type": "scale-out-failed",
                            "category": "system",
                            "subCategory": "ssg-scale-out",
                            "logLevel": "error",
                            "module": "bigiq-ssg",
                            "description": "Failed scale-out on SSG exampleSSG",
                            "title": "Failed scale-out",
                            "correlationId": "",
                            "startTime": 1558119911000,
                            "timestamp": 1558121441000,
                            "severity": "Critical",
                            "severityLevel": 2,
                            "reportedObjectType": "constantstring:Service Scaling Group",
                            "reportedObject": "exampleSSG",
                            "producerType": "ssg",
                            "alertContext": "scaling",
                            "timeWindow": {
                                    "timeInterval": 0,
                                    "end": 1558121441000
                            },
                            "dimensions": {
                                    "workflow": "scale-out",
                                    "ssg": "exampleSSG"
                            },
                            "properties": {
                                    "delta": "1.0"
                            }
                    },
                    {
                            "publish": "true",
                            "tenantId": "default",
                            "sourceId": "bigiq_internal",
                            "type": "scale-out-failed",
                            "category": "system",
                            "subCategory": "ssg-scale-out",
                            "logLevel": "error",
                            "module": "bigiq-ssg",
                            "description": "Failed scale-out on SSG exampleSSG",
                            "title": "Failed scale-out",
                            "correlationId": "",
                            "startTime": 1558118231000,
                            "timestamp": 1558119761000,
                            "severity": "Critical",
                            "severityLevel": 2,
                            "reportedObjectType": "constantstring:Service Scaling Group",
                            "reportedObject": "exampleSSG",
                            "producerType": "ssg",
                            "alertContext": "scaling",
                            "timeWindow": {
                                    "timeInterval": 0,
                                    "end": 1558119761000
                            },
                            "dimensions": {
                                    "workflow": "scale-out",
                                    "ssg": "exampleSSG"
                            },
                            "properties": {
                                    "delta": "1.0"
                            }
                    }
            ],
            "totalHits": 3
    },
    "requestDurationInMillis": 10
}