Metrics

Query the collected metrics.

The core can collect metrics about itself, the system it is running on, and about the FFmpeg processes it is executing. This is not enabled by default. Please check the metrics configuration for how to enable it and how often metrics should be collected and for how long metrics should be kept available for querying.

Each metric is collected by a collector, like a topic. Each collector can contain several metrics and each metric can have labels to describe a variant of that metric. Think of used space on a filesystem where the variant is whether it is a disk filesystem or a memory filesystem.

All metrics can be scraped by Prometheus from the /metrics endpoint, if enabled.

List collectors

In order to know which metrics are available and to learn what they mean, you can retrieve a list of all metrics, their descriptions and labels.

Example:

Curl

curl http://127.0.0.1:8080/api/v3/metrics \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -X GET

PyClient

from core_client import Client

client = Client(
    base_url="http://127.0.0.1:8080"
)
client.login()

core_metrics_collection_list = client.v3_metrics_get()
print(core_metrics_collection_list)

GoClient

import (
    "fmt"
    "github.com/datarhei/core-client-go/v16"
)

client, _ := coreclient.New(coreclient.Config{
    Address: "https://127.0.0.1:8080",
})

metrics, err := client.MetricsList()

for _, m := range metrics {
    fmt.Printf("%+v\n", m)
}

Description:

List all known metrics with their description and labels

get

List all known metrics with their description and labels

Authorizations

AuthorizationstringRequired

Responses

200

OK

application/json

descriptionstringOptional

labelsstring[]Optional

namestringOptional

get/api/v3/metrics

