Skip to main content

Event fields resources

Use the event fields resources of the dictionary service to override the default dictionary entries with your own definitions, create new entries for event fields that are not included in the default dictionary, and manage custom entries.

Resource list

Authentication

All Virtana Service Observability API endpoints require HTTPS, expect JSON in the request body when a body is required, and return a JSON response. You must have an authentication key to send requests to a Virtana Service Observability API endpoint. The key is sent in the zenoss-api-key header of each request.

All of the following API examples use curl to send a JSON request from a Bash shell to an endpoint. All examples use YOUR-API-ENDPOINT and YOUR-API-KEY as placeholders for endpoints and authentication keys.

Create an event field entry

POST /v1/dictionary/event_fields

You can create a custom event field entry. If the default dictionary includes an entry for the event field name specified in a create request, the custom entry becomes the effective entry. Subsequently, if the custom entry is deleted, the default entry becomes the effective entry.

Request template

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

{
  "name": "<name>",
  "label": "<label>",
  "description": "<description>",
  "tags": [ "<tag>" ]
}

Request fields

Field

Type

Required

Description

name

String

Yes

The event field name.

label

String

No

A short name for an event field.

description

String

No

A longer, free-form statement about an event field.

tags

Array

No

A list of arbitrary terms to associate with an event field. The tags namespace is shared among all dictionary types. By convention, this field is used to record the source of an entry.

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

400

Bad request. The request body is missing, malformed, or contains invalid values.

409

Conflict. The request conflicts with the current state of the resource. A custom entry by the same name already exists.

Example

Request example

 curl https://YOUR-API-ENDPOINT/v1/dictionary/event_fields \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s \
  -d '{
  "name": "psblusmk",
  "label": "Power Supply Blue Smoke",
  "description": "The power supply has released its last gasp of blue smoke.",
  "tags": [
    "hardware",
    "failure"
  ]
}'

Response example

 {
  "name": "psblusmk",
  "label": "Power Supply Blue Smoke",
  "description": "The power supply has released its last gasp of blue smoke.",
  "tags": [
    "hardware",
    "failure"
  ],
  "layer": "TENANT",
  "default": null
}

Get one event field entry

GET /v1/dictionary/event_fields/{name}

Response fields

Field

Description

layer

DEFAULT for Virtana-defined entries or TENANT for entries defined by a user in your organization.

default

null for Virtana-defined entries or an object containing the default value of a Virtana-defined entry that has been overridden by a user in your organization.

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

404

Not found. The specified resource does not exist.

Examples

View the following examples for different types of requests and responses.

Default entry

Request example

 curl https://YOUR-API-ENDPOINT/v1/dictionary/event_fields/CZ_EVENT_DETAIL-zenoss.device.groups \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET -s

Response example

 {
  "name": "CZ_EVENT_DETAIL-zenoss.device.groups",
  "label": "Device Groups",
  "description": "Device groups of the event's device.",
  "tags": [
    "cz"
  ],
  "layer": "DEFAULT",
  "default": null
}

Overridden entry

Request example

 curl https://YOUR-API-ENDPOINT/v1/dictionary/event_fields/CZ_EVENT_DETAIL-zenoss.device.groups \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET -s

Response example

 {
  "name": "CZ_EVENT_DETAIL-zenoss.device.groups",
  "label": "CZ Device Groups",
  "description": "Device groups of the event's device.",
  "tags": [
    "cz"
  ],
  "layer": "TENANT",
  "default": {
    "name": "CZ_EVENT_DETAIL-zenoss.device.groups",
    "label": "Device Groups",
    "description": "Device groups of the event's device.",
    "tags": [
      "cz"
    ],
    "layer": "DEFAULT",
    "default": null
  }
}

Custom entry

Request example

 curl https://YOUR-API-ENDPOINT/v1/dictionary/event_fields/psblusmk \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET -s

Response example

 {
  "name": "psblusmk",
  "label": "Power Supply Blue Smoke",
  "description": "The power supply has released its last gasp of blue smoke.",
  "tags": [
    "hardware",
    "failure"
  ],
  "layer": "TENANT",
  "default": null
}

Get all event field entries

GET /v1/dictionary/event_fields

Get all event field entries. This includes all default entries, all overridden entries, and all custom entries.

Response fields

Field

Description

layer

DEFAULT for Virtana-defined entries or TENANT for entries defined by a user in your organization.

default

null for Virtana-defined entries or an object containing the default value of a Virtana-defined entry that has been overridden by a user in your organization.

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

Example

Request example

 curl https://YOUR-API-ENDPOINT/v1/dictionary/event_fields \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET -s

Response example (truncated)

 {
  "eventFields": [
    {
      "name": "CZ_EVENT_DETAIL-capacity.breach",
      "label": "Capacity Breach Type",
      "description": "The type of capacity breach being reported by the event.\n\nPossible values include current or projected. Current indicates that the defined capacity threshold is currently breached, and projected indicates that it is projected to be breached. When the type is projected you can use the Capacity Breach Timestamp, Capacity Breach At, or Capacity Breach In fields to know when breach is projected to occur.",
      "tags": [
        "cz",
        "capacity"
      ],
      "layer": "DEFAULT",
      "default": null
    },
    {
      "name": "CZ_EVENT_DETAIL-capacity.breach_at",
      "label": "Capacity Breach At",
      "description": "Formatted timestamp for when the capacity threshold is projected to be breached.",
      "tags": [
        "cz",
        "capacity"
      ],
      "layer": "DEFAULT",
      "default": null
    },
    .
    .
    .
  ],
  "nextPageToken": "",
  "totalCount": "68"
}

Update a custom event field entry

PATCH /v1/dictionary/event_fields/{name}

Update an existing custom event field entry.

To override a default entry, create a new custom entry.

Request fields

Update requests use the same fields as create requests. The name field is required but cannot be changed.

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

404

Not found. The specified resource does not exist.

Example

Request example

 curl https://YOUR-API-ENDPOINT/v1/dictionary/event_fields/psblusmk \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X PATCH -s -d '{
  "name": "psblusmk",
  "description": "The power supply has released its last gasp of blue smoke. RIP good buddy."
}'

Response example

 {
  "name": "psblusmk",
  "label": "Power Supply Blue Smoke",
  "description": "The power supply has released its last gasp of blue smoke. RIP good buddy.",
  "tags": [
    "hardware",
    "failure"
  ],
  "layer": "TENANT",
  "default": null
}

Delete a custom event field entry

DELETE /v1/dictionary/event_fields/{name}

If a default entry exists for the specified name, the default entry becomes the effective entry.

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

404

Not found. The specified resource does not exist.

Example

Request example

 curl https://YOUR-API-ENDPOINT/v1/dictionary/event_fields/psblusmk \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X DELETE -s

Response example

 {}
In this section: