Build Information

I include build info so there's never ambiguity about which version produced an error, even days or weeks later.

2024-06-10T12:34:56Z level=ERROR msg="Failed to connect to database" version="1.2.3"

Nobody reading this log will be left wondering "Was that before or after we added feature X?" or "Does that code include Bob's fix for caching?"

Build info also makes trend analysis easier. Many logging services do this automatically, and some integrate with your VCS (such as GitHub) to link errors to specific commits.

If you use canary deployments, rolling deployments, or any strategy that runs multiple app versions at once, build information is a lifesaver.

So we need a way to get build information into our logs at runtime... and we don't want to hardcode it. Someone will forget to update it, and wrong build information is worse than none at all!

The go build command supports -buildvcs, which stamps VCS metadata into the binary so you can read it at runtime with runtime/debug.ReadBuildInfo. It's convenient, but has tradeoffs:

• It requires VCS metadata (like .git) at build time, which is often missing in container builds.
• It only exposes limited fields (revision + build time).

So I recommend an alternate method...

Using ldflags for Build Info

go build also supports -ldflags, which lets the linker set package variables at build time.

To use this, create placeholder string variables in your code. You can put them anywhere, but I prefer a dedicated build package that only contains these variables, defaulting to "unknown":

package build

// default build-time variables
var (
	GitSHA    = "unknown"
	BuildTime = "unknown"
)

Then, we can set them in the logger:

logger = logger.With(
	slog.String("git_sha", build.GitSHA),
	slog.String("build_time", build.BuildTime),
)

At build time, inject the real values with -ldflags:

go build -ldflags "-X my/package/build.GitSHA=$(git rev-parse HEAD) -X my/package/build.BuildTime=$(date -u '+%Y-%m-%dT%H:%M:%SZ')"

Attach build metadata to every log entry.

1. Create a new package internal/build with a build.go file exporting GitSHA and BuildTime string variables, both defaulting to "unknown".
2. In your main package, immediately after initializing your logger, add these two fields using Logger.With:

   logger = logger.With(
   	slog.String("git_sha", build.GitSHA),
   	slog.String("build_time", build.BuildTime),
   )
   

3. Build your app using -ldflags to inject values at link time:

   go build \
     -ldflags "-X boot.dev/linko/internal/build.GitSHA=$(git rev-parse HEAD) -X boot.dev/linko/internal/build.BuildTime=$(date -u '+%Y-%m-%dT%H:%M:%SZ')" \
     -o linko
   

   The boot.dev/linko/internal/build part of the -X flag is the full import path to the variable you want to set. Yours may be a bit different from mine!

4. Run the prebuilt app with the log file path set:

   LINKO_LOG_FILE=linko.access.log ./linko
   

Run and submit the CLI tests from the root of the Linko repo.