Skip to content
Hands-on IT IT Drills

Day 2: Structs, Methods, Interfaces – logsum

Goal: Build a logs package with your own types, methods and an interface and turn it into logsum, which analyzes access logs in two formats · Duration: approx. 120 min · Prerequisite: Day 1

Briefing

  • A struct bundles fields into a type; there are no classes and no inheritance.
  • Methods attach to a type via a receiver: func (s *Summary) Add(e Entry). Pointer receivers may change the value.
  • An interface describes behavior (Parse(line string) (Entry, error)). A type satisfies it implicitly as soon as it has the methods – no implements.
  • A package is a folder. Capitalized = exported, lowercase = private. Only your own module may import internal/.
  • Rule of thumb: functions accept interfaces (io.Reader, io.Writer) and return concrete types.
 cmd/logsum/main.go                    internal/logs
 ┌──────────────────┐                  ┌────────────────────────────────┐
 │ -format json     │ ── Parser ─────► │ Combined{} / JSON{}  .Parse()  │
 │ -top 3           │ ── io.Reader ──► │ Read() ──► *Summary            │
 │ file or stdin    │                  │   .Add() .TopPaths() .ErrorRate│
 │ os.Stdout        │ ◄─ io.Writer ─── │   .Report(w, top)              │
 └──────────────────┘                  └────────────────────────────────┘

Drill 1: Module and test data

