This documentation and the Cisco Observability Platform functionalities it describes are subject to change. Data saved on the platform may disappear and APIs may change without notice.

Metrics

A metric is a numeric measurement reported for a specific entity, sampled over a specific timeframe and typically with a fixed frequency. Metrics include the following information:

A numeric status at a specific time-interval such as, the CPU % used
An aggregated measurement such as, a count of events over one-minute, or a rate of events-per-minute

You can determine the metric by defining the consumption function. To define the function, you specify one or more values for the following:

granularity of the time interval; the interval is the same for each metric data point
aggregation method, such as the maximum value, sum of all values, the count of the events
mathematical expression for the data reported, such as the average of the values
set of event dimensions if the events are complex

Metric Kind

A metric kind is a template for the metric type. The metric kind helps to determine the schema that can be used to define a metric type. There is a set of defined fields that describes the metric.

The metric kind is associated with metric type. For information about kinds and type, see Glossary.

Each metric includes the following states or properties:

Properties	Description
type	a fully qualified type reference to the metric type
source	a source of this metric
timestamp	a timestamp for this metric
attributes	(optional) a list of key-value pairs must adhere to the attribute definitions in the corresponding metric type if an attribute with a given name is not defined in a metric type, it is considered typeless and its value will always be a string
tags (optional)	a list of tags

Metric Type

A metric kind is always be associated with a metric type defined in the metric.json file of the solution package. The following table describes the required parameters or keys used to define metric type:

Key	Type	Description	Examples
kind	string	Specifies the kind of the type being defined.	metric
name	string	A type name that is unique within this namespace.	system.network.packets http.server.duration http.server.active_requests NetworkPacketsOut
displayName	string	Display name of the type.
category	string	Category governs how the metric is consumed when a value is shown on the UI. There are limitations to use different categories, which is based on the `contentType`. `monotonic_legacy` can only be used if `contentType` is `sum`, all other `_legacy` can only be used if `contentType` is `distribution`.	meter_legacy counter_legacy rate_legacy monotonic_legacy", "average sum", "rate", "rate_per_sec sum_per_instrumented_entity current_per_instrumented_entity current
contentType	string	Content type of the metric.	sum distribution gauge
aggregationTemporality	string	Aggregation temporality of this metric. When `contentType` is `sum` it will be `delta` or `cumulative`. For distribution it will be `delta` and for gauge it can only be `unspecified`.	cumulative delta unspecified
isMonotonic	boolean	This value is false except when the category is `monotonic_legacy`, where it should be true.	true false
type	string	A primitive data type of the metric.	long double
unit	string	UCUM compliant unit code.	ms s min {faults}/s {errors}/min {packets} %
ingestGranularities	array	The granularities at which this metric can be ingested in seconds.	{ "uniqueItems": true, "minItems": 1, "items": { "type": "number", "description": "Granularity in seconds", "minimum": 10 }
attributeDefinitions	object	The definitions of attributes that can be used to describe a metric of this type.	"attributes": { "type": "object", "minProperties": 1, "maxProperties": 80, "propertyNames": { "pattern": "^[a-z]+[a-z0-9_.]{0,256}$" }, "additionalProperties": { "$ref": "#/definitions/attribute" } } }

Metric Object Definition

Before you add a new metric object definition to your Cisco Observability Platform Data model, ensure that you know the type of the telemetry data you plan to ingest so that you map it to the appropriate Metric type in the Cisco Observability Platform data model. You define the characteristics of each individual metric within their solution data model using the fmm:metric object.

fsoc provides the following command to help you easily add a new entity type to your solution package:

fsoc solution extend –-add-metric=<metric-name>

Replace <metric-name> with the name of the new metric you want do add to your solution data model.

Example

The following JSON file provides a metric definition used by the star spaceship example:

