From ca03b5d9ae17e7d822f43a1d13b044bceceaedd3 Mon Sep 17 00:00:00 2001 From: Alistair Young Date: Sat, 10 Oct 2026 23:37:38 -0500 Subject: [PATCH] Make the Home Assistant alert messages readable aloud; note the CronJob time zone - Backup stale: the on message now turns last_success (an ISO 8601 UTC timestamp) into local time, phrased for speech: "since yesterday at 9:15 PM", "since Tuesday, October 6 at 11:30 PM", or "yet". - Backup failed: a short on message for announcing; the technical error text moves to the card message. - Target names are read as words (- and _ become spaces). - README and cronjob.yaml: the default schedule is 02:15 UTC; set timeZone to your own zone. Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- deploy/k8s/cronjob.yaml | 1 + docs/home-assistant.md | 26 ++++++++++++++++++++++++-- 3 files changed, 26 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 857a8a7..944abe8 100644 --- a/README.md +++ b/README.md @@ -120,7 +120,7 @@ kubectl -n db-backup create job --from=cronjob/db-backup db-backup-manual kubectl -n db-backup logs -f job/db-backup-manual ``` -The schedule is in `cronjob.yaml`. If you change it, adjust the staleness threshold in your Home Assistant alert to match. +The schedule is in `cronjob.yaml`, along with its `timeZone`, which is `Etc/UTC` unless you change it: the default 02:15 is UTC, not your local time. Set it to your own zone, e.g. `timeZone: America/Chicago`. If you change the schedule, adjust the staleness threshold in your Home Assistant alert to match. ## Commands diff --git a/deploy/k8s/cronjob.yaml b/deploy/k8s/cronjob.yaml index 5905b1f..aba883c 100644 --- a/deploy/k8s/cronjob.yaml +++ b/deploy/k8s/cronjob.yaml @@ -4,6 +4,7 @@ metadata: name: db-backup spec: schedule: "15 2 * * *" + # The schedule's time zone: set your own (e.g. America/Chicago), or 02:15 is UTC. timeZone: Etc/UTC # Never two runs at once (the tool also takes a per-target lock on the share). concurrencyPolicy: Forbid diff --git a/docs/home-assistant.md b/docs/home-assistant.md index d674965..9849dc9 100644 --- a/docs/home-assistant.md +++ b/docs/home-assistant.md @@ -28,7 +28,10 @@ This fires as soon as a run reports a failure. | Targets → entity ID pattern | `sensor.dbbackup_*_status` | | Target state | `failed` | | Priority | Critical | -| On message | `Backup of {{ state_attr(target, 'target') }} failed: {{ state_attr(target, 'error') }}` | +| On message | `The backup of {{ state_attr(target, 'target') \| replace('-', ' ') \| replace('_', ' ') }} failed.` | +| Card message | `Backup of {{ state_attr(target, 'target') }} failed: {{ state_attr(target, 'error') or 'no error recorded' }}` | + +The on message is the one that's sent, and announced if your notifications are spoken, so it stays a short sentence. Target names have their `-` and `_` turned into spaces, so they're read as words. The error itself, often a long and technical client-tool message, goes in the card message, where you can read it. It stops firing by itself once a later run of that target succeeds. @@ -44,7 +47,9 @@ A CronJob that never runs reports nothing, so failure alerts alone can't catch i | Targets → entity ID pattern | `sensor.dbbackup_*_status` | | Template | see below | | Priority | Critical | -| On message | `No successful backup of {{ state_attr(target, 'target') }} since {{ state_attr(target, 'last_success') or 'ever' }}` | +| On message | see below | + +The template: ```jinja {% set last = state_attr(target, 'last_success') %} @@ -53,6 +58,23 @@ A CronJob that never runs reports nothing, so failure alerts alone can't catch i The 26 hours suit a daily schedule: a day, plus slack for a long run. Use your interval plus a margin if you change the schedule. A target that has never succeeded counts as stale. +The on message: + +```jinja +{%- set last = state_attr(target, 'last_success') -%} +{%- set name = state_attr(target, 'target') | replace('-', ' ') | replace('_', ' ') -%} +{%- if last -%} + {%- set t = as_local(as_datetime(last)) -%} + {%- set days = (now().date() - t.date()).days -%} + {%- set day = 'today' if days == 0 else 'yesterday' if days == 1 else t.strftime('%A, %B %-d') -%} + No successful backup of {{ name }} since {{ day }} at {{ t.strftime('%-I:%M %p') }}. +{%- else -%} + No successful backup of {{ name }} yet. +{%- endif -%} +``` + +`last_success` is an ISO 8601 timestamp in UTC, such as `2026-10-10T02:15:19+00:00`. That's exact, but hard to read at a glance, and a speaker reads it out as a string of numbers. The message converts it to Home Assistant's local time zone and phrases it as speech: "No successful backup of postgres main since yesterday at 9:15 PM." Older timestamps read "since Tuesday, October 6 at 11:30 PM", and a target that has never succeeded reads "No successful backup of postgres main yet." For 24-hour time, use `%H:%M` instead of `%-I:%M %p`. + ### Supersession Both generators target the same status sensor, so they can be linked. In **Backup failed**'s **Supersession** section, add the **Backup stale** generator: each target's *Backup failed* alert then supersedes its *Backup stale* alert. While a target is failing you hear about the failure; you don't get a second alert a day later saying the same thing.