mkdir -p ~/go-lab/tag02-logsum && cd ~/go-lab/tag02-logsum
go mod init example.com/logsum
mkdir -p cmd/logsum internal/logs testdata
cat > testdata/access.log <<'EOF'
10.0.0.1 - - [10/Oct/2026:08:00:01 +0200] "GET / HTTP/1.1" 200 512 "-" "curl/8.7"
10.0.0.2 - - [10/Oct/2026:08:00:03 +0200] "GET /api/orders HTTP/1.1" 200 2048 "-" "k6"
10.0.0.2 - - [10/Oct/2026:08:00:04 +0200] "POST /api/orders HTTP/1.1" 201 64 "-" "k6"
10.0.0.3 - - [10/Oct/2026:08:01:10 +0200] "GET /api/orders HTTP/1.1" 200 2048 "-" "k6"
10.0.0.1 - - [10/Oct/2026:08:01:12 +0200] "GET /favicon.ico HTTP/1.1" 404 0 "-" "Safari"
10.0.0.4 - - [10/Oct/2026:08:02:00 +0200] "GET /old HTTP/1.1" 301 - "-" "curl/8.7"
das ist keine Logzeile
10.0.0.3 - - [10/Oct/2026:08:02:30 +0200] "GET /api/users HTTP/1.1" 500 128 "-" "k6"
10.0.0.2 - - [10/Oct/2026:08:03:45 +0200] "GET /api/orders HTTP/1.1" 200 2048 "-" "k6"
10.0.0.5 - - [10/Oct/2026:08:04:13 +0200] "GET /admin HTTP/1.1" 403 256 "-" "nmap"
10.0.0.3 - - [10/Oct/2026:08:04:20 +0200] "GET /api/users HTTP/1.1" 502 0 "-" "k6"
EOF
cat > testdata/access.jsonl <<'EOF'
{"ts":"2026-10-10T07:00:00Z","ip":"10.0.0.7","path":"/healthz","status":200,"bytes":2}
{"ts":"2026-10-10T07:00:05Z","ip":"10.0.0.7","path":"/healthz","status":200,"bytes":2}
{"ts":"2026-10-10T07:00:09Z","ip":"10.0.0.8","path":"/api/orders","status":503}
{"ts":"kaputt"}
EOF
wc -l testdata/*

Expected:

go: creating new go.mod: module example.com/logsum
       4 testdata/access.jsonl
      11 testdata/access.log
      15 total

Two formats, one broken line each (“das ist keine Logzeile” means “this is not a log line”, “kaputt” means “broken”) – a good tool has to cope with that. testdata/ is a special folder: go build ignores it, and tests (Day 4) find their inputs in it.

Save your progress? Sign up for free

Drill 2: A type and an interface

cat > internal/logs/entry.go <<'EOF'
// Package logs liest Zugriffslogs und fasst sie zusammen.
package logs

import "time"

// Entry is a parsed log line.
type Entry struct {
    IP     string
    Time   time.Time
    Method string
    Path   string
    Status int
    Bytes  int64
}

// Parser turns a line into an Entry. Every log format implements it.
type Parser interface {
    Parse(line string) (Entry, error)
}
EOF
go doc ./internal/logs

Expected:

package logs // import "example.com/logsum/internal/logs"

Package logs liest Zugriffslogs und fasst sie zusammen.

type Entry struct{ ... }
type Parser interface{ ... }

Why? The comment directly above package and above every exported name is the documentation – go doc, gopls and pkg.go.dev display it (here: “Package logs reads access logs and summarizes them.”). The interface is deliberately small: one method. Small interfaces are easy to implement and easy to replace in tests.

Save your progress? Sign up for free

Drill 3: Two implementations

First the classic Combined Log Format of nginx and Apache:

cat > internal/logs/combined.go <<'EOF'
package logs

import (
    "fmt"
    "regexp"
    "strconv"
    "time"
)

// combinedRe is lowercase, so it is visible only in package logs.
var combinedRe = regexp.MustCompile(
    `^(\S+) \S+ \S+ \[([^\]]+)\] "(\S+) (\S+)[^"]*" (\d{3}) (\d+|-)`)

const combinedTime = "02/Jan/2006:15:04:05 -0700"

// Combined liest das Combined Log Format von nginx und Apache.
type Combined struct{}

// The compiler checks: Combined satisfies Parser.
var _ Parser = Combined{}

// Parse implements Parser.
func (Combined) Parse(line string) (Entry, error) {
    m := combinedRe.FindStringSubmatch(line)
    if m == nil {
        return Entry{}, fmt.Errorf("kein Combined-Format: %q", line)
    }
    t, err := time.Parse(combinedTime, m[2])
    if err != nil {
        return Entry{}, err
    }
    status, _ := strconv.Atoi(m[5]) // the regex guarantees three digits
    var size int64
    if m[6] != "-" {
        size, _ = strconv.ParseInt(m[6], 10, 64)
    }
    return Entry{
        IP: m[1], Time: t, Method: m[3], Path: m[4],
        Status: status, Bytes: size,
    }, nil
}
EOF

Then JSON logs, one line per request:

cat > internal/logs/json.go <<'EOF'
package logs

import (
    "encoding/json"
    "fmt"
    "time"
)

// JSON reads one JSON object per line (e.g. nginx with escape=json).
type JSON struct{}

var _ Parser = JSON{}

// jsonLine describes the format; the tags map JSON keys to fields.
type jsonLine struct {
    Time   time.Time `json:"ts"`
    IP     string    `json:"ip"`
    Method string    `json:"method"`
    Path   string    `json:"path"`
    Status int       `json:"status"`
    Bytes  int64     `json:"bytes"`
}

// Parse implements Parser.
func (JSON) Parse(line string) (Entry, error) {
    var j jsonLine
    if err := json.Unmarshal([]byte(line), &j); err != nil {
        return Entry{}, err
    }
    if j.Path == "" || j.Status == 0 {
        return Entry{}, fmt.Errorf("path oder status fehlt: %q", line)
    }
    return Entry{
        IP: j.IP, Time: j.Time, Method: j.Method, Path: j.Path,
        Status: j.Status, Bytes: j.Bytes,
    }, nil
}
EOF
go vet ./... && go doc ./internal/logs Combined

Expected:

package logs // import "example.com/logsum/internal/logs"

type Combined struct{}
    Combined liest das Combined Log Format von nginx und Apache.

func (Combined) Parse(line string) (Entry, error)

Why? Combined and JSON are empty structs – they need no state, only the method. var _ Parser = Combined{} costs nothing at runtime but makes the compiler complain immediately if the signature doesn’t match. Struct tags like `json:"ts"` tell encoding/json which key belongs in which field (more on Day 6). The time format 02/Jan/2006:15:04:05 -0700 is not a typo: Go describes layouts using the reference date January 2, 2006, 15:04:05.

Save your progress? Sign up for free

Drill 4: Summary with methods

cat > internal/logs/summary.go <<'EOF'
package logs

import (
    "bufio"
    "cmp"
    "fmt"
    "io"
    "slices"
    "strings"
    "time"
)

// Summary collects metrics across many entries.
type Summary struct {
    Lines    int // lines read
    Bad      int // unreadable lines
    Bytes    int64
    First    time.Time
    Last     time.Time
    ByStatus map[int]int    // 200 -> 17
    ByPath   map[string]int // "/api" -> 4
}

// PathCount is an entry of the top list.
type PathCount struct {
    Path string
    N    int
}

// NewSummary returns a Summary with initialized maps.
func NewSummary() *Summary {
    return &Summary{ByStatus: map[int]int{}, ByPath: map[string]int{}}
}

// Read parses every line from r with p and counts it into a new Summary.
func Read(r io.Reader, p Parser) (*Summary, error) {
    s := NewSummary()
    sc := bufio.NewScanner(r)
    for sc.Scan() {
        s.Lines++
        e, err := p.Parse(sc.Text())
        if err != nil {
            s.Bad++
            continue
        }
        s.Add(e)
    }
    return s, sc.Err()
}

// Add counts e. Pointer receiver, because Add modifies the Summary.
func (s *Summary) Add(e Entry) {
    s.Bytes += e.Bytes
    s.ByStatus[e.Status]++
    s.ByPath[e.Path]++
    if s.First.IsZero() || e.Time.Before(s.First) {
        s.First = e.Time
    }
    if e.Time.After(s.Last) {
        s.Last = e.Time
    }
}

// Requests is the number of readable lines.
func (s *Summary) Requests() int { return s.Lines - s.Bad }

// ErrorRate returns the share of 5xx responses in percent.
func (s *Summary) ErrorRate() float64 {
    if s.Requests() == 0 {
        return 0
    }
    n := 0
    for code, k := range s.ByStatus {
        if code >= 500 {
            n += k
        }
    }
    return 100 * float64(n) / float64(s.Requests())
}

// TopPaths returns the n most frequent paths.
func (s *Summary) TopPaths(n int) []PathCount {
    list := make([]PathCount, 0, len(s.ByPath))
    for p, k := range s.ByPath {
        list = append(list, PathCount{p, k})
    }
    slices.SortFunc(list, func(a, b PathCount) int {
        return cmp.Or(cmp.Compare(b.N, a.N), cmp.Compare(a.Path, b.Path))
    })
    return list[:min(n, len(list))]
}

// Report writes an overview to w – terminal, file or buffer.
func (s *Summary) Report(w io.Writer, top int) error {
    var b strings.Builder // collect, then write once
    fmt.Fprintf(&b, "Requests:   %d (%d Zeilen unlesbar)\n", s.Requests(), s.Bad)
    if s.Requests() > 0 {
        const layout = "2006-01-02 15:04:05"
        fmt.Fprintf(&b, "Zeitraum:   %s bis %s\n",
            s.First.Format(layout), s.Last.Format(layout))
        fmt.Fprintf(&b, "Bytes:      %d\n", s.Bytes)
        b.WriteString("Status:    ")
        for _, class := range []int{1, 2, 3, 4, 5} {
            n := 0
            for code, k := range s.ByStatus {
                if code/100 == class {
                    n += k
                }
            }
            if n > 0 {
                fmt.Fprintf(&b, " %dxx=%d", class, n)
            }
        }
        fmt.Fprintf(&b, "\n5xx-Quote:  %.1f %%\n", s.ErrorRate())
        fmt.Fprintf(&b, "Top %d Pfade:\n", top)
        for _, pc := range s.TopPaths(top) {
            fmt.Fprintf(&b, "%8d  %s\n", pc.N, pc.Path)
        }
    }
    _, err := io.WriteString(w, b.String())
    return err
}
EOF
go vet ./...

Expected: no output.

Why like this?

Element What it shows
NewSummary() Constructor convention: maps must be created with make or {}
func (s *Summary) Add Pointer receiver: changes the caller’s Summary
Read(r io.Reader, p Parser) accepts two interfaces – file, stdin, test string, any format
Report(w io.Writer, …) error writes anywhere; write errors are returned

cmp.Or takes the first value that is not 0: first by frequency, on a tie by path. min has been built in since Go 1.21.

Save your progress? Sign up for free

Drill 5: main – the interface in action

cat > cmd/logsum/main.go <<'EOF'
// logsum summarizes an access log: status, error rate, top paths.
// Day 2 from "Go hands-on".
package main

import (
    "flag"
    "fmt"
    "io"
    "os"

    "example.com/logsum/internal/logs"
)

func main() {
    format := flag.String("format", "combined", "Logformat: combined oder json")
    top := flag.Int("top", 3, "Anzahl der Top-Pfade")
    flag.Parse()

    // The interface makes the formats interchangeable.
    parsers := map[string]logs.Parser{
        "combined": logs.Combined{},
        "json":     logs.JSON{},
    }
    p, ok := parsers[*format]
    if !ok {
        fmt.Fprintf(os.Stderr, "logsum: unbekanntes Format %q\n", *format)
        os.Exit(2)
    }

    var in io.Reader = os.Stdin
    if flag.NArg() > 0 {
        f, err := os.Open(flag.Arg(0))
        if err != nil {
            fmt.Fprintln(os.Stderr, "logsum:", err)
            os.Exit(1)
        }
        defer f.Close() //nolint:errcheck // read only
        in = f
    }

    s, err := logs.Read(in, p)
    if err != nil {
        fmt.Fprintln(os.Stderr, "logsum:", err)
        os.Exit(1)
    }
    if err := s.Report(os.Stdout, *top); err != nil {
        fmt.Fprintln(os.Stderr, "logsum:", err)
        os.Exit(1)
    }
}
EOF
go build -o bin/logsum ./cmd/logsum
./bin/logsum testdata/access.log

Expected:

Requests:   10 (1 Zeilen unlesbar)
Zeitraum:   2026-10-10 08:00:01 bis 2026-10-10 08:04:20
Bytes:      7104
Status:     2xx=5 3xx=1 4xx=2 5xx=2
5xx-Quote:  20.0 %
Top 3 Pfade:
       4  /api/orders
       2  /api/users
       1  /

Why? main knows only logs.Parser – which concrete type is behind it is decided by the map at runtime. var in io.Reader = os.Stdin is replaced by an *os.File when needed; both satisfy io.Reader. The broken line ends up in Bad instead of aborting the tool. (The report labels are German: “Zeilen unlesbar” = lines unreadable, “Zeitraum” = time range, “Quote” = rate, “Pfade” = paths.)

Save your progress? Sign up for free

Drill 6: Second format, same code

./bin/logsum -format json -top 2 testdata/access.jsonl
cat testdata/access.log | ./bin/logsum -top 1 | tail -2
./bin/logsum -format xml; echo "exit=$?"

Expected:

Requests:   3 (1 Zeilen unlesbar)
Zeitraum:   2026-10-10 07:00:00 bis 2026-10-10 07:00:09
Bytes:      4
Status:     2xx=2 5xx=1
5xx-Quote:  33.3 %
Top 2 Pfade:
       2  /healthz
       1  /api/orders
Top 1 Pfade:
       4  /api/orders
logsum: unbekanntes Format "xml"
exit=2

Why? Read, Summary and Report have not changed – only the parser. That is exactly what interfaces are for: a third format (Traefik, CloudFront, Envoy) is a new file with a Parse method.

Save your progress? Sign up for free

Drill 7: Test visibility

The compiler shows you fastest what “exported” means. A throwaway program in the same module:

mkdir -p cmd/probe
cat > cmd/probe/main.go <<'EOF'
package main

import (
    "fmt"

    "example.com/logsum/internal/logs"
)

func main() {
    var p logs.Parser = logs.JSON{}
    fmt.Printf("%T\n", p)
    fmt.Println(logs.combinedRe)
}
EOF
go build ./cmd/probe
perl -ni -e 'print unless /combinedRe/' cmd/probe/main.go
go run ./cmd/probe
rm -r cmd/probe

Expected:

# example.com/logsum/cmd/probe
cmd/probe/main.go:12:19: undefined: logs.combinedRe
logs.JSON

Why? combinedRe is lowercase and therefore invisible outside logs – so nobody can swap the regex from the outside. %T shows the dynamic type behind an interface variable. A foreign module could not import example.com/logsum/internal/logs at all: internal/ locks out everything outside example.com/logsum.

Save your progress? Sign up for free

Drill 8: The tool is done

cd ~/go-lab/tag02-logsum
gofmt -l . && go vet ./... && ~/go-lab/bin/lint run ./...
go build -o bin/logsum ./cmd/logsum
./bin/logsum -h
./bin/logsum -top 2 testdata/access.log | grep -A2 Top

Expected:

0 issues.
Usage of ./bin/logsum:
  -format string
        Logformat: combined oder json (default "combined")
  -top int
        Anzahl der Top-Pfade (default 3)
Top 2 Pfade:
       4  /api/orders
       2  /api/users

Your module:

tag02-logsum/
├── cmd/logsum/main.go        flags, file/stdin, choose parser
├── internal/logs/
│   ├── entry.go              Entry, Parser
│   ├── combined.go           parser for nginx/Apache
│   ├── json.go               parser for JSON lines
│   └── summary.go            Summary, Read, Report
├── testdata/access.log, access.jsonl
└── go.mod

Tip: logsum is deliberately kept simple with a regex and time.Parse. On Day 13 you make it ten times faster with benchmarks and pprof.

Save your progress? Sign up for free

Checkpoint

#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
cd ~/go-lab/tag02-logsum
check "gofmt sauber" "test -z \"\$(gofmt -l .)\""
check "go vet" "go vet ./..."
check "golangci-lint" "~/go-lab/bin/lint run ./..."
check "Combined: 10 Requests" \
  "./bin/logsum testdata/access.log | grep -q '^Requests:   10 '"
check "JSON: 5xx-Quote 33.3 %" \
  "./bin/logsum -format json testdata/access.jsonl | grep -q '33.3 %'"
check "Exit 2 bei falschem Format" "./bin/logsum -format xml; test \$? -eq 2"
check "Paket dokumentiert" "go doc ./internal/logs | grep -q 'Package logs'"

Expected:

✔ gofmt sauber
✔ go vet
✔ golangci-lint
✔ Combined: 10 Requests
✔ JSON: 5xx-Quote 33.3 %
✔ Exit 2 bei falschem Format
✔ Paket dokumentiert

Challenge

A colleague “simplifies” Add to a value receiver: func (s Summary) Add(e Entry). The code compiles, go vet stays silent. Predict which lines of the report go wrong – and why not all of them.

Hint: A value receiver gets a copy of the struct. What actually gets copied with a map?

Solution

perl -pi -e 's/func \(s \*Summary\) Add/func (s Summary) Add/' internal/logs/summary.go
go vet ./... && go run ./cmd/logsum testdata/access.log | head -4
~/go-lab/bin/lint run ./... 2>&1 | grep -o 'SA4005: .*'
perl -pi -e 's/func \(s Summary\) Add/func (s *Summary) Add/' internal/logs/summary.go

Expected:

Requests:   10 (1 Zeilen unlesbar)
Zeitraum:   0001-01-01 00:00:00 bis 0001-01-01 00:00:00
Bytes:      0
Status:     2xx=5 3xx=1 4xx=2 5xx=2
SA4005: ineffective assignment to field Summary.Bytes (staticcheck)
SA4005: ineffective assignment to field Summary.First (staticcheck)
SA4005: ineffective assignment to field Summary.Last (staticcheck)

Bytes, First and Last end up in the copy and disappear with it – hence the zero values (0001-01-01 is the zero value of time.Time). The status codes are still right: the copy contains the same map reference, so Add writes into the same map. Exactly this half effect makes the bug so treacherous. go vet doesn’t find it, staticcheck in the linter does. Rule: if a method changes the value, it gets a pointer receiver – and then so do all methods of the type, to keep it consistent.

Save your progress? Sign up for free

Enterprise Note

  • bufio.Scanner aborts on lines over 64 KB with token too long – realistic with JSON logs containing stack traces. Remedy: sc.Buffer(make([]byte, 0, 1<<20), 10<<20).
  • Logs contain personal data (IP addresses, user IDs). Run analyses only on approved data and pass on results without raw IPs (GDPR).
  • Package boundaries: one package per responsibility (logs, not utils or common). internal/ protects you from other teams coupling themselves to half-finished APIs.
  • For real log pipelines there are Loki, Vector or Fluent Bit – a tool of your own pays off for quick analyses, ad-hoc incidents and CI checks.