Skip to content

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

POST /v1/data-receiver/models

Creates or updates one or more entities. (The gRPC method name is PutModels.)

An update can delete an entity.

Fields

Field Required? Type Description
detailedResponse No Boolean Provide specific feedback when parsing fails (true) or no specific feedback (false). The default is false.
models Yes Array

One or more entity specifications.

The remaining fields of this table specify an entity.

timestamp Yes Number

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 Yes Object

One or more key-value pairs that uniquely identify the entity. The values must be strings and the pairs may be arranged in any order.

Some reserved key-value pairs are either required or commonly used in this field. See Dimension attributes.

metadataFields Yes Object

One or more key-value pairs containing additional information about the entity. The pairs may be arranged in any order.

Some reserved key-value pairs are either required or commonly used in this field. See Metadata attributes.

Status codes

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

Example

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

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

Fields

Field Required? Type Description
detailedResponse No Boolean Provide specific feedback when parsing fails (true) or no specific feedback (false). The default is false.
metrics Yes Array

One or more metric data point specifications.

The remaining fields of this table specify a data point.

timestamp Yes Number

The date and time for the data point, specified as milliseconds since the epoch (January 1, 1970 at 00:00:00 UTC).

Zenoss Cloud does not accept requests with timestamp values that are more than 24 hours old.

metric Yes String The name of the metric.
value Yes Number The numeric value to record for the metric.
dimensions Yes Object

The key-value pair or 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 dimension field. The pairs may be arranged in any order.

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

Status codes

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

Example

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

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

Fields

Field Required? Type Description
detailedResponse No Boolean Provide specific feedback when parsing fails (true) or no specific feedback (false). The default is false.
events Yes Array

One or more event specifications.

The remaining fields of this table specify an event.

timestamp Yes Number

The date and time for the event, specified as milliseconds since the epoch (January 1, 1970 at 00:00:00 UTC).

Zenoss Cloud does not accept requests with timestamp values that are more than 24 hours old.

name Yes String

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 Yes Object

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

severity No String

The event severity, one of the following values:

SEVERITY_DEFAULT
Unknown at this time
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

When this field is not specified, the value is SEVERITY_DEFAULT.

status No String

The event status, one of the following:

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

When this field is not specified, the value is STATUS_DEFAULT.

type No String A context-free label that classifies the event. For systems that employ event IDs, the same value as the name field, typically.
summary No String A brief description of the event. The maximum size is 128 characters.
body No String A longer description of the event.
acknowledged No Boolean The acknowledgement state of the event, acknowledged (true) or not acknowledged (false). The default is not acknowledged (false).
metadataFields No Object One or more key-value pairs of additional information about the event.

Status codes

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

Example

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