buildmeta

README

Buildmeta

An easy way to set ldflags and retain build-time metadata that is useful for Go applications running in any environment.

Getting Started

There are already a few applications out there with canonical paths for build metadata, though none thus far is authoritative. This package takes the idea and extends it to include a CLI that knows how to set ldflags appropriately so that all your build needs is -ldflags "$(buildmeta ldflags)". There are additional options for outputting JSON metadata for e.g. static directories.

To use this, run go install github.com/andrewstuart/buildmeta/cmd/buildmeta@latest in terminal, and run buildmeta to validate output. You can also try go run github.com/andrewstuart/buildmeta/cmd/buildmeta which will both download and run this module.

go build -o app -ldflags "$(buildmeta ldflags)"

Documentation

Index

• Constants
• type DownstreamError
  • func (d *DownstreamError) Error() string
• type Info
  • func GenerateInfo(repoPath string) (*Info, error)
  • func GetInfo() Info
  • func (i Info) LDFlags() string
  • func (i Info) PrometheusCollector() prometheus.Collector
  • func (i Info) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (i Info) TagOrCommit() string
• type MetaChecker
  • func (g MetaChecker) Check() (err error)
• type MetaHandler
  • func Handler() *MetaHandler
  • func (rh *MetaHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

Examples

• Handler

Constants

const (
	BasePath  = "/-/"
	InfoPath  = "info"
	AlivePath = "alive"
	PingPath  = "ping"
	ReadyPath = "ready"
)

Well-known paths used by buildmeta

Types

type DownstreamError

type DownstreamError struct {
	StatusCode   int
	Root, Status string
	Body         interface{}
}

A DownstreamError is returned by the MetaChecker so that further details can be inspected in the output messages if it is json encoded.

func (*DownstreamError) Error

func (d *DownstreamError) Error() string

Error implements error

type Info

type Info struct {
	GitCommit      string `json:"commit"`
	GitCommitTime  string `json:"commitTime"`
	GitRepo        string `json:"gitRepo"`
	GitTag         string `json:"tag"`
	BuildTime      string `json:"buildTime"`
	GoBuildVersion string `json:"goBuildVersion,omitempty"`
	// contains filtered or unexported fields
}

Info is the type used by the buildmeta package to return build-time information.

func GenerateInfo

func GenerateInfo(repoPath string) (*Info, error)

GenerateInfo returns the *Info object per a given repoPath on the local filesystem. It does not yet work outside a local filesystem.

func GetInfo

func GetInfo() Info

GetInfo returns the Info object with the values that were set by ldflags during compilation.

func (Info) LDFlags

func (i Info) LDFlags() string

LDFlags returns the ldflags that match the variables in the biuldmeta package.

func (Info) PrometheusCollector

func (i Info) PrometheusCollector() prometheus.Collector

PrometheusCollector returns a prometheus collector that can be registered by applications using buildmeta in order to provide standardized prometheus metrics on current version and builds.

func (Info) ServeHTTP

func (i Info) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (Info) TagOrCommit

func (i Info) TagOrCommit() string

type MetaChecker

type MetaChecker struct {
	Root string
}

MetaChecker is a health.Checker implementation that just abstracts over a simple base endpoint, and attempts to contact the buildmeta readiness probe under the well-known buildmeta path.

func (MetaChecker) Check

func (g MetaChecker) Check() (err error)

Check implements health.Checker

type MetaHandler

type MetaHandler struct {
	Info         Info
	Alive, Ready *health.Registry
}

MetaHandler serves structured metadata for version control metadata, liveness, and readiness.

func Handler

func Handler() *MetaHandler

Handler returns a MetaHandler, which serves up version information and any registered health checks at given endpoints. Liveness and Readiness probes should be registered in Alive and Ready.

Example

package main

import (
	"database/sql"
	"fmt"
	"math/rand"
	"net/http"
	"time"

	health "astuart.co/go-healthcheck"
	"github.com/andrewstuart/buildmeta"
)

var db *sql.DB

func main() {
	h := buildmeta.Handler()

	h.Alive.Register("postgres", health.PeriodicChecker(health.CheckFunc(func() error {
		return db.Ping()
	}), time.Minute))

	h.Alive.Register("someservie", health.PeriodicChecker(buildmeta.MetaChecker{
		Root: "https://some-buildmeta-using-service.test.local:8443",
	}, time.Minute))

	h.Ready.Register("random", health.PeriodicThresholdChecker(health.CheckFunc(func() error {
		if rand.Int()%2 == 0 {
			// If we get 5 coin tosses in a minute then return not ready
			return fmt.Errorf("not ready")
		}
		return nil
	}), time.Minute, 5))

	http.Handle(buildmeta.BasePath, h)
	http.ListenAndServe("localhost:8080", nil)
}

func (*MetaHandler) ServeHTTP

func (rh *MetaHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

The MetaHandler implements http.ServeMux by serving both the info struct and health check information.