Data receiver service

The resources of the data receiver service enable sending entities, metric data points, and events directly to Virtana Service Observability. 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

Field	Type	Required	Description
`detailedResponse`	Boolean	No	Provide specific feedback when parsing fails (`true`) or no specific feedback (`false`). Default is `false`.
`models`	Array	Yes	An array of one or more entity objects.
`models.timestamp`	Number	Yes	The date and time for the entity, specified as milliseconds since the epoch (January 1, 1970 at 00:00:00 UTC). Virtana Service Observability rejects requests with `models.timestamp` values that are more than 24 hours old.
`models.dimensions`	Object	Yes	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.
`models.metadataFields`	Object	Yes	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

Code	Description
200	Success. See response message.
401	Unauthorized. Missing or invalid authentication key.

Example

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

Response example

 {
  "succeeded": 1
}

Deleting an entity

To delete an entity, send a request with the following key-value pair in the models.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

Field	Type	Required	Description
`detailedResponse`	Boolean	No	Provide specific feedback when parsing fails (`true`) or no specific feedback (`false`). Default = `false`.
`metrics`	Array	Yes	An array of one or more metric data point objects.
`metrics.timestamp`	Number	Yes	The date and time for the metric, specified as milliseconds since the epoch (January 1, 1970 at 00:00:00 UTC). Virtana Service Observability rejects requests with `@lp(metrics.timestamp)` values that are more than 24 hours old.
`metrics.metric`	String	Yes	The name of the metric.
`metrics.value`	Number	Yes	The measurement record for the metric.
`metrics.dimensions`	Object	Yes	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.
`metrics.metadataFields`	Object	No	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

Code	Description
200	Success. The request was processed. Check the response body for per-item results when processing multiple objects.
401	Unauthorized. The API key is missing or invalid.

Example

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

Response example

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

Field	Type	Required	Description
`detailedResponse`	Boolean	No	Provide specific feedback when parsing fails (`true`) or no specific feedback (`false`). Default = `false`.
`events`	Array	Yes	An array of one of more event objects.
`events.timestamp`	String	Yes	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 `events.timestamp` values that are more than 24 hours old.
`events.name`	String	Yes	The name of the event. The value of this field and the key-value pairs of the `events.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 `events.type` field is commonly used.
`events.dimensions`	Object	Yes	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 `models.dimension` field. The pairs may be arranged in any order. The `name` key can not be included in this object.
`events.severity`	String	No	The event severity. Default = `SEVERITY_DEFAULT`. `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
`events.status`	String	No	The event status. Default = `STATUS_DEFAULT`. `STATUS_DEFAULT` - Unknown `STATUS_OPEN` - Known to be in progress `STATUS_SUPPRESSED` - Most likely ended `STATUS_CLOSED` - Known to be ended
`events.type`	String	No	A context-free label that classifies the event. For systems that employ event IDs, the same value as the `events.name` field, typically.
`events.summary`	String	No	A brief description of the event. The maximum size is 128 characters.
`events.body`	String	No	A longer description of the event.
`events.acknowledged`	Boolean	No	The acknowledgement state of the event, acknowledged (`true`) or not acknowledged (`false`). Default = `false`.
`events.metadataFields`	Object	No	One or more key-value pairs of additional information about the event.

Status codes

Code	Description
200	Success. The request was processed. Check the response body for per-item results when processing multiple objects.
401	Unauthorized. The API key is missing or invalid.

Example

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

Response example

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

In this section:

Data receiver service

Resource list

POST /v1/data-receiver/models

Request template

Request fields

Status codes

Example

Deleting an entity

POST /v1/data-receiver/metrics

Request template

Request fields

Status codes

Example

POST /v1/data-receiver/events

Request template

Request fields

Status codes

Example

Search results