chore: structured logging (#28)

Author: DeepSpace2

.github/workflows/reusable-unittests.yml

@@ -13,7 +13,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.24.5'
+          go-version: "1.25.4"
 
       - name: Run tests with coverage
         run: go test -coverprofile=coverage.out ./...

Dockerfile

@@ -1,4 +1,4 @@
-FROM golang:1.24.5-alpine AS builder
+FROM golang:1.25.4-alpine AS builder
 
 LABEL org.opencontainers.image.source=https://github.com/DeepSpace2/plugnpin
 

docs/index.md

@@ -52,6 +52,7 @@ See [Per Container Configuration ➔ Pi-Hole](#targetDomainLabel).
 
 | Variable {: style="width:35%" } | Description | Default {: style="width:10%" } |
 |---|---|---|
+| `DEBUG` | Set to `true` to enable DEBUG level logs | `false` |
 | `DOCKER_HOST` | The URL of a docker socket proxy. If set, you don't need to mount the docker socket as a volume. Querying containers must be allowed (typically done by setting the `CONTAINERS` environment variable to `1`). | *None* |
 | <div id="piHoleDisabledEnvVar"><a name="piholeDisabledEnvVar"></a>`PIHOLE_DISABLED`</div> | Set to `true` to disable Pi-Hole functionality | `false` |
 | `RUN_INTERVAL` | The interval at which to scan for new containers, in Go's [`time.ParseDuration`](<https://go.dev/pkg/time/#ParseDuration>){: target="_blank" } format. Set to `0` to run once and exit. | `1h` |

go.mod

@@ -1,45 +1,62 @@
 module github.com/deepspace2/plugnpin
 
-go 1.23.11
+go 1.25.4
 
 require (
 	github.com/caarlos0/env/v11 v11.3.1
 	github.com/docker/docker v28.3.2+incompatible
+	github.com/docker/go-connections v0.5.0
 	github.com/docker/go-sdk/client v0.1.0-alpha009
 	github.com/joho/godotenv v1.5.1
+	github.com/moby/moby/api v1.52.0
 	github.com/spf13/pflag v1.0.7
 	github.com/stretchr/testify v1.10.0
 )
 
 require (
 	github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect
 	github.com/Microsoft/go-winio v0.6.2 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/cenkalti/backoff/v5 v5.0.3 // indirect
 	github.com/containerd/errdefs v1.0.0 // indirect
 	github.com/containerd/errdefs/pkg v0.3.0 // indirect
+	github.com/containerd/fifo v1.1.0 // indirect
+	github.com/containerd/log v0.1.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/distribution/reference v0.6.0 // indirect
-	github.com/docker/go-connections v0.5.0 // indirect
+	github.com/docker/go-metrics v0.0.1 // indirect
 	github.com/docker/go-sdk/config v0.1.0-alpha009 // indirect
 	github.com/docker/go-sdk/context v0.1.0-alpha009 // indirect
 	github.com/docker/go-units v0.5.0 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/protobuf v1.5.0 // indirect
+	github.com/matttproud/golang_protobuf_extensions v1.0.1 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
+	github.com/moby/sys/atomicwriter v0.1.0 // indirect
 	github.com/moby/sys/sequential v0.6.0 // indirect
+	github.com/moby/sys/userns v0.1.0 // indirect
+	github.com/moby/term v0.5.2 // indirect
+	github.com/morikuni/aec v1.0.0 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.1 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/prometheus/client_golang v1.1.0 // indirect
+	github.com/prometheus/client_model v0.0.0-20190129233127-fd36f4220a90 // indirect
+	github.com/prometheus/common v0.6.0 // indirect
+	github.com/prometheus/procfs v0.0.3 // indirect
+	github.com/sirupsen/logrus v1.9.3 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
 	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0 // indirect
 	go.opentelemetry.io/otel v1.37.0 // indirect
 	go.opentelemetry.io/otel/metric v1.37.0 // indirect
 	go.opentelemetry.io/otel/trace v1.37.0 // indirect
 	golang.org/x/net v0.37.0 // indirect
 	golang.org/x/sys v0.33.0 // indirect
+	golang.org/x/time v0.11.0 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20250818200422-3122310a409c // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20250811230008-5f3141c8851a // indirect
 	google.golang.org/protobuf v1.36.7 // indirect

go.sum

@@ -2,7 +2,7 @@ package main
 
 import (
 	"context"
-	"log"
+	"fmt"
 	"os"
 	"os/signal"
 	"sync"
@@ -13,31 +13,41 @@ import (
 	"github.com/deepspace2/plugnpin/pkg/clients/npm"
 	"github.com/deepspace2/plugnpin/pkg/clients/pihole"
 	"github.com/deepspace2/plugnpin/pkg/config"
+	"github.com/deepspace2/plugnpin/pkg/logging"
 	"github.com/deepspace2/plugnpin/pkg/processor"
 )
 
+var log = logging.GetLogger()
+
 func shutdown(cancelCtx context.CancelFunc, wg *sync.WaitGroup) {
 	shutdownChan := make(chan os.Signal, 1)
 	signal.Notify(shutdownChan, syscall.SIGINT, syscall.SIGTERM)
 
 	<-shutdownChan
 
-	log.Println("Shutdown signal received, exiting gracefully.")
+	log.Info("Shutdown signal received, exiting gracefully.")
 	cancelCtx()
 	wg.Wait()
-	log.Println("Shutdown complete.")
+	log.Info("Shutdown complete.")
 }
 
 func main() {
 	cliFlags := cli.ParseFlags()
 
 	conf, err := config.GetEnvVars()
 	if err != nil {
-		log.Fatal(err)
+		log.Error("Failed to parse environment variables", "error", err)
+		os.Exit(1)
+	}
+
+	if conf.Debug {
+		logging.SetLevel(logging.DEBUG)
+	} else {
+		logging.SetLevel(logging.INFO)
 	}
 
 	if conf.RunInterval > 0 {
-		log.Printf("Will run every %v", conf.RunInterval)
+		log.Info(fmt.Sprintf("Will run every %v", conf.RunInterval))
 	}
 
 	var piholeClient *pihole.Client
@@ -48,27 +58,30 @@ func main() {
 			piholeClient = pihole.NewClient(conf.PiholeHost)
 			err = piholeClient.Login(conf.PiholePassword)
 			if err != nil {
-				log.Fatalf("ERROR failed to login to Pi-Hole: %v", err)
+				log.Error("Failed to login to Pi-Hole", "error", err)
+				os.Exit(1)
 			}
 		}
 
 		npmClient = npm.NewClient(conf.NpmHost, conf.NpmUsername, conf.NpmPassword)
 		err = npmClient.Login()
 		if err != nil {
-			log.Fatalf("ERROR failed to login to Nginx Proxy Manager: %v", err)
+			log.Error("Failed to login to Nginx Proxy Manager", "error", err)
+			os.Exit(1)
 		}
 	}
 
 	dockerClient, err := docker.NewClient()
 	if err != nil {
-		log.Fatalf("ERROR creating docker client: %v", err)
+		log.Error("Failed to create docker client", "error", err)
+		os.Exit(1)
 	}
 	defer dockerClient.Close()
 
 	proc := processor.New(dockerClient, piholeClient, npmClient, cliFlags.DryRun)
 
 	if conf.RunInterval == 0 {
-		log.Println("RUN_INTERVAL is 0, will run once")
+		log.Info("RUN_INTERVAL is 0, will run once")
 		proc.RunOnce()
 		return
 	}

main.go

@@ -3,19 +3,22 @@ package docker
 import (
 	"context"
 	"fmt"
-	"log"
 	"slices"
 	"strconv"
 	"strings"
 
-	"github.com/deepspace2/plugnpin/pkg/clients/npm"
-	"github.com/deepspace2/plugnpin/pkg/clients/pihole"
-	"github.com/deepspace2/plugnpin/pkg/errors"
 	"github.com/docker/docker/api/types/container"
 	"github.com/docker/docker/api/types/filters"
 	dockerSdk "github.com/docker/go-sdk/client"
+
+	"github.com/deepspace2/plugnpin/pkg/clients/npm"
+	"github.com/deepspace2/plugnpin/pkg/clients/pihole"
+	"github.com/deepspace2/plugnpin/pkg/errors"
+	"github.com/deepspace2/plugnpin/pkg/logging"
 )
 
+var log = logging.GetLogger()
+
 const (
 	ipLabel  = "plugNPiN.ip"
 	urlLabel = "plugNPiN.url"
@@ -49,7 +52,7 @@ func (d *Client) GetRelevantContainers() ([]container.Summary, error) {
 		f.Add("label", label)
 	}
 
-	log.Printf("Getting containers with labels: %v", strings.Join(labels, ", "))
+	log.Info(fmt.Sprintf("Getting containers with labels: %v", strings.Join(labels, ", ")))
 
 	return d.ContainerList(
 		context.Background(),

pkg/clients/docker/docker.go

@@ -2,7 +2,6 @@ package docker
 
 import (
 	"context"
-	"log"
 
 	"github.com/docker/docker/api/types/events"
 	"github.com/docker/docker/api/types/filters"
@@ -22,7 +21,7 @@ func Listen(ctx context.Context, handler func(events.Message)) error {
 	f.Add("event", ContainerEvent.Stop.String())
 	f.Add("event", ContainerEvent.Kill.String())
 
-	log.Println("Listening for Docker events...")
+	log.Info("Listening for Docker events...")
 
 	messages, errs := c.Events(ctx, events.ListOptions{
 		Filters: f,
@@ -31,13 +30,13 @@ func Listen(ctx context.Context, handler func(events.Message)) error {
 	for {
 		select {
 		case <-ctx.Done():
-			log.Printf("Stopping stream of Docker events")
+			log.Info("Stopping stream of Docker events")
 			return ctx.Err()
 		case event := <-messages:
 			handler(event)
 		case err := <-errs:
 			if err != nil {
-				log.Printf("Error receiving event: %v", err)
+				log.Error("Failed to receive event", "error", err)
 			}
 			return err
 		}

pkg/clients/docker/events.go

@@ -4,13 +4,15 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"log"
 	"net/http"
 	"net/url"
 
 	"github.com/deepspace2/plugnpin/pkg/clients"
+	"github.com/deepspace2/plugnpin/pkg/logging"
 )
 
+var log = logging.GetLogger()
+
 type Client struct {
 	http.Client
 	baseURL  string
@@ -86,7 +88,7 @@ func (n *Client) getProxyHosts() (map[string]int, error) {
 }
 
 func (n *Client) refreshToken() error {
-	log.Println("Refreshing Nginx Proxy Manager token")
+	log.Info("Refreshing Nginx Proxy Manager token")
 	return n.Login()
 }
 

pkg/clients/npm/npm.go

@@ -2,14 +2,18 @@ package pihole
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
-	"log"
 	"net/http"
+	"os"
 	"strings"
 
 	"github.com/deepspace2/plugnpin/pkg/clients"
+	"github.com/deepspace2/plugnpin/pkg/logging"
 )
 
+var log = logging.GetLogger()
+
 type Client struct {
 	http.Client
 	baseURL string
@@ -39,7 +43,7 @@ func (p *Client) Login(password string) error {
 	json.Unmarshal([]byte(loginResponseString), &resp)
 
 	if statusCode >= 400 || resp.Session.Sid == "" {
-		return fmt.Errorf(resp.Session.Message)
+		return errors.New(resp.Session.Message)
 	}
 
 	p.sid = resp.Session.Sid
@@ -63,8 +67,8 @@ func dnsRecordToRaw(domain DomainName, ip IP) string {
 
 func (p *Client) getDnsRecords() (DnsRecords, error) {
 	if p.sid == "" {
-		// TODO:
-		log.Fatal("no SID")
+		log.Error("Missing Pi-Hole session ID")
+		os.Exit(1)
 	}
 	headers["X-FTL-SID"] = p.sid
 	configResponseString, _, err := clients.Get(&p.Client, p.baseURL+"/config", headers)
@@ -113,8 +117,8 @@ func (p *Client) AddDnsRecord(domain, ip string) error {
 	}
 
 	if p.sid == "" {
-		// TODO:
-		log.Fatal("no SID")
+		log.Error("Missing Pi-Hole session ID")
+		os.Exit(1)
 	}
 	headers["X-FTL-SID"] = p.sid
 	resp, statusCode, err := clients.Patch(&p.Client, p.baseURL+"/config", headers, string(payloadString))
@@ -158,8 +162,8 @@ func (p *Client) DeleteDnsRecord(domain string) error {
 	}
 
 	if p.sid == "" {
-		// TODO:
-		log.Fatal("no SID")
+		log.Error("Missing Pi-Hole session ID")
+		os.Exit(1)
 	}
 	headers["X-FTL-SID"] = p.sid
 	resp, statusCode, err := clients.Patch(&p.Client, p.baseURL+"/config", headers, string(payloadString))
@@ -192,8 +196,8 @@ func cNameRecordToRaw(domain DomainName, target Target) string {
 
 func (p *Client) getCNameRecords() (CNameRecords, error) {
 	if p.sid == "" {
-		// TODO:
-		log.Fatal("no SID")
+		log.Error("Missing Pi-Hole session ID")
+		os.Exit(1)
 	}
 	headers["X-FTL-SID"] = p.sid
 	configResponseString, _, err := clients.Get(&p.Client, p.baseURL+"/config", headers)
@@ -242,8 +246,8 @@ func (p *Client) AddCNameRecord(domain, target string) error {
 	}
 
 	if p.sid == "" {
-		// TODO:
-		log.Fatal("no SID")
+		log.Error("Missing Pi-Hole session ID")
+		os.Exit(1)
 	}
 	headers["X-FTL-SID"] = p.sid
 	resp, statusCode, err := clients.Patch(&p.Client, p.baseURL+"/config", headers, string(payloadString))
@@ -287,8 +291,8 @@ func (p *Client) DeleteCNameRecord(domain, target string) error {
 	}
 
 	if p.sid == "" {
-		// TODO:
-		log.Fatal("no SID")
+		log.Error("Missing Pi-Hole session ID")
+		os.Exit(1)
 	}
 	headers["X-FTL-SID"] = p.sid
 	resp, statusCode, err := clients.Patch(&p.Client, p.baseURL+"/config", headers, string(payloadString))