Events API

The following are events resources that you can access in the Virtana Service Observability API:

Create new events (POST /v1/data-receiver/events)
Annotate (POST /v1/event-management/annotate)
Set status (POST /v1/event-management/status)

Create new events (POST /v1/data-receiver/events)

Create new Event

Create one or more events. (The gRPC method name is PutEvents).

Use the Event management service to annotate events or set event status.

Request template

An abstract preview of a JSON request to create one event.

{
  "events": [
    {
      "name": "<event-name>",
      "status": "<status>",
      "severity": "<severity>",
      "summary": "<summary>",
      "timestamp": "<ms-since-epoch>",
      "dimensions": {
        "<key>": "<value>",
        "<key>": "<value>"
      },
      "metadataFields": {
        "<key>": "<value>",
        "<key>": "<value>"
      }
    }
  ]
}

Field	Type / Requirement	Description
`detailedResponse`	boolean, optional, default = false	Provide specific feedback when parsing fails (true) or no specific feedback (false).
`events`	array, required	An array of one or more event objects.
`timestamp`	string, required	The date and time for the event, specified as milliseconds since the epoch (January 1, 1970 at 00:00:00 UTC). Virtana Service Observability rejects requests with timestamp values that are more than 24 hours old.
`name`	string, required	The name of the event. The value of this field and the key-value pairs of the dimensions field are used to identify one unique event.
`dimensions`	object, required	One or more key-value pairs that uniquely identify the entity associated with the event. The contents of this object must match the key-value pairs of one entity's dimension field. The pairs may be arranged in any order. The name key may not be included in this object.
`severity`	string, optional, default = SEVERITY_DEFAULT	The event severity. `SEVERITY_DEFAULT` — Unknown `SEVERITY_DEBUG` — By default, not severe enough to display in an events console `SEVERITY_INFO` — Most likely, no action is required `SEVERITY_WARNING` — Action may be required in the future `SEVERITY_ERROR` — Entity is degraded but not down `SEVERITY_CRITICAL` — Entity is down
`status`	string, optional, default = STATUS_DEFAULT	The event status. `STATUS_DEFAULT` — Unknown `STATUS_OPEN` — Known to be in progress `STATUS_SUPPRESSED` — Most likely ended `STATUS_CLOSED` — Known to be ended
`type`	string, optional	A context-free label that classifies the event. For systems that employ event IDs, the same value as the name field, typically.
`summary`	string, optional	A brief description of the event. The maximum size is 128 characters.
`body`	string, optional	A longer description of the event.
`acknowledged`	boolean, optional, default = false	The acknowledgement state of the event, acknowledged (true) or not acknowledged (false).
`metadataFields`	object, optional	One or more key-value pairs of additional information about the event.

Request Body

curl https://YOUR-API-ENDPOINT/v1/data-receiver/events \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -S -d \
'{
  "events": [
    {
      "name": "my first event",
      "status": "STATUS_OPEN",
      "severity": "SEVERITY_CRITICAL",
      "summary": "Event created for my entity one",
      "timestamp": "1625152452000",
      "dimensions": {
        "source": "my.simple.app.one",
        "source-type": "com.example.simple"
      },
      "metadataFields": {
        "eventClass": "/App"
      }
    },
    {
      "name": "my second event",
      "status": "STATUS_OPEN",
      "severity": "SEVERITY_ERROR",
      "summary": "Event created for my entity two",
      "timestamp": "1625152467000",
      "dimensions": {
        "source": "my.simple.app.two",
        "source-type": "com.example.simple"
      },
      "metadataFields": {
        "eventClass": "/App"
      }
    }
  ]
}'

Request Body

{
  "succeeded": 2
  "message": "successfully processed 2 out of 2 events"
}

Annotate (POST /v1/event-management/annotate)

POST /v1/event-management/annotate

Create or update the annotation field of one or more events.To create an event, use the create events resource.

Important

To obtain values for the occurrenceId and annotationId fields, display the details of the event to annotate in an events console.

Request Template

Abstract previews of JSON requests to create or update one event annotation.

Create annotation

{
  "annotations": [
    {
      "eventId": "<event-id>",
      "occurrenceId": "<occurence-id>",
      "annotation": "<annotation>"
    }
  ]
}

Update annotation

{
  "annotations": [
    {
      "eventId": "<event-id>",
      "occurrenceId": "<occurence-id>",
      "annotationId": "<annotation-id>",
      "annotation": "<annotation>"
    }
  ]
}

Request fileds

Field	Type / Requirement	Description
`annotations`	array, required	One or more event annotation specifications.
`eventId`	string, required	The identifier of an event.
`occurrenceId`	string, required	The occurrence identifier of an event.
`annotationId`	string, optional	The identifier of an event annotation. For updates, this field is required.
`annotation`	string, optional	The text of an annotation. For updates, the content of this field replaces the existing content of an event annotation, if any.

Status codes

200 (full or partial success; see response message)
500 (missing or invalid authentication key)

Example

Request

curl https://YOUR-API-ENDPOINT/v1/event-management/annotate \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -S -d \
'{
  "annotations": [
    {
      "eventId": "AAAABWRDWOPER3lzOFI2tSCG49g=",
      "occurrenceId": "AAAABWRDWOPER3lzOFI2tSCG49g=:1",
      "annotation": "my sample annotation"
    },
    {
      "eventId": "AAAEDBRDWOPER3lzOFI2tSCG49g=",
      "occurrenceId": "GOLABWRDWOPER3lzOFI2tSCG49g=:16",
      "annotationId": "4cVf7RnzENAbMLXdt8Qu",
      "annotation": "my sample annotation update"
    }
  ]
}'

Response

{
  "annotationResponses": [
    {
      "eventId": "AAAABWRDWOPER3lzOFI2tSCG49g=",
      "occurrenceId": "AAAABWRDWOPER3lzOFI2tSCG49g=:1",
      "annotationId": "3BDeyX0rnToJgKvEEaPk",
      "success": true
    },
    {
      "eventId": "AAAEDBRDWOPER3lzOFI2tSCG49g=",
      "occurrenceId": "GOLABWRDWOPER3lzOFI2tSCG49g=:16",
      "success": true
    }
  ]
}

Set status (POST /v1/event-management/status)

POST /v1/event-management/status

Update the status of one or more events.

To create an event, use the create events resource.

Notice

To obtain values for the occurrenceId and annotationId fields, display the details of the event to update in an events console.

Request template

Abstract previews of JSON requests to update event status information.

Status update

{
  "statuses": [
    {
      "eventId": "<event-id>",
      "occurrenceId": "<occurence-id>",
      "statusWrapper": {
        "status": "<status>"
      }
    }
  ]
}

Set acknowledgement status

{
  "statuses": [
    {
      "eventId": "<event-id>",
      "occurrenceId": "<occurence-id>",
      "acknowledged": <boolean>
    }
  ]
}

Request fields

Field	Type / Requirement	Description
statuses	array, required	One or more event status specifications.
eventId	string, required	The identifier of an event.
occurrenceId	string, required	A container for a status string. This field or the acknowledged field must be included in a request.
acknowledged	boolean, optional, default = `false`	The acknowledgement state of the event, acknowledged (true) or not acknowledged (false). This field or the statusWrapper field must be included in a request.
statusWrapper	object, optional)	A container for a status string. This field or the acknowledged field must be included in a request.
status	string, optional	The status of the event. STATUS_DEFAULT - Unknown at this time STATUS_OPEN - Known to be in progress at this time STATUS_SUPPRESSED - Should be ended STATUS_CLOSED - Known to be ended