checkfleet

mediamtx streaming server check

mediamtx — mediamtx streaming server

Paths present and ready via the v3 control API, expected paths missing, stalled ingest (ready but zero bytes received), readers per path.

checkfleet check mediamtx --config checkfleet.yml

Reads the v3 control API of a mediamtx server: which paths exist, whether each is ready, and what is flowing through it.

This is the layer nothing else in checkfleet can see. ingest says a streamer can connect and stream says a manifest is being served — but between them sits the failure that takes a broadcast off the air quietly: the encoder died, the path went not-ready, and the manifest is still cached downstream, so every other probe stays green.

  • API reachable — one finding per target, with the path count as its metric. WARN over max_latency_ms, ERROR when the API is unreachable, rejects the credentials (401) or answers anything but 200. ERROR, not BAD: an API that cannot be read says nothing about whether the streams are healthy.
  • Per path — BAD when a path is not ready (no publisher: the encoder is gone), BAD when it is ready but has received zero bytes (the publisher connected and went silent, which looks identical to health from the outside), otherwise OK with the source type, the tracks and the reader count as its metric.
  • expect_paths turns the question from “are the paths that exist healthy” into “are the paths that must be on the air on the air”. A path that vanished from the server’s config is invisible to the first question and BAD under the second. Without it, every path the server reports is judged.
  • warn_no_readers WARNs on a ready path nobody is reading. Off by default: a stream with no viewers at 04:00 is the middle of the night, not a fault.

Credentials are HTTP basic auth with the password from an env var, and the check never calls anything but /v3/paths/list — it cannot create or delete a path. Pagination is followed, because a truncated path list is the same failure as not checking the missing ones. Zero-dep HTTP/JSON, tested against a fake mediamtx in-test.

  mediamtx:
    targets:
      - name: mtx-01
        url: http://mtx-01:9997      # API base, no path
        expect_paths: [live/stream1, live/stream2]
        warn_no_readers: false
        max_latency_ms: 1000

See the full module reference for every check, or configuration for the config keys.