API URL (endpoint)

All data sent to http(s)://api.zenoss.io

Definitions

API-Key

• Must first be generated from the Cloud UI > API Clients > Generate Key
• You must save this key once it is displayed.  Zenoss does not store it.
• Key will be included with API requests and is used to:
  • Authenticate the request
  • Assign the request to a Client

curl

curl -s -S https://api.zenoss.io/v1/data-receiver/models \
-H "Content-type: application/json" \
-H "zenoss-api-key: $(cat ~/.zenoss.key)" \
-X POST \
-d @simple-model.json

• ~/.zenoss.key = text file with API-key
• simple-model.json: See Source Code

{
  "models": [
    {
      "timestamp": $(date +%s000),
      "dimensions": {
        "source": "$USER",
        "source-type": "com.zenoss.training"
      },
      "metadataFields": {
        "name": "${USER}-$(hostname-f)"
      }
    }
  ]
}

Options

• -s: silent mode
• -S: Show errors, used with -s
• -H: header
• -X: request method, specifies the request method to use when communicating with the HTTP server.
  • POST, GET, etc.
• -d: data.  JSON string
  • @filename: reads JSON from the filename specified.

dimensions

• Required for both Model and Metric data
• Dimensions define which metrics belong to which entity
  • These can be completely user-defined as you wish
• Entity dimensions are assigned in the Model
• Metric dimensions must exactly match the Model dimensions
  • Dimension fields should never change.  If they do, then referring to a different entity.

...
   "dimensions": {
    "source": "zennycorp",
    "source-host": "web-01.zennycorp.com",
    "source-type": "com.zenoss.training"
   },

Entity

• Any device, program, etc. that Metrics are associate or collected from.

HTTPie Utility

• Install with Python PIP
  • pip install http https
• Commands are http and https
• Options
  • -b: body – print only the response body. Default behavior is to print the response headers and body
  • URL: http or https are assumed by the command used.
  • Name:Value : Additional HTTP headers
• Defaults
  • GET if no request data
  • POST if there is request data < filename or `< “JSON_STRING”
  • Content-Type: “application/json”
  • : : Shortcut for localhost:

https -b api.zenoss.io/v1/data-receiver/models \
"zenoss-api-key:$(cat ~/.zenoss.key)" \
< simple-model.json

jq

• Linux CLI JSON processor, not installed by default
• jq without options formats its input
• jq -c  outputs compact version without spaces and one object per line

metadataFields

• Required Model field
• Contains “Optional” fields for storing metadata on a Model
• Should always include a “name”

{
 "models": [
  ...,
  "metadataFields": {
   "name": "web-01.zennycorp.com"
  }
 ]
}

Metric

You cannot send in metrics that are over 24 hours old!

• A Metric is a key: value pair
  • metric = Metric Name
  • value = Value of the metric

{
 "metrics: [
  {
   "metric": "resource_load_avg_5min",
   "timestamp: 1593883448000,
   "value": 4.03,
   "dimensions": {
    "source": "zennycorp",
    "source-host": "web-01.zennycorp.com",
    "source-type": "com.zenoss.training"
   }
  }
 ]
}

Metrics Fields

Name of the metric

Model

• Model defines an entity.
• One or more models may be defined in a single command.

{
 "models: [
  {
   "timestamp: 1593883448000,
   "dimensions": {
    "source": "zennycorp",
    "source-host": "web-01.zennycorp.com",
    "source-type": "com.zenoss.training"
   },
   "metadataFields": {
    "name": "web-01.zennycorp.com"
   }
  }
 ]
}

Model Fields

source

• Sources are metric groups for dashboards
• Can be thought of as an instances of the source-type.
  • Example: Zenoss Cloud Kubernetes agen uses the cluster name as the source value.
• Can be defined in either “dimension” or “metadataFields”
  • Use “metadataFields” if it is NOT required for uniqueness, i.e. to define it’s Entity.

source-type

• Optional
• Usually used to define the agent source the data is sent from
  • If the agent sending the data is Zenoss Cloud Kubernetes, you might use:
    • “source-type”: “zenoss.agent.kubernetes”
• Can be defined in either “dimension” or “metadataFields”

timestamp

• Required for both Model and Metric
• Milliseconds since Jan 1, 1970 at 00:00:00 UTC
• Linux commands
  • Current date time in seconds: date +%s
  • current date time in miliseconds: date +%s000
  • TIME_NOW_MS=$(date +%s000)
  • TIME_NOW_MS=`date +%s000`

{
 "models: [
  {
   "timestamp: 1593883448000,

Source Code

example.sh, example_new.sh

• example_new.sh: Uncomment #tee /dev/tty | \

#! /bin/bash
ZUSER="troberts"
API_key="$(cat ~/.zenoss.key)"
SOURCE=$ZUSER
SOURCE_TYPE=com.zenoss.training
HOST_NAME=$(hostname -f)
TIME_NOW_MS=$(date +%s000)
function data-receiver-api(){
   # Takes 1 argument, 'models' or 'metrics'
   local service=$1
   #tee /dev/tty | \
   curl -s -S \
      "https://api.zenoss.io/v1/data-receiver/$service" \
      -H "content-type: application/json" \
      -H "zenoss-api-key: $API_KEY" \
      -X POST \
      -d @- | jq
   echo
}
echo "Sending model for $SOURCE."
data-receiver-api models << EoT
{
 "models": [
  {
   "timestamp": $TIME_NOW_MS,
   "dimensions": {
    "source": "$SOURCE",
    "source-type": "$SOURCE_TYPE"
   },
   "metadataFields": {
    "name": "$SOURCE-$HOST_NAME"
   }
  }
 ]
}
EoT

echo "Sending metric(s) for $SOURCE."
data-receiver-api metrics << EoT
{
 "metrics": [
  {
   "metric": "random.number",
   "timestamp": $TIME_NOW_MS,
   "value": $((RANDOM & 127)),
   "dimensions": {
    "source": "$SOURCE",
    "source-type": "$SOURCE_TYPE"
   }
  }
 ]
}
EoT

metric.json

{"metrics":[{"metric": "random.number","timestamp": 1615068406000"value":17727,"dimensions":{"source":"train-tr","source-type":"com.zenoss.training"}}]}

Pretty Version

{
  "metrics": [
    {
      "metric": "random.number",
      "timestamp": 1615068406000,
      "value": 17727,
      "dimensions": {
        "source": "train-tr",
        "source-type": "com.zenoss.training"
      } 
    }
  ]
}

simple-json.model

{"models":[{"timestamp": $(date +%s000),     "dimensions": {
        "source": "$USER",
        "source-type": "com.zenoss.training"
      },
      "metadataFields": {
        "name": "${USER}-$(hostname-f)"
      }
    }
  ]
}