From a39a2be03a670b705a7b852bbb59a98b3ad09db7 Mon Sep 17 00:00:00 2001 From: Philip Bernaerts Date: Fri, 21 Aug 2026 16:24:38 +0200 Subject: [PATCH] docs(monitoring): say in both configs why an edit needs a deploy Loki reads its config once at startup and has no reload endpoint, and Python reads main.py once when the process starts. Both are single-file bind mounts, so a git pull swaps the inode under a running container and a plain `docker compose up -d` applies nothing. Since #422 the DEP-6 hash label does apply an edit, and these headers say so where somebody is standing when they edit the file rather than only in the compose labels. Both files fail quietly if an edit never loads. loki-config.yml holds the retention settings, so a change that did not take either deletes logs you believed you were keeping or fills the disk. main.py carries the exporter's own scrape-health metrics, so stale code keeps reporting healthy while serving the old numbers. This is also the content-only change that proves the fingerprint path: the previous deploy recreated both services because the label block itself was new, which proves nothing about the digest. The next deploy changes bytes only. --- monitoring/loki/loki-config.yml | 12 ++++++++++++ monitoring/tautulli-exporter/main.py | 10 ++++++++++ 2 files changed, 22 insertions(+) diff --git a/monitoring/loki/loki-config.yml b/monitoring/loki/loki-config.yml index efea0ea8..100cb93a 100644 --- a/monitoring/loki/loki-config.yml +++ b/monitoring/loki/loki-config.yml @@ -1,3 +1,15 @@ +# Loki reads this file once, at startup. It has no reload endpoint and no +# SIGHUP reload; only a separate -runtime-config.file reloads live, and this +# stack passes -config.file only. It is also a single-file bind mount, so a git +# pull replaces it by rename and the running container keeps reading the old +# inode: a plain `docker compose up -d` changes nothing here. What applies an +# edit is the DEP-6 hash label, `homelab.config-sha` on the loki service in +# monitoring/compose.yaml, which deploy.yml sets to a sha256 of this file so a +# content change recreates the container. It matters most for the retention +# settings below: a retention_period edit that silently never loaded either +# deletes logs you believed you were keeping or fills the disk, and both look +# exactly like a healthy system until the damage is done. + auth_enabled: false server: diff --git a/monitoring/tautulli-exporter/main.py b/monitoring/tautulli-exporter/main.py index fabe4e75..20c24c57 100644 --- a/monitoring/tautulli-exporter/main.py +++ b/monitoring/tautulli-exporter/main.py @@ -14,6 +14,16 @@ # 5. Component transcode counts use Tautulli get_activity's stream_*_decision # fields (upstream looked for nonexistent transcode_*_decision fields). # Re-sync required if the image pin in monitoring/compose.yaml changes. +# +# Python reads this file once, when the process starts, and it is a single-file +# bind mount, so a git pull replaces it by rename and the running container +# keeps the old inode: a plain `docker compose up -d` applies nothing. What +# applies an edit is the DEP-6 hash label, homelab.config-sha on the +# tautulli-exporter service in monitoring/compose.yaml, which deploy.yml sets to +# a sha256 of this file so a content change recreates the container. Editing +# this file without a deploy leaves the old code serving the old numbers, and +# since two of the patches above are the exporter's own scrape-health metrics, +# nothing reports a problem while it does. import os import sys import json