docs: add monitoring chapter for status & prometheus (#505)

Author: creativeprojects

config/profile.go

@@ -136,7 +136,9 @@ func (i *InitSection) resolve(_ *Profile) {
 	i.FromRepository.setValue(fixPath(i.FromRepository.Value(), expandEnv, expandUserHome))
 }
 
-func (i *InitSection) setRootPath(_ *Profile, rootPath string) {
+func (i *InitSection) setRootPath(p *Profile, rootPath string) {
+	i.GenericSection.setRootPath(p, rootPath)
+
 	i.FromRepositoryFile = fixPath(i.FromRepositoryFile, expandEnv, expandUserHome, absolutePrefix(rootPath))
 	i.FromPasswordFile = fixPath(i.FromPasswordFile, expandEnv, expandUserHome, absolutePrefix(rootPath))
 }

docs/content/_index.md

@@ -23,10 +23,10 @@ With resticprofile:
 * Check for [enough memory]({{% relref "/usage/memory" %}}) before starting a backup
 * Generate cryptographically secure random keys for a restic [key file]({{% relref "/usage/keyfile" %}})
 * Easily [schedule]({{% relref "/schedules" %}}) backups, retentions, and checks (supports *systemd*, *crond*, *launchd*, and *Windows Task Scheduler*)
-* Generate a simple [status file]({{% relref "/status" %}}) for monitoring software to ensure backups are running smoothly
+* Generate a simple [status file]({{% relref "/monitoring/status" %}}) for monitoring software to ensure backups are running smoothly
 * Use [template syntax]({{% relref "/configuration/templates" %}}) in your configuration file
 * Automatically clear [stale locks]({{% relref "/usage/locks" %}})
-* Export a [prometheus]({{% relref "/status/prometheus" %}}) file after a backup or send the report to a push gateway
+* Export a [prometheus]({{% relref "/monitoring/prometheus" %}}) file after a backup or send the report to a push gateway
 * Run shell commands in the background when non-fatal errors are detected
 * Send messages to [HTTP hooks]({{% relref "/configuration/http_hooks" %}}) before, after a successful or failed job (backup, forget, check, prune, copy)
 * Automatically [initialize the secondary repository]({{% relref "/configuration/copy" %}}) using the `copy-chunker-params` flag

docs/content/configuration/http_hooks.md

@@ -1,6 +1,7 @@
 ---
 title: "HTTP Hooks"
 weight: 22
+tags: [ "monitoring", "healthchecks.io" ]
 ---
 
 

docs/content/configuration/run_hooks.md

@@ -1,6 +1,7 @@
 ---
 title: "Command Hooks"
 weight: 20
+tags: [ "monitoring" ]
 ---
 
 

docs/content/monitoring/_index.md

@@ -0,0 +1,8 @@
+---
+archetype: "chapter"
+pre: "<b>5. </b>"
+title: "Monitoring"
+weight: 5
+---
+
+{{% children  %}}

docs/content/status/prometheus.md docs/content/monitoring/prometheus.mddocs/content/status/prometheus.md renamed to docs/content/monitoring/prometheus.md

@@ -1,12 +1,11 @@
 ---
 title: "Prometheus"
-weight: 5
+slug: prometheus
+weight: 10
+tags: [ "monitoring" ]
 ---
 
-
-
-resticprofile can generate a prometheus file, or send the report to a push gateway. For now, only a `backup` command will generate a report.
-Here's a configuration example with both options to generate a file and send to a push gateway:
+Resticprofile can generate a Prometheus file or send the report to a Pushgateway. Currently, only the `backup` command generates a report. Below is a configuration example for generating a file and sending it to a Pushgateway:
 
 {{< tabs groupid="config-with-json" >}}
 {{% tab title="toml" %}}
@@ -80,66 +79,69 @@ root:
 {{< /tabs >}}
 
 {{% notice style="note" %}}
-Please note you need to set `extended-status` to `true` if you want all the available metrics. See [Extended status]({{% relref "/status/index.html#-extended-status" %}}) for more information.
+Set `extended-status` to `true` to access all available metrics. For details, see [Extended status]({{% relref "/monitoring/status/index.html#-extended-status" %}}).
 {{% /notice %}}
 
-Here's an example of the generated prometheus file:
+Here's an example of a generated prometheus file:
 
 ```
+# HELP restic_build_info restic build information.
+# TYPE restic_build_info gauge
+restic_build_info{profile="prom",version="0.18.0"} 1
 # HELP resticprofile_backup_added_bytes Total number of bytes added to the repository.
 # TYPE resticprofile_backup_added_bytes gauge
-resticprofile_backup_added_bytes{profile="prom"} 9.83610983e+08
+resticprofile_backup_added_bytes{profile="prom"} 96167
 # HELP resticprofile_backup_dir_changed Number of directories with changes.
 # TYPE resticprofile_backup_dir_changed gauge
-resticprofile_backup_dir_changed{profile="prom"} 0
+resticprofile_backup_dir_changed{profile="prom"} 8
 # HELP resticprofile_backup_dir_new Number of new directories added to the backup.
 # TYPE resticprofile_backup_dir_new gauge
-resticprofile_backup_dir_new{profile="prom"} 847
+resticprofile_backup_dir_new{profile="prom"} 0
 # HELP resticprofile_backup_dir_unmodified Number of directories unmodified since last backup.
 # TYPE resticprofile_backup_dir_unmodified gauge
-resticprofile_backup_dir_unmodified{profile="prom"} 0
+resticprofile_backup_dir_unmodified{profile="prom"} 1060
 # HELP resticprofile_backup_duration_seconds The backup duration (in seconds).
 # TYPE resticprofile_backup_duration_seconds gauge
-resticprofile_backup_duration_seconds{profile="prom"} 4.453124672
+resticprofile_backup_duration_seconds{profile="prom"} 0.986296416
 # HELP resticprofile_backup_files_changed Number of files with changes.
 # TYPE resticprofile_backup_files_changed gauge
-resticprofile_backup_files_changed{profile="prom"} 0
+resticprofile_backup_files_changed{profile="prom"} 2
 # HELP resticprofile_backup_files_new Number of new files added to the backup.
 # TYPE resticprofile_backup_files_new gauge
-resticprofile_backup_files_new{profile="prom"} 6006
+resticprofile_backup_files_new{profile="prom"} 0
 # HELP resticprofile_backup_files_processed Total number of files scanned by the backup for changes.
 # TYPE resticprofile_backup_files_processed gauge
-resticprofile_backup_files_processed{profile="prom"} 6006
+resticprofile_backup_files_processed{profile="prom"} 7723
 # HELP resticprofile_backup_files_unmodified Number of files unmodified since last backup.
 # TYPE resticprofile_backup_files_unmodified gauge
-resticprofile_backup_files_unmodified{profile="prom"} 0
+resticprofile_backup_files_unmodified{profile="prom"} 7721
 # HELP resticprofile_backup_processed_bytes Total number of bytes scanned for changes.
 # TYPE resticprofile_backup_processed_bytes gauge
-resticprofile_backup_processed_bytes{profile="prom"} 1.016520315e+09
+resticprofile_backup_processed_bytes{profile="prom"} 2.935621558e+09
 # HELP resticprofile_backup_status Backup status: 0=fail, 1=warning, 2=success.
 # TYPE resticprofile_backup_status gauge
 resticprofile_backup_status{profile="prom"} 2
 # HELP resticprofile_backup_time_seconds Last backup run (unixtime).
 # TYPE resticprofile_backup_time_seconds gauge
-resticprofile_backup_time_seconds{profile="prom"} 1.707863748e+09
+resticprofile_backup_time_seconds{profile="prom"} 1.747673785e+09
 # HELP resticprofile_build_info resticprofile build information.
 # TYPE resticprofile_build_info gauge
-resticprofile_build_info{goversion="go1.22.0",profile="prom",version="0.26.0"} 1
+resticprofile_build_info{goversion="go1.24.3",profile="prom",version="0.31.0"} 1
+
 
 ```
 
 ## Prometheus Pushgateway
 
-Prometheus Pushgateway uses the job label as a grouping key. All metrics with the same grouping key get replaced when pushed. To prevent metrics from multiple profiles getting overwritten by each other, the default job label is set to `<profile_name>.<command>` (e.g. `root.backup`).
+Prometheus Pushgateway uses the job label as a grouping key. Metrics with the same grouping key are replaced when pushed. To prevent overwriting metrics from different profiles, the default job label is set to `<profile_name>.<command>` (e.g., `root.backup`).
 
-If you need more control over the job label, you can use the `prometheus-push-job` property. This property can contain the `$command` placeholder, which is replaced with the name of the executed command.
+For more control over the job label, use the `prometheus-push-job` property. This property supports the `$command` placeholder, which is replaced with the executed command's name.
 
-Additionally, the request format can be specified with `prometheus-push-format`. The default is `text`, but it can also be set to `protobuf` (see [compatibility with Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/#exposition-formats)).
+You can specify the request format using `prometheus-push-format`. The default is `text`, but it can also be set to `protobuf` (see [compatibility with Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/#exposition-formats)).
 
-## User defined labels
+## User-Defined Labels
 
-You can add your own prometheus labels. Please note they will be applied to **all** the metrics.
-Here's an example:
+You can add custom Prometheus labels, which will apply to **all** metrics. Example:
 
 {{< tabs groupid="config-with-json" >}}
 {{% tab title="toml" %}}
@@ -227,4 +229,4 @@ root:
 {{< /tabs >}}
 
 
-which will add the `host` label to all your metrics.
+This adds the `host` label to all your metrics.

docs/content/status/_index.md docs/content/monitoring/status.mddocs/content/status/_index.md renamed to docs/content/monitoring/status.md

@@ -1,16 +1,17 @@
-+++
-archetype = "chapter"
-pre = "<b>5. </b>"
-title = "Status file"
-weight = 5
-+++
+---
+title: "Status file"
+slug: status
+weight: 5
+tags: [ "monitoring" ]
+aliases:
+  - /status
+---
 
+If you need to send your backup results to a monitoring system, use the `run-after` and `run-after-fail` scripts.
 
-If you need to escalate the result of your backup to a monitoring system, you can definitely use the `run-after` and `run-after-fail` scripting.
+For simpler needs, resticprofile can generate a JSON file with details of the latest backup, forget, or check command. For example, I use a Zabbix agent to [check this file](https://github.com/creativeprojects/resticprofile/tree/master/contrib/zabbix) daily. Any monitoring system that reads JSON files can be integrated.
 
-But sometimes we just need something simple that a monitoring system can regularly check. For that matter, resticprofile can generate a simple JSON file with the details of the latest backup/forget/check command. For example I have a Zabbix agent [checking this file](https://github.com/creativeprojects/resticprofile/tree/master/contrib/zabbix) once a day, and so you can hook up any monitoring system that can interpret a JSON file.
-
-In your profile, you simply need to add a new parameter, which is the location of your status file
+To enable this, add the status file location as a parameter in your profile.
 
 {{< tabs groupid="config-with-json" >}}
 {{% tab title="toml" %}}
@@ -57,7 +58,7 @@ profile:
 {{< /tabs >}}
 
 
-Here's an example of a generated file, where you can see that the last `check` failed, whereas the last `backup` succeeded:
+Here is an example of a generated file showing the last `check` failed, while the last `backup` succeeded:
 
 ```json
 {
@@ -93,18 +94,18 @@ Here's an example of a generated file, where you can see that the last `check` f
 
 ## ⚠️ Extended status
 
-In the backup section above you can see some fields like `files_new`, `files_total`, etc. This information is only available when resticprofile's output is either *not* sent to the terminal (e.g. redirected) or when you add the flag `extended-status` to your backup configuration.
+In the backup section above, you can see fields like `files_new` and `files_total`. This information is available only when resticprofile's output is redirected or when the `extended-status` flag is added to your backup configuration.
 
-This is a technical limitation to ensure restic displays terminal output correctly. 
+This limitation ensures restic displays terminal output correctly.
 
-`extended-status` or stdout redirection is **not needed** for these fields:
+The following fields do **not** require `extended-status` or stdout redirection:
 - success
 - time
 - error
 - stderr
 - duration
 
-`extended-status` is **not set by default because it hides any output from restic**
+The `extended-status` flag is **disabled by default because it suppresses restic's output**.
 
 {{< tabs groupid="config-with-json" >}}
 {{% tab title="toml" %}}

docs/hugo.toml

@@ -40,10 +40,10 @@ publishdir = "../public/"
   main = false
   type = 'menu'
 
-# [[menu.shortcuts]]
-#   name = "<i class='fas fa-tags'></i> Tags"
-#   url = "/tags"
-#   weight = 10
+[[menu.shortcuts]]
+  name = "<i class='fas fa-tags'></i> Tags"
+  url = "/tags"
+  weight = 10
 
 [[menu.shortcuts]]
   name = "<i class='fab fa-fw fa-github'></i> GitHub repo"

examples/dev.yaml

@@ -129,6 +129,23 @@ self:
         schedule:
             - "*:05,10,15,20,25,35"
         schedule-permission: user
+        run-before:
+            - "echo Check started"
+        run-after:
+            - "echo Check done"
+        send-before:
+            - url: "https://httpbin.org/status/400"
+        send-after:
+            - url: "https://httpbin.org/status/400"
+    init:
+        run-before:
+            - "echo Init started"
+        run-after:
+            - "echo Init done"
+        send-before:
+            - url: "https://httpbin.org/status/400"
+        send-after:
+            - url: "https://httpbin.org/status/400"
     retention:
         after-backup: true
         keep-last: 30
@@ -173,8 +190,8 @@ prom:
     inherit: default
     prometheus-save-to-file: "self.prom"
     prometheus-push: "http://localhost:9091/"
-    prometheus-labels:
-        host: "{{ .Hostname }}"
+    # prometheus-labels:
+    #     host: "{{ .Hostname }}"
     status-file: /Volumes/RAMDisk/status.json
     backup:
         check-after: true