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

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)
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

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)
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

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

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

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