View Events (API)

Learn about events, the event types, and how events are reported.


This documentation applies to NGINX Management Suite Instance Manager 2.1.0 and later.


Overview

Use the Events API to view events for Instance Manager. Currently, the reported events include statuses for the NGINX Agent and attempted NGINX configuration updates.

Query the Events API for all Events

To query the Events API, send a GET request similar to the following example to the Events endpoint:

curl -u {USERNAME:PASSWORD} -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/analytics/events

Example Response

{
	"Metadata": {
		"pagination": {
			"links": {
				"next": {},
				"prev": {}
			},
			"pageToken": "1639453182"
		}
	},
	"items": [{
		"category": "agent status",
		"dimensions": {
			"alias": "alias",
			"hostname": "hostname",
			"instance": "instance",
			"nginx_id": "nginx_id",
			"system_id": "system_id",
		},
		"id": "uuid",
		"level": "INFO",
		"message": "successfully applied config on <instance>",
		"status": "Config Apply Success",
		"timestamp": "2021-12-14T01:03:11Z"
	}, {
		"category": "agent status",
		"dimensions": {
			"alias": "alias",
			"hostname": "hostname",
			"instance": "instance",
			"nginx_id": "nginx_id",
			"system_id": "system_id",
		},
		"error": "Config apply failed (write): Error running nginx -t exit status 1",
		"id": "uuid",
		"level": "INFO",
		"message": "failed to apply nginx config on <instance>",
		"status": "Config Apply Failure",
		"timestamp": "2021-12-14T00:57:48Z"
	},{
		"category": "agent status",
		"dimensions": {
			"alias": "alias",
			"hostname": "hostname",
			"instance": "instance",
			"nginx_id": "nginx_id",
			"system_id": "system_id"
		},
		"id": "uuid",
		"level": "INFO",
		"message": "nginx-agent v2.1.6 stopped on <instance>",
		"status": "Agent Stop",
		"timestamp": "2021-12-13T20:08:49Z"
	}, {
		"category": "agent status",
		"dimensions": {
			"alias": "alias",
			"hostname": "hostname",
			"instance": "instance",
			"nginx_id": "nginx_id",
			"system_id": "system_id",
		},
		"id": "uuid",
		"level": "INFO",
		"message": "nginx-agent v2.1.6 started on <instance>",
		"status": "Agent Start",
		"timestamp": "2021-12-13T03:20:00Z"
	}]
}

Filter Events with Query Parameters

The list of events can be filtered by passing different query parameters to the API request. The type of filtering depends on the chosen query parameters. This section introduces the list of available query parameters.

Note that query parameters are only intended for filtering an events collection, not for querying a single event resource.

Time interval

Events can be queried with an exclusive time interval by passing either a startTime or both a startTime and an endTime.

Start Time

Passing a startTime query parameter to an Events API request will return only the events that occurred after the provided timestamp:

curl -u {USERNAME:PASSWORD} -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/analytics/events?startTime=2022-03-19T08:00:00.000000000Z"

The startTime parameter can use the keyword now to signify the timestamp at the time of the request.

Timestamps relative to now can be passed by substracting a period of time from the current time, for example now-3h or now-30m

For example:

curl -u {USERNAME:PASSWORD} -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/analytics/events?startTime=now-3h"

Alternatively, the UUID of an event can be passed as a startTime. In this case, the events that occurred after the given event will be returned:

curl -u {USERNAME:PASSWORD} -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/analytics/events?startTime=c77b71b5-3afa-497a-8e1c-fdc11d676796"

End Time

The endTime query parameter cannot be passed without a startTime. Together they form an exclusive time interval, where the startTime is inclusive and endTime is non-inclusive. It can be formatted in the same three ways as startTime.

curl -u {USERNAME:PASSWORD} -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/analytics/events?startTime=2022-03-19T08:00:00Z&endTime=2022-03-19T12:00:00Z"

Filtering

The filter parameter enables filtering events based on predicates. Predicates are in the form:

<dimension><operator><dimension value>

Where a <dimension> is one of the event’s dimensions <operator> is one of =, !=, >=, <=, <, >, in, not <dimension> and <dimension value> are both case sensitive.

Predicates can be combined into logical expressions using OR, AND, ( and ). Wilcards (*) are supported for matching values.

curl -u {USERNAME:PASSWORD} -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/analytics/events?filter=category IN ('agent','nms') AND level='debug' AND count > 100"

Sorting

Events can be sorted based on any of their dimensions with the orderBy query parameter.

orderBy dimensions are separated by commas and can optionally given an order.

curl -u {USERNAME:PASSWORD} -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/analytics/events?orderBy=timestamp DESC,id"

The order of the dimensions can be either ascending (ASC) or descending (DESC). By default, that is when the order is omitted, dimensions are sorted in ascending order.

In the above example, events are sorted in descending timestamp order first, and second in ascending ID order (in cases where timestamps are equal).

Pagination

There are several query parameters related to pagination in the API. By default, pagination is enabled with one hundred events returned per page.

Page

The page query parameter returns the events for the given page number. By default the first page is returned.

curl -u {USERNAME:PASSWORD} -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/analytics/events?page=3"

Page Size

pageSize determines how many events are returned per page, up to a maximum of 100. Setting pageSize to zero disables pagination.

curl -u {USERNAME:PASSWORD} -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/analytics/events?pageSize=3"

Page Token

pageToken is a transactional token that ensures consistency of queries across requests. Responses to queries made with the same pageToken will always be the same. The response is a snapshot of the database contents at the time of the original request when the pageToken was first used.

If pageToken is omitted, a token is automatically generated and returned in the response’s metadata. Subsequent requests can then use that token to ensure consistency.

curl -u {USERNAME:PASSWORD} -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/analytics/events?pageToken=1573653786"

Aggregations

Count

Passing the includeTotal query parameter with a value of true will return the total number of events of the response. The count of events will be in the response’s metadata.

curl -u {USERNAME:PASSWORD} -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/analytics/events?includeTotal=true"

Query a Single Event

Querying for a unique event requires only the event’s UUID.

curl -u {USERNAME:PASSWORD} -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/analytics/events/7cb91de6-49ae-4ddc-a8b3-3255e00b9346"

Example response:

{
    "category": "agent status",
    "dimensions": {
        "alias": "devenv-agent",
        "hostname": "devenv-agent",
        "instance": "3d54a8fe-7c90-374f-9cad-fa2b8fccb0cd",
        "nginx_id": "3d54a8fe-7c90-374f-9cad-fa2b8fccb0cd",
        "system_id": "3d54a8fe-7c90-374f-9cad-fa2b8fccb0cd"
    },
    "id": "7cb91de6-49ae-4ddc-a8b3-3255e00b9346",
    "level": "INFO",
    "message": "nginx-agent v2.11.0 started on devenv-agent",
    "status": "Agent Start",
    "timestamp": "2022-03-21T14:33:37Z"
}