buildinfo

README

buildinfo

Package buildinfo provides basic building blocks and instructions to easily add build and release information to your app.

go get github.com/go-pogo/buildinfo

import "github.com/go-pogo/buildinfo"

Using ldflags

Declare build info variables in your main package:

package main

// this value is changed via ldflags when building a new release
var version string

func main() {
    bld, err := buildinfo.New(version)
}

Build your Go project and include the following ldflags:

go build -ldflags=" \
  -X main.version=`$(git describe --tags)` \
  main.go

Observability usage

When using a metrics scraper like Prometheus or OpenTelemetry, it is often a good idea to make the build information of your app available. Below example shows just how easy it is to create and register a collector with the build information as constant labels.

Prometheus metric collector

prometheus.MustRegister(prometheus.NewGaugeFunc(
    prometheus.GaugeOpts{
        Namespace:   "myapp",
        Name:        buildinfo.MetricName,
        Help:        buildinfo.MetricHelp,
        ConstLabels: bld.Map(),
    },
    func() float64 { return 1 },
))

OTEL resource

resource.Merge(
    resource.Default(),
    resource.NewSchemaless(
        semconv.ServiceName("myapp"),
        semconv.ServiceVersion(bld.Version()),
        attribute.String("vcs.revision", bld.Revision()),
        attribute.String("vcs.time", bld.Time().Format(time.RFC3339)),
    ),
)

Documentation

Additional detailed documentation is available at pkg.go.dev

Created with

License

Copyright © 2020-2025 Roel Schut. All rights reserved.

This project is governed by a BSD-style license that can be found in the LICENSE file.

Documentation

Overview

Package buildinfo provides basic building blocks and instructions to easily add build and release information to your app.

# Using ldflags Declare build info variables in your main package:

package main

// this value is changed via ldflags when building a new release
var version

func main() {
	bld, err := buildinfo.New(version)
}

Build your Go project and include the following ldflags:

go build -ldflags=" \
  -X main.version=`$(git describe --tags)` \
  main.go

# Prometheus metric collector When using a metrics scraper like Prometheus, it is often a good idea to make the build information of your app available. Below example shows just how easy it is to create and register a collector with the build information as constant labels.

prometheus.MustRegister(prometheus.NewGaugeFunc(
    prometheus.GaugeOpts{
        Namespace:   "myapp",
        Name:        buildinfo.MetricName,
        Help:        buildinfo.MetricHelp,
        ConstLabels: bld.Map(),
    },
    func() float64 { return 1 },
))

Index

• Constants
• Variables
• func HTTPHandler(bld *BuildInfo) http.Handler
• type BuildInfo
  • func New(altVersion string) (*BuildInfo, error)
  • func (bld *BuildInfo) GoVersion() string
  • func (bld *BuildInfo) Internal() *debug.BuildInfo
  • func (bld *BuildInfo) Map() map[string]string
  • func (bld *BuildInfo) MarshalJSON() ([]byte, error)
  • func (bld *BuildInfo) Module(name string) debug.Module
  • func (bld *BuildInfo) Name() string
  • func (bld *BuildInfo) Revision() string
  • func (bld *BuildInfo) Setting(key string) string
  • func (bld *BuildInfo) String() string
  • func (bld *BuildInfo) Time() time.Time
  • func (bld *BuildInfo) Version() string

Examples

• New

Constants

const (
	// ShortFlag is the default flag to print the current build information.
	ShortFlag = "v"
	// LongFlag is an alternative long version that may be used together with ShortFlag.
	LongFlag = "version"

	// MetricName is the default name for the metric (without namespace).
	MetricName = "buildinfo"
	// MetricHelp is the default help text to describe the metric.
	MetricHelp = "Metric with build information labels and a constant value of '1'."

	// PathPattern is the default path for a http handler.
	PathPattern = "/version"
)

const ErrNoBuildInfo = "no build information available"

Variables

var EmptyVersion = "0.0.0"

EmptyVersion is the default version string when no version is set.

Functions

func HTTPHandler

func HTTPHandler(bld *BuildInfo) http.Handler

HTTPHandler is the http.Handler that writes BuildInfo bld as a JSON response to the http response.

Types

type BuildInfo

type BuildInfo struct {

	// AltName is an alternative name for the release.
	AltName string
	// AltVersion is an alternative version of the release.
	AltVersion string
	// contains filtered or unexported fields
}

BuildInfo contains the relevant information of the current release's build version, revision and time.

func New

func New(altVersion string) (*BuildInfo, error)

New creates a new BuildInfo with the given altVersion string.

Example

bld, _ := New("1.2.3")
fmt.Println(bld.String())

Output:

1.2.3

func (*BuildInfo) GoVersion

func (bld *BuildInfo) GoVersion() string

GoVersion returns the Go runtime version used to make the current build.

func (*BuildInfo) Internal

func (bld *BuildInfo) Internal() *debug.BuildInfo

func (*BuildInfo) Map

func (bld *BuildInfo) Map() map[string]string

Map returns the build information as a map. Field names are lowercase. Empty fields are omitted.

func (*BuildInfo) MarshalJSON

func (bld *BuildInfo) MarshalJSON() ([]byte, error)

MarshalJSON returns valid JSON output. Empty fields within buildInfo are omitted.

func (*BuildInfo) Module

func (bld *BuildInfo) Module(name string) debug.Module

func (*BuildInfo) Name

func (bld *BuildInfo) Name() string

func (*BuildInfo) Revision

func (bld *BuildInfo) Revision() string

Revision is the (short) commit hash the release is build from.

func (*BuildInfo) Setting

func (bld *BuildInfo) Setting(key string) string

func (*BuildInfo) String

func (bld *BuildInfo) String() string

String returns the string representation of the build information. It always includes the release version. Other fields are omitted when empty. Examples:

• version only: `8.5.0`
• version and revision `8.5.0 (#fedcba)`
• version and date: `8.5.0 (2020-06-16 19:53)`
• all: `8.5.0 (#fedcba @ 2020-06-16 19:53)`

func (*BuildInfo) Time

func (bld *BuildInfo) Time() time.Time

Time of the commit the release was build.

func (*BuildInfo) Version

func (bld *BuildInfo) Version() string