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
func main() {
bld := buildinfo.New(version)
}
Build your Go project and include the following ldflags:
go build -ldflags=" \
-X main.version=`$(git describe --tags)` \
main.go
Using an embedded file
package main
import (
_ "embed"
"encoding/json"
"github.com/go-pogo/buildinfo"
)
//go:embed buildinfo.json
var buildInfo []byte
func main() {
var bld buildinfo.BuildInfo
if err := json.Unmarshal(buildInfo, &bld); err != nil {
panic(err)
}
}
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-2024 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 := buildinfo.New(version)
}
Build your Go project and include the following ldflags:
go build -ldflags=" \ -X main.version=`$(git describe --tags)` \ main.go
Using an embedded file ¶
package main
import _ "embed"
//go:embed buildinfo.json
var buildInfo []byte
func main() {
var bld buildinfo.BuildInfo
if err := json.Unmarshal(buildInfo, &bld); err != nil {
panic(err)
}
}
# 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 ¶
Examples ¶
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'." // Route is the default path for a http handler. Route = "/version" )
Variables ¶
var EmptyVersion = "0.0.0"
EmptyVersion is the default version string when no version is set.
Functions ¶
func HttpHandler ¶ added in v0.3.0
HttpHandler is the http.Handler that writes BuildInfo bld as a json response to the received request.
Types ¶
type BuildInfo ¶
type BuildInfo struct {
// Version of the release.
Version string
// Revision is the (short) commit hash the release is build from.
Revision string
// Time of the commit the release was build.
Time time.Time
// Extra additional information to show.
Extra map[string]string
// contains filtered or unexported fields
}
BuildInfo contains the relevant information of the current release's build version, revision and time.
func New ¶ added in v0.3.0
New creates a new BuildInfo with the given version string.
Example ¶
fmt.Println(New("1.2.3").String())
Output: 1.2.3
func OpenFS ¶ added in v0.5.0
OpenFS opens file from fsys. It then reads and decodes the file's contents using Read.
func Read ¶ added in v0.5.0
Read reads from io.Reader r and json unmarshals it's content into a new BuildInfo.
Example ¶
buf := bytes.NewBufferString(`{"version":"1.2.3","something":"else"}`)
bld, err := Read(buf)
if err != nil {
panic(err)
}
fmt.Printf("version=%s, something=%s\n", bld.Version, bld.Extra["something"])
Output: version=1.2.3, something=else
func (*BuildInfo) GoVersion ¶
GoVersion returns the Go runtime version used to make the current build.
func (*BuildInfo) Map ¶
Map returns the build information as a map. Field names are lowercase. Empty fields within BuildInfo are omitted.
func (*BuildInfo) MarshalJSON ¶
MarshalJSON returns valid JSON output. Empty fields within BuildInfo are omitted.
func (*BuildInfo) 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) UnmarshalJSON ¶ added in v0.5.0
Example ¶
data := someEmbeddedJsonData
var bld BuildInfo
if err := bld.UnmarshalJSON(data); err != nil {
panic(err)
}
fmt.Printf("version=%s, something=%s\n", bld.Version, bld.Extra["something"])
Output: version=1.2.3, something=else
Source Files