{
  "types": [
    {
      "namespace": {
        "name": "${manifest.name & manifest.tag}",
        "version": 1
      },
      "kind": "metric",
      "name": "speed",
      "displayName": "speed",
      "description": "Current speed in kilometers per second",
      "category": "sum",
      "contentType": "sum",
      "aggregationTemporality": "unspecified",
      "isMonotonic": false,
      "type": "double",
      "unit": "km/s",
      "ingestGranularities": [
        60
      ]
    },
    {
      "namespace": {
        "name": "${manifest.name & manifest.tag}",
        "version": 1
      },
      "kind": "metric",
      "name": "torpedos",
      "displayName": "Number of torpedos",
      "description": "Number of torpedos available",
      "category": "sum",
      "contentType": "sum",
      "aggregationTemporality": "unspecified",
      "isMonotonic": false,
      "type": "long",
      "unit": "{torpedos}",
      "ingestGranularities": [
        60
      ]
    },
    {
      "namespace": {
        "name": "${manifest.name & manifest.tag}",
        "version": 1
      },
      "kind": "metric",
      "name": "torpedos.launched",
      "displayName": "Number of torpedos launched from tube",
      "description": "Number of torpedos launched from tube",
      "category": "current",
      "contentType": "gauge",
      "aggregationTemporality": "unspecified",
      "isMonotonic": true,
      "type": "long",
      "unit": "By/min",
      "ingestGranularities": [
        60
      ]
    },
    {
      "namespace": {
        "name": "${manifest.name & manifest.tag}",
        "version": 1
      },
      "kind": "metric",
      "name": "currentOccupancy",
      "displayName": "Crew members in a room",
      "description": "Crew members in a room",
      "category": "current",
      "contentType": "gauge",
      "aggregationTemporality": "unspecified",
      "isMonotonic": false,
      "type": "long",
      "unit": "By/min",
      "ingestGranularities": [
        60
      ]
    },
    {
      "namespace": {
        "name": "${manifest.name & manifest.tag}",
        "version": 1
      },
      "kind": "metric",
      "name": "officerCount",
      "displayName": "Total number of officers in bridge",
      "description": "Total number of officers in bridge",
      "category": "current",
      "contentType": "gauge",
      "aggregationTemporality": "unspecified",
      "isMonotonic": false,
      "type": "long",
      "unit": "By/min",
      "ingestGranularities": [
        60
      ]
    },
    {
      "namespace": {
        "name": "${manifest.name & manifest.tag}",
        "version": 1
      },
      "kind": "metric",
      "name": "screensInUse",
      "displayName": "Screens Live in Bridge",
      "description": "Screens Live in Bridge",
      "category": "current",
      "contentType": "gauge",
      "aggregationTemporality": "unspecified",
      "isMonotonic": false,
      "type": "long",
      "unit": "By/min",
      "ingestGranularities": [
        60
      ]
    },
    {
      "namespace": {
        "name": "${manifest.name & manifest.tag}",
        "version": 1
      },
      "kind": "metric",
      "name": "earthDay",
      "displayName": "Duration",
      "description": "Total time from the date ship was launched in epochmillis",
      "category": "current",
      "contentType": "gauge",
      "aggregationTemporality": "unspecified",
      "isMonotonic": false,
      "type": "long",
      "unit": "By/min",
      "ingestGranularities": [
        60
      ]
    },
    {
      "namespace": {
        "name": "${manifest.name & manifest.tag}",
        "version": 1
      },
      "kind": "metric",
      "name": "antimatterLevel",
      "displayName": "antimatterLevel",
      "description": "antimatterLevel",
      "category": "current",
      "contentType": "gauge",
      "aggregationTemporality": "unspecified",
      "isMonotonic": false,
      "type": "long",
      "unit": "By/min",
      "ingestGranularities": [
        60
      ]
    },
    {
      "namespace": {
        "name": "${manifest.name & manifest.tag}",
        "version": 1
      },
      "kind": "metric",
      "name": "matterLevel",
      "displayName": "matterLevel",
      "description": "matterLevel",
      "category": "current",
      "contentType": "gauge",
      "aggregationTemporality": "unspecified",
      "isMonotonic": false,
      "type": "long",
      "unit": "By/min",
      "ingestGranularities": [
        60
      ]
    },
    {
      "namespace": {
        "name": "${manifest.name & manifest.tag}",
        "version": 1
      },
      "kind": "metric",
      "name": "shieldLevel",
      "displayName": "shieldLevel",
      "description": "shield level of a room or starship",
      "category": "current",
      "contentType": "gauge",
      "aggregationTemporality": "unspecified",
      "isMonotonic": false,
      "type": "double",
      "unit": "By/min",
      "ingestGranularities": [
        60
      ]
    }
  ]
}

After defining the JSON file, you can add this file path to objectsFile parameter under objects parameter within your solution manifest file (link to solution manifest description). In the solution manifest file, you can use the following syntax to include the metrics type under the objects parameter:

"objects" : [
      {
        "type": "fmm${manifest.dependencyTags.fmm}:metric",
        "objectsFile": "<path-to-metric-types.json>"
      }
    ]

The same metric type can be reported on multiple entities and from multiple sources, and each unique combination of type + entityId + attributes + source is referred to as a metric time series.

Assign Metrics to Entities

After you define the fmm:metric object, you need to assign the metrics to the respective entities in the data model. Use the metricTypes attribute of the fmm:entity object that provides a list of strings containing the fully qualified type names of the metrics to assign to the entity.