Project challenges / verified progress
Beacon: turn a program into a service

The engineering notebook

Write machine-readable logs

How do logs help during an incident without leaking what they should not?

Loading Vault account...
Phase 3 — API and observability

Step 01 of 06

Understand the idea

Logs help you understand what a service was doing. Structured logs store details such as target, status, and request ID in separate fields, so you can search and filter them more easily.

ONE EVENT MANY READERSslog recordmessage plus attrsTerminaltext handlerlocalCollectorJSON handlerprodIncidentfilter by fieldsfast
The same logging call can feed a text handler during development and JSON in production. The value is in stable attributes: request ID, target, route, status, duration.
Step 01

Key technical ideas

Attributes beat string parsing

logger.Info("check complete", "target", target, "latencyMs", 82) records fields separately from the message. A log system can filter latencyMs > 1000 without regex. Humans still get a sentence. Machines get columns. Everyone is less annoyed.

Levels are a budget

Debug is for development detail, info for normal lifecycle events, warn for degraded but handled conditions, and error for failed operations that need attention. If every slow check is error, real errors drown. If storage failure is info, no one sees it. Levels are not decoration.

Correlation IDs join the path

A request ID generated at the HTTP edge should appear in every log produced while handling that request. It lets an operator follow one failing call across middleware, handler and store. Use a header if supplied by trusted infrastructure; otherwise generate one.

Some data must never enter logs

Secrets, bearer tokens, cookies, private keys and personal data do not belong in logs. Logs spread: terminals, files, collectors, tickets, screenshots. Beacon does not use credentials in this course, but the habit matters before course five introduces cloud identity.

One slog record
package main

import (
	"log/slog"
	"os"
)

func main() {
	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
	logger.Info("check complete", "target", "https://example.com", "latencyMs", 82)
}

The output is one JSON object with stable keys. Beacon will add request IDs and route names the same way.

Text or JSON handler

HandlerGood forTrade-off

Text

Local reading

Harder to query

JSON

Collectors

Noisier by eye

Both

Same call sites

Configured at startup

Technical terms used at work

  • Attribute — A key-value pair attached to a log record.

  • Correlation ID — An identifier repeated across logs for one request or unit of work.

  • PII — Personally identifiable information, which should not be casually logged.