Metrics

Query the collected metrics.

Last updated 2 years ago

Was this helpful?

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 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 http://127.0.0.1:8080/api/v3/metrics \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -X GET

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)

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:

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 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"
            }
         ]
      }'

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)

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:

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": []
    }
]

PreviousS3 NextSessions

Last updated 2 years ago

Was this helpful?

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 http://127.0.0.1:8080/api/v3/metrics \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -X GET

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)

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:

Query metrics

Example:

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"
            }
         ]
      }'

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)

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:

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": []
    }
]

List all known metrics with their description and labels

get

List all known metrics with their description and labels

Authorizations

Responses

200

application/json

get

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

200

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

Query the collected metrics

post

Query the collected metrics

Authorizations

Body

interval_secinteger · int64Optional

timerange_secinteger · int64Optional

Responses

200

application/json

400

Bad Request

application/json

post

POST /v3/metrics HTTP/1.1
Host: api
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
}