Day 2: Structs, Methods, Interfaces – logsum
Goal: Build a
logspackage with your own types, methods and an interface and turn it intologsum, 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 – noimplements. - 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/logsExpected:
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
}
EOFThen 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 CombinedExpected:
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.logExpected:
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/probeExpected:
# 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 TopExpected:
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:
logsumis deliberately kept simple with a regex andtime.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.goExpected:
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.Scanneraborts on lines over 64 KB withtoken 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, notutilsorcommon).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.