Data receiver service

The resources of the data receiver service enable sending entities, metric data points, and events directly to Zenoss Cloud. The data receiver service also supports gRPC methods.

Resource list

• Create or update entities (POST /v1/data-receiver/models)
• Create metric data points (POST /v1/data-receiver/metrics)
• Create new events (POST /v1/data-receiver/events)

POST /v1/data-receiver/models

Create or update one or more entities. (The gRPC method name is PutModels.)

An update can delete an entity.

Request template

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

{
  "detailedResponse": <boolean>,
  "models": [
    {
      "timestamp": <ms-since-epoch>,
      "dimensions": {
        "<key>": "<value>",
        "<key>": "<value>"
      },
      "metadataFields": {
        "<key>": "<value>",
        "<key>": "<value>"
      }
    }
  ]
}

Request fields

detailedResponse (boolean, optional, default = false)

Provide specific feedback when parsing fails (true) or no specific feedback (false).

models (array, required)

An array of one or more entity objects.

timestamp (number, required)

The date and time for the entity, specified as milliseconds since the epoch (January 1, 1970 at 00:00:00 UTC). Zenoss Cloud rejects requests with timestamp values that are more than 24 hours old.

dimensions (object, required)

One or more key-value pairs that uniquely identify the entity.

Some reserved key-value pairs are either required or commonly used in this field. See Dimension attributes. The name key may not be included in this object.

metadataFields (object, required)

One or more key-value pairs of additional information about the entity.

Some reserved key-value pairs are either required or commonly used in this field. See Metadata attributes. The name key may be included in this object.

Status codes

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

Example

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/data-receiver/models \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -S -d \
'{
  "detailedResponse": true,
  "models": [
    {
      "timestamp": 1600799308000,
      "dimensions": {
        "source": "my.simple.app",
        "source-type": "com.example.simple"
      },
      "metadataFields": {
        "name": "My.Simple.App"
      }
    }
  ]
}'

{
  "succeeded": 1
}

Deleting an entity

To delete an entity, send a request with the following key-value pair in the metadataFields object:

"_zen_deleted_entity": true

POST /v1/data-receiver/metrics

Create one or more metric data points. (The gRPC method name is PutMetrics.)

Request template

An abstract preview of a JSON request to create one metric data point.

{
  "detailedResponse": <boolean>,
  "metrics": [
    {
      "timestamp": <ms-since-epoch>,
      "metric": "<metric-name>",
      "value": <data-point>,
      "dimensions": {
        "<key>": "<value>",
        "<key>": "<value>"
      }
    }
  ]
}

Request fields

detailedResponse (boolean, optional, default = false)

Provide specific feedback when parsing fails (true) or no specific feedback (false).

metrics (array, required)

An array of one or more metric data point objects.

timestamp (number, required)

The date and time for the metric, specified as milliseconds since the epoch (January 1, 1970 at 00:00:00 UTC). Zenoss Cloud rejects requests with timestamp values that are more than 24 hours old.

metric (string, required)

The name of the metric.

value (number, required)

The measurement record for the metric.

dimensions (object, required)

One or more key-value pairs that uniquely identify the entity associated with the metric.
The contents of this object must match the key-value pairs of one entity's dimensions field.

Some reserved key-value pairs are either required or commonly used in this field. See Dimension attributes. The name key may not be included in this object.

metadataFields (object, optional)

One or more key-value pairs of additional information about the metric.

Some reserved key-value pairs are either required or commonly used in this field. See Metadata attributes. The name key may not be included in this object.

Status codes

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

Example

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/data-receiver/metrics \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -S -d \
'{
  "detailedResponse": true,
  "metrics": [
    {
      "timestamp": 1600807394000,
      "metric": "my.metric",
      "value": 1349.3,
      "dimensions": {
        "source": "my.simple.app",
        "source-type": "com.example.simple"
      }
    },
    {
      "timestamp": 1600807647000,
      "metric": "my.metric",
      "value": 1481.7,
      "dimensions": {
        "source": "my.simple.app",
        "source-type": "com.example.simple"
      }
    }
  ]
}'

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

POST /v1/data-receiver/events

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>"
      }
    }
  ]
}

Request fields

detailedResponse (boolean, optional, default = false)

Provide specific feedback when parsing fails (true) or no specific feedback (false).

events (array, required)

An array of one of 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). Zenoss Cloud 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.

For systems that employ event IDs, the value of this field should be the ID. Otherwise, the same value as the type field is commonly used.

dimensions (object, required)

One or more key-value pair 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.

Status codes

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

Example

RequestResponse

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"
      }
    }
  ]
}'

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