Overview

The Telemetry APIs are a special subsection of the Intersight API focused on time-series data. These APIs do not support the OData parameters like $filter and have a different request structure. This guide will describe how you can query time series information from Intersight.

Understanding the stored data

Intersight uses the OpenTelemetry standard to structure our stored information. Whenever there is a standard defined by OpenTelemetry, it is followed by Intersight. For those aspects where no standard is defined, Intersight trys to stay as close as possible to OpenTelemetry best practices.

What is OpenTelemetry?

Before we get into Intersight's telemetry APIs, let's first talk about what OpenTelemetry is. Essentially, it is a framework and toolkit for managing different types of telemetry data. It consists of standards as well as implementations. For the purposes of Intersight, the important part is that the Intersight backend is based on OpenTelemetry. Specifically, Intersight follows the OpenTelemetry Protocol (OTLP). While OpenTelemetry offers a standard for a lot of different observability options, Intersight specifically focuses on metrics.

An introduction to Metrics

Metrics are a measurement for a specific entity. For example, the measurement of the fan speed for a specific device at a specific point in time would be a metric event. In addition to this basic information, metrics can also have additional attributes. Continuing with the fan example, attributes could include things like the ID of the fan or the host name of the server.

Intersight endpoints capture metric events by collecting a lot of datapoints locally. In regular intervals the endpoint will then aggregate this data. Depending on the type of data different operations will be performed. An example of this would be calculating the minimum, average, and maximum value. After this is done, these values are sent to Intersight.

The other important aspect surrounding metrics are instruments. These are essentially groupings of related metrics. The Fan Speed metric would be part of a Fan instrument. This instrument will also contain other metrics for Fans, for example the Fan Speed Ratio.

Getting Metrics information

Now that you understand how the data in Intersight looks like - where would you get the required information for building an API query. You can look directly in the UI and try to copy information from there. You can also go to the Supported Metrics documentation where you can find the full documentation of all metrics, including all details such as attributes.

Telemetry API Details

Intersight uses Apache Druid to store all metrics information, and also enables you to query this information using the native Druid query language. This guide will first show you how you can simply copy queries from the UI, then we will explain how you can create your own queries. Either way, your queries can use the /api/v1/telemetry/TimeSeries endpoint.

Using the UI to build queries

If you already have a query built in the Intersight UI, you can go to the Code tab and simply copy the query from there. Let's look at an example for this: Code Tab

As you can see, we have a query for fan speed. Be aware that the queries are saved as a JSON list in case there are multiple queries required to render the graph. You will have to remove the individual requests from it like this:

  {
    "queryType": "groupBy",
    "dataSource": "PhysicalEntities",
    "granularity": {
      "type": "period",
      "period": "PT12H",
      "timeZone": "Europe/Vienna",
      "origin": "2023-07-27T21:24:00.000Z"
    },
    "intervals": [
      "2023-07-27T21:24:00.000Z/2023-08-03T21:24:00.000Z"
    ],
    "dimensions": [],
    "filter": {
      "type": "and",
      "fields": [
        {
          "type": "selector",
          "dimension": "instrument.name",
          "value": "hw.fan"
        }
      ]
    },
    "aggregations": [
      {
        "type": "longMax",
        "name": "hw-fan-speed_max-Max",
        "fieldName": "hw.fan.speed_max"
      }
    ]
  }

As you can see, we are only stripping the outer "[" and "]". You can then run each individual query against the telemetry/TimeSeries API.

Druid query types

Druid supports multiple query types, each of which serves its own purpose. The available types are:

Aggegation queries

  • Timeseries
  • TopN
  • GroupBy

Metadata queries

  • Timeboundary
  • SegmentMetadata
  • DataSourceMetadata

Other queries

  • Scan
  • Search

In this guide we will focus on the GroupBy queries which are also used to build all graphs in the UI. If you are interested in the other query types, check out the official Druid documentation to learn more.