feat(notifications): enhance default-legacy template with fields and debug logging (#200)

- Fixed missing container/image info in notifications by updating default-legacy template to use logrus fields
- Revised template to past tense ("Stopped", "Removed") and removed signal for consistency and brevity
- Added debug logging in shoutrrr.go for message generation and sending
- Updated Notifications.md to document new template and behavior
- Adjusted test to remove trailing newline expectation

Author: nicholas-fedor

cmd/root.go

@@ -809,6 +809,19 @@ func runUpdatesWithNotifications(filter types.Filter) *metrics.Metric {
 		logrus.WithError(err).Error("Update execution failed")
 	}
 
+	// Debug report
+	updatedNames := make([]string, 0, len(result.Updated()))
+	for _, r := range result.Updated() {
+		updatedNames = append(updatedNames, r.Name())
+	}
+
+	logrus.WithFields(logrus.Fields{
+		"scanned":       len(result.Scanned()),
+		"updated":       len(result.Updated()),
+		"failed":        len(result.Failed()),
+		"updated_names": updatedNames,
+	}).Debug("Report before notification")
+
 	// Send the batched notification with update results (successes, failures, etc.).
 	notifier.SendNotification(result)
 

docs/notifications.md

@@ -16,7 +16,7 @@ system, [logrus](http://github.com/sirupsen/logrus).
 
 ## Settings
 
-- `--notifications-level` (env. `WATCHTOWER_NOTIFICATIONS_LEVEL`): Controls the log level which is used for the notifications. If omitted, the default log level is `info`. Possible values are: `panic`, `fatal`, `error`, `warn`, `info`, `debug` or `trace`.
+- `--notifications-level` (env. `WATCHTOWER_NOTIFICATIONS_LEVEL`): Controls the log level for notifications. Defaults to `info`. In legacy mode (`--notification-report=false`), only `info`-level logs trigger notifications, ensuring a focused step-by-step update summary. Possible values: `panic`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`.
 - `--notifications-hostname` (env. `WATCHTOWER_NOTIFICATIONS_HOSTNAME`): Custom hostname specified in subject/title. Useful to override the operating system hostname.
 - `--notifications-delay` (env. `WATCHTOWER_NOTIFICATIONS_DELAY`): Delay before sending notifications expressed in seconds.
 - Watchtower will post a notification every time it is started. This behavior [can be changed](https://nicholas-fedor.github.io/watchtower/arguments/#without_sending_a_startup_message) with an argument.
@@ -47,17 +47,47 @@ Simple templates are used unless the `notification-report` flag is specified:
 
 ## Simple templates
 
-The default value if not set is `{{range .}}{{.Message}}{{println}}{{end}}`. The example below uses a template that also
-outputs timestamp and log level.
+The default template for simple notifications (used when `WATCHTOWER_NOTIFICATION_REPORT` is not set) is:
+
+```go
+{{- range $i, $e := . -}}
+{{- if $i}}{{- println -}}{{- end -}}
+{{- $msg := $e.Message -}}
+{{- if eq $msg "Found new image" -}}
+    Found new image: {{$e.Data.image}} ({{with $e.Data.new_id}}{{.}}{{else}}unknown{{end}})
+{{- else if eq $msg "Stopping container" -}}
+    Stopped stale container: {{$e.Data.container}} ({{with $e.Data.id}}{{.}}{{else}}unknown{{end}})
+{{- else if eq $msg "Started new container" -}}
+    Started new container: {{$e.Data.container}} ({{with $e.Data.new_id}}{{.}}{{else}}unknown{{end}})
+{{- else if eq $msg "Removing image" -}}
+    Removed stale image: {{with $e.Data.image_id}}{{.}}{{else}}unknown{{end}}
+{{- else if $e.Data -}}
+    {{$msg}} | {{range $k, $v := $e.Data -}}{{$k}}={{$v}} {{- end}}
+{{- else -}}
+    {{$msg}}
+{{- end -}}
+{{- end -}}
+```
+
+This template processes `info`-level log entries as they occur, formatting key update events in past tense with container and image details from `logrus` fields. It sends each event immediately in legacy mode, mimicking a step-by-step log.
+
+Example output for a single container update with `WATCHTOWER_CLEANUP` enabled:
+
+```text
+Found new image: /app:latest (bb7ba9626731)
+Stopped stale container: /app (4a2a8f7298a2)
+Started new container: /app (f52721881bed)
+Removed stale image: 78612560eb20
+```
+
+!!! note "Field Handling"
+    If expected fields (e.g., `new_id`, `id`, `image_id`) are missing, the template uses "unknown" as a fallback to ensure readable output (e.g., `Stopped stale container: /app (unknown)`).
 
 !!! tip "Custom date format"
-    If you want to adjust the date/time format it must show how the
-    [reference time](https://golang.org/pkg/time/#pkg-constants) (_Mon Jan 2 15:04:05 MST 2006_) would be displayed in your
-    custom format.  
-    i.e., The day of the year has to be 1, the month has to be 2 (february), the hour 3 (or 15 for 24h time) etc.
+    To include timestamps, modify the template with .Time.Format, e.g., {{.Time.Format "2006-01-02 15:04:05"}} {{$msg}}. The reference time format is Mon Jan 2 15:04:05 MST 2006, so adjust accordingly (e.g., day as 1, month as 2, hour as 3 or 15).
 
 !!! note "Skipping notifications"
-    To skip sending notifications that do not contain any information, you can wrap your template with `{{if .}}` and `{{end}}`.
+    To skip sending notifications that do not contain any information, you can wrap your template with `{{if .}}` and `{{end}}`. The default template does not skip empty messages in legacy mode, as it processes logs as they occur.
 
 Example:
 

internal/actions/update.go

@@ -384,6 +384,7 @@ func cleanupImages(client container.Client, imageIDs map[types.ImageID]bool) {
 		if err := client.RemoveImageByID(imageID); err != nil {
 			logrus.WithError(err).WithField("image_id", imageID).Warn("Failed to remove image")
 		} else {
+			// Log detailed removal message
 			logrus.WithField("image_id", imageID).Debug("Removed image")
 		}
 	}

pkg/container/container_source.go

@@ -174,6 +174,7 @@ func StopSourceContainer(
 
 	// Stop the container if it’s running.
 	if sourceContainer.IsRunning() {
+		// Log detailed stop message
 		clog.WithField("signal", signal).Info("Stopping container")
 
 		if err := api.ContainerKill(ctx, string(sourceContainer.ID()), signal); err != nil {
@@ -370,9 +371,9 @@ func getLegacyNetworkConfig(
 		}
 	}
 
-	// Warn if MAC preservation is desired but not possible
+	// Provide debug log message if MAC preservation is desired but not possible
 	if len(networks) > 0 {
-		clog.Warn("MAC addresses not preserved in legacy config")
+		clog.Debug("MAC addresses not preserved in legacy config")
 	}
 
 	return config

pkg/container/container_target.go

@@ -87,6 +87,7 @@ func StartTargetContainer(
 		return createdContainerID, fmt.Errorf("%w: %w", errStartContainerFailed, err)
 	}
 
+	// Log detailed start message
 	clog.WithField("new_id", createdContainerID.ShortID()).Info("Started new container")
 
 	return createdContainerID, nil

pkg/container/image.go

@@ -138,6 +138,7 @@ func (c imageClient) HasNewImage(
 		return false, currentImageID, nil
 	}
 
+	// Log full image name and ID
 	clog.WithField("new_id", newImageID.ShortID()).Info("Found new image")
 
 	return true, newImageID, nil

pkg/notifications/common_templates.go

@@ -1,7 +1,24 @@
 package notifications
 
 var commonTemplates = map[string]string{
-	`default-legacy`: "{{range .}}{{.Message}}{{println}}{{end}}",
+	"default-legacy": `
+{{- range $i, $e := . -}}
+{{- if $i}}{{- println -}}{{- end -}}
+{{- $msg := $e.Message -}}
+{{- if eq $msg "Found new image" -}}
+    Found new image: {{$e.Data.image}} ({{with $e.Data.new_id}}{{.}}{{else}}unknown{{end}})
+{{- else if eq $msg "Stopping container" -}}
+    Stopped stale container: {{$e.Data.container}} ({{with $e.Data.id}}{{.}}{{else}}unknown{{end}})
+{{- else if eq $msg "Started new container" -}}
+    Started new container: {{$e.Data.container}} ({{with $e.Data.new_id}}{{.}}{{else}}unknown{{end}})
+{{- else if eq $msg "Removing image" -}}
+    Removed stale image: {{with $e.Data.image_id}}{{.}}{{else}}unknown{{end}}
+{{- else if $e.Data -}}
+    {{$msg}} | {{range $k, $v := $e.Data -}}{{$k}}={{$v}} {{- end}}
+{{- else -}}
+    {{$msg}}
+{{- end -}}
+{{- end -}}`,
 
 	`default`: `
 {{- if .Report -}}

pkg/notifications/shoutrrr.go

@@ -182,6 +182,7 @@ func createNotifier(
 //   - notifier: Notifier instance.
 func sendNotifications(notifier *shoutrrrTypeNotifier) {
 	for msg := range notifier.messages {
+		LocalLog.WithField("message", msg).Debug("Sending notification")
 		time.Sleep(notifier.delay)
 		errs := notifier.Router.Send(msg, notifier.params)
 
@@ -223,7 +224,10 @@ func (n *shoutrrrTypeNotifier) buildMessage(data Data) (string, error) {
 		return "", fmt.Errorf("failed to execute template: %w", err)
 	}
 
-	return body.String(), nil
+	msg := body.String()
+	LocalLog.WithField("message", msg).Debug("Generated notification message")
+
+	return msg, nil
 }
 
 // sendEntries sends batched entries and optional report.
@@ -234,6 +238,10 @@ func (n *shoutrrrTypeNotifier) buildMessage(data Data) (string, error) {
 func (n *shoutrrrTypeNotifier) sendEntries(entries []*logrus.Entry, report types.Report) {
 	msg, err := n.buildMessage(Data{n.data, entries, report})
 
+	LocalLog.WithError(err).
+		WithFields(logrus.Fields{"message": msg}).
+		Debug("Preparing to send entries")
+
 	if msg == "" {
 		// Log in go func in case we entered from Fire to avoid stalling
 		go func() { // Avoid blocking if called from Fire.
@@ -244,8 +252,12 @@ func (n *shoutrrrTypeNotifier) sendEntries(entries []*logrus.Entry, report types
 			}
 		}()
 
+		LocalLog.Debug("Message empty, skipping send")
+
 		return
 	}
+
+	LocalLog.Debug("Queuing notification message")
 	n.messages <- msg
 }
 

pkg/notifications/shoutrrr_test.go

@@ -154,7 +154,7 @@ updt1 (mock/updt1:latest): Updated
 
 				s, err := shoutrrr.buildMessage(Data{Entries: entries})
 				gomega.Expect(err).NotTo(gomega.HaveOccurred())
-				gomega.Expect(s).To(gomega.Equal("foo bar\n"))
+				gomega.Expect(s).To(gomega.Equal("foo bar"))
 			})
 		})
 		ginkgo.When("given a valid custom template", func() {