GET /api/v3/metrics HTTP/1.1
Authorization: YOUR_API_KEY
Accept: */*

200

OK

[
  {
    "description": "text",
    "labels": [
      "text"
    ],
    "name": "text"
  }
]

Query metrics

All collected metrics can be queried by sending a query to the /api/v3/metrics endpoint. This query contains the names of the metrics with the labels you are interested in. Leave out the labels in order to get the values for all labels of that metrics. By default you will receive the last collected value. You can also receive a whole timeseries for each metric and label by providing a timerange and stepsize in seconds.

Example:

Curl

curl http://127.0.0.1:8080/api/v3/metrics/ \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -X POST \
   -d '{
         "metrics": [
            {
               "name": "cpu_idle"
            }, {
               "name": "mem_free"
            }
         ]
      }'

PyClient

from core_client import Client

client = Client(base_url="http://127.0.0.1:8080")
client.login()

core_metrics = client.v3_metrics_post(
   config={
      "metrics": [
         {
            "name": "cpu_idle"
         }, {
            "name": "mem_free"
         }
      ]
   }
)
print(core_metrics)

GoClient

import (
    "fmt"
    "github.com/datarhei/core-client-go/v16"
    "github.com/datarhei/core-client-go/v16/api"
)

client, _ := coreclient.New(coreclient.Config{
    Address: "https://127.0.0.1:8080",
})

// get the latest collected value
query := api.MetricsQuery{
    Metrics: []api.MetricsQueryMetric{
        {
            Name: "cpu_idle",
        },
        {
            Name: "mem_free",
        },
    }
}

metrics, err := client.Metrics(query)
fmt.Printf("%+v\n", metrics)

// get the collected values from the last 10 minutes in
// steps of 5 seconds
query := api.MetricsQuery{
    Timerange: 600,
    Interval: 5,
    Metrics: []api.MetricsQueryMetric{
        {
            Name: "cpu_idle",
        },
        {
            Name: "mem_free",
        },
    }
}

metrics, err := client.Metrics(query)
fmt.Printf("%+v\n", metrics)

Description:

Query the collected metrics

post

Query the collected metrics

Authorizations

AuthorizationstringRequired

Body

interval_secinteger · int64Optional

timerange_secinteger · int64Optional

Responses

200

OK

application/json

interval_secinteger · int64Optional

timerange_secinteger · int64Optional

400

Bad Request

application/json

post/api/v3/metrics

POST /api/v3/metrics HTTP/1.1
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 108

{
  "interval_sec": 1,
  "metrics": [
    {
      "labels": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "name": "text"
    }
  ],
  "timerange_sec": 1
}

{
  "interval_sec": 1,
  "metrics": [
    {
      "labels": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "name": "text",
      "values": [
        {
          "ts": "text",
          "value": 1
        }
      ]
    }
  ],
  "timerange_sec": 1
}

Available collectors

CPU

[
    {
        "name": "cpu_idle",
        "description": "Percentage of idle CPU",
        "labels": []
    },
    {
        "name": "cpu_ncpu",
        "description": "Number of logical CPUs in the system",
        "labels": []
    },
    {
        "name": "cpu_other",
        "description": "Percentage of CPU used for other subsystems",
        "labels": []
    },
    {
        "name": "cpu_system",
        "description": "Percentage of CPU used for the system",
        "labels": []
    },
    {
        "name": "cpu_user",
        "description": "Percentage of CPU used for the user",
        "labels": []
    }
]

Memory

[
    {
        "name": "mem_free",
        "description": "Free memory in bytes",
        "labels": []
    },
    {
        "name": "mem_total",
        "description": "Total available memory in bytes",
        "labels": []
    }
]

Disk

[
    {
        "name": "disk_total",
        "description": "Total size of the disk in bytes",
        "labels": [
            "path"
        ]
    },
    {
        "name": "disk_usage",
        "description": "Number of used bytes on the disk",
        "labels": [
            "path"
        ]
    }
]

Filesystem

[
    {
        "name": "filesystem_files",
        "description": "Number of files on the filesystem (excluding directories)",
        "labels": [
            "name"
        ]
    },
    {
        "name": "filesystem_limit",
        "description": "Total size of the filesystem in bytes, negative if unlimited",
        "labels": [
            "name"
        ]
    },
    {
        "name": "filesystem_usage",
        "description": "Number of used bytes on the filesystem",
        "labels": [
            "name"
        ]
    }
]jso

Network

[
    {
        "name": "net_rx",
        "description": "Number of received bytes",
        "labels": [
            "interface"
        ]
    },
    {
        "name": "net_tx",
        "description": "Number of transmitted bytes",
        "labels": [
            "interface"
        ]
    }
]

FFmpeg

[{
    "name": "ffmpeg_process",
    "description": "State of the ffmpeg process",
    "labels": [
        "state"
    ]
}]

Restream IO

[
    {
        "name": "restream_io",
        "description": "Current process IO values by name",
        "labels": [
            "processid",
            "type",
            "id",
            "address",
            "index",
            "stream",
            "media",
            "name"
        ]
    },
    {
        "name": "restream_process",
        "description": "Current process values by name",
        "labels": [
            "processid",
            "state",
            "order",
            "name"
        ]
    },
    {
        "name": "restream_process_states",
        "description": "Current process state",
        "labels": [
            "processid",
            "state"
        ]
    },
    {
        "name": "restream_state",
        "description": "Summarized process states",
        "labels": [
            "state"
        ]
    }
]

Sessions

[
    {
        "name": "session_active",
        "description": "Number of current sessions",
        "labels": [
            "collector"
        ]
    },
    {
        "name": "session_limit",
        "description": "Max. number of concurrent sessions",
        "labels": [
            "collector"
        ]
    },
    {
        "name": "session_maxrxbitrate",
        "description": "Max. allowed receiving bitrate in bit per second",
        "labels": [
            "collector"
        ]
    },
    {
        "name": "session_maxtxbitrate",
        "description": "Max. allowed transmitting bitrate in bit per second",
        "labels": [
            "collector"
        ]
    },
    {
        "name": "session_rxbitrate",
        "description": "Current receiving bitrate in bit per second",
        "labels": [
            "collector"
        ]
    },
    {
        "name": "session_rxbytes",
        "description": "Number of received bytes",
        "labels": [
            "collector"
        ]
    },
    {
        "name": "session_total",
        "description": "Total sessions",
        "labels": [
            "collector"
        ]
    },
    {
        "name": "session_txbitrate",
        "description": "Current transmitting bitrate in bit per second",
        "labels": [
            "collector"
        ]
    },
    {
        "name": "session_txbytes",
        "description": "Number of transmitted bytes",
        "labels": [
            "collector"
        ]
    }
]

Uptime

[
    {
        "name": "uptime_uptime",
        "description": "Current uptime in seconds",
        "labels": []
    }
]