Metrics

Noct says what it’s doing at /api/metrics, in Prometheus’s text format, for Prometheus, Grafana Agent, VictoriaMetrics or anything else that scrapes it. For “is it up”, use /api/health instead, which anyone can ask and which the Docker image’s health check already does.

Turning it on

Metrics say what’s in the library (how many films, the paths of its folders), so they’re off until the server is given a token for them:

NOCT_METRICS_TOKEN=$(openssl rand -hex 32)

With none, /api/metrics answers 404. With one, it answers a request that sends it as Authorization: Bearer <token> and refuses anything else with a 401, including a profile’s token, the admin’s too: a scraper is given a token that can read the metrics and do nothing else. It’s on the same port as everything else.

prometheus.yml

scrape_configs:
  - job_name: noct
    metrics_path: /api/metrics
    authorization:
      credentials_file: /etc/prometheus/noct-token
    static_configs:
      - targets: ["nas.local:7356"]

Noct speaks plain HTTP, so on anything but your own network the token can be read on the way, as anything else can: see security.

The tray app (macOS and Windows) has no metrics, as it isn’t given a token.

What there is

Counters start at zero when the server starts. Everything else is worked out when it’s asked for, from the database and what the server has in memory, so a scrape costs a few small queries and a look at each watched folder.

Metric	Type	Labels	What it is
noct_build_info	gauge	version	Always 1; the version is the label.
process_start_time_seconds	gauge		When the server started, in seconds since the Unix epoch. Uptime is time() - process_start_time_seconds.
noct_items	gauge	kind: movie, series, season, episode	Items in the library.
noct_files	gauge	status: pending, processing, published, failed; stage	Files, by where they are in the pipeline. stage is the one a file is waiting for, in, or failed in, and empty for a file that’s through (published) or not started. A stuck pipeline is pending files that don’t go down; failed by stage says where files fail.
noct_files_missing	gauge		Files a scan found gone, which are removed if they stay that way for a day.
noct_files_bytes	gauge		The size of every file in the library.
noct_database_bytes	gauge		The size of the database.
noct_stage_runs_total	counter	stage; outcome: done, retry, failed	Files each stage has worked on. retry is a failure that will be tried again (TMDB unavailable, say), failed one that won’t.
noct_stage_duration_seconds	summary	stage	Time each stage has spent on files: _sum in seconds and _count of files. rate(_sum) / rate(_count) is the average.
noct_folder_online	gauge	folder: its path	1 if a watched folder can be read, 0 if not (an unmounted share). A folder that takes longer than 2 seconds to answer counts as 0.
noct_scan_duration_seconds	gauge	folder: its path	How long the folder’s latest scan took, for folders scanned since the server started.
noct_scans_running	gauge		Folders being scanned right now.
noct_tmdb_requests_total	counter	status: TMDB’s HTTP status, or error	Requests sent to TMDB’s API. A retry is another request; 429 is TMDB asking Noct to slow down. Images aren’t counted.
noct_tmdb_cache_lookups_total	counter	result: hit, miss	TMDB responses looked for in Noct’s cache. The hit rate is rate(hit) / rate(hit + miss).
noct_playback_sessions	gauge		Files being converted for playback right now (HLS). A file a player can take as it is isn’t converted, so isn’t one.
noct_playback_transcodes	gauge		Of those, the ones having their video encoded, which is what takes a CPU or graphics card.