Working with the Data API

The data API provides access to the labels and metrics data captured by Sysdig agents and stored in the Sysdig datastores. Sysdig agents capture process, network, system and other infrastructure data with a 1-second resolution, and sends them to the Sysdig worker service with a 10-second resolution.

The data API allows you to fetch data at the native resolution of 10-second or lower. You can specify the resolution to return data via the sampling parameter. Each resolution has different data retention periods. Since native data capturing is performed with a 1-second resolution, for each metric you need to specify a time aggregation.

Similarly, data associated with individual pods, processes, and so can be aggregated at a higher level. For example, at the host or namespace level. This type of aggregation depends on the list of labels you specify. For instance, you could aggregate data at the host level by specifying a host label. For this to work, you need to specify a group aggregation.

To learn more about data aggregation, see Data Aggregation.

General Guidelines for Using the Data API

• The maximum number of samples you can fetch via the data API is 600. Consequently, the larger the time window for the data retrieval, the lower the resolution will be.

• The API enforces a response timeout of 30 seconds. Larger time windows, a higher number of metrics, multiple segments (higher number of columns and rows) might cause a longer response time.

• Some labels might not apply to certain entities. When those labels are retrieved, the label value will be null.

• Due to a current limitation, the same metric name cannot be specified more than once independent of the aggregations.

REST Resource: Data

See Sysdig REST API Conventions for generic conventions and authentication.

Request Variables

(not) label operator value

POST /api/data
{
"filter": "kubernetes.node.name = 'n1'",
…

"metrics": [
    {"id": "container.name"},
    {
      "id": "cpu.cores.used",
      "aggregations": { "time": "avg", "group": "avg" }
    }

Response Variables

Sample Request and Response

In this example, CPU cores for containers are retrieved.

POST https://<your-Sysdig-URL>/api/data

{
  "last": 600,
  "sampling": 600,
  "filter": null,
  "metrics": [
    {
      "id": "cpu.cores.used",
      "aggregations": { "time": "avg", "group": "sum" }
    }
  ],
  "dataSourceType": "container",
  "paging": {
    "from": 0,
    "to": 99
  }
}

Ensure that you replace with your Sysdig URL associated with your region. For example:

POST https://us2.app.sysdig.com/api/data/

Given below is a sample response :

{
    "data": [
        {
            "t": 1582756200,
            "d": [
                6.481
            ]
        }
    ],
    "start": 1582755600,
    "end": 1582756200
}

Python Script Library for Data API

Sysdig Python client for interacting with the Data API. See Python SDC Client for comprehensive examples and documentation.

Function: sysdig_api.get_data

sdclient.get_data(metrics,start_ts,end_ts,sampling_s,filter,paging,datasource_type)

Returns the requested metrics data.

Arguments

Successful Return Value

Returns the requested metrics data in a JSON file.

Sample Script

ok, res = sysdig_api.get_data(
  start_ts = -600,
  end_ts = 0,
  sampling_s = 600,
  filter = None,
  metrics = [
    {
      "id": "cpu.cores.used",
      "aggregations": {
          "time": "avg",
          "group": "sum"
      }
    }
  ],
  datasource_type = "container",
  paging = {"from": 0, "to": 99}
)