Version Package

The version package provides build information utilities for Prometheus components, including version numbers, build metadata, and user agent string generation.

Import

import "github.com/prometheus/common/version"

Overview

This package captures build-time information (version, revision, branch, build user, build date) and provides functions to format this information for display and logging. The build information is typically populated at build time using linker flags.

Build Variables

Version Information

var Version string

Version string populated at build time (e.g., "2.45.0").

var Revision string

Git revision hash populated at build time.

var Branch string

Git branch name populated at build time.

var BuildUser string

Username of the user who built the binary, populated at build time.

var BuildDate string

Timestamp when the binary was built, populated at build time.

Runtime Information

var GoVersion string

Go version used to build the binary. Defaults to runtime.Version().

var GoOS string

Target operating system. Defaults to runtime.GOOS.

var GoArch string

Target architecture. Defaults to runtime.GOARCH.

Functions

Print

func Print(program string) string

Returns version information formatted as multi-line text suitable for printing to console or logs.

Parameters:

• program - The program name to include in the output

Returns: Multi-line string with version, branch, revision, Go version, platform, user, date, and tags information

Example:

fmt.Println(version.Print("prometheus"))
// Output:
// prometheus, version 2.45.0 (branch: main, revision: abc123)
//   build user:       user@hostname
//   build date:       20230615-14:23:45
//   go version:       go1.20.5
//   platform:         linux/amd64

Info

func Info() string

Returns a concise version information string with version, branch, and revision.

Returns: String in format (version=%s, branch=%s, revision=%s)

Example:

log.Printf("Starting server %s", version.Info())
// Output: Starting server (version=2.45.0, branch=main, revision=abc123)

BuildContext

func BuildContext() string

Returns build context information including Go version, platform, build user, build date, and tags.

Returns: String in format (go=%s, platform=%s, user=%s, date=%s, tags=%s)

Example:

log.Printf("Build context: %s", version.BuildContext())
// Output: Build context: (go=go1.20.5, platform=linux/amd64, user=user@hostname, date=20230615-14:23:45, tags=netgo)

GetRevision

func GetRevision() string

Returns the revision string. If the build-time Revision variable is empty, attempts to compute it from VCS (version control system) information embedded in the binary.

Returns: Git revision hash

GetTags

func GetTags() string

Returns the build tags used when compiling the binary.

Returns: Comma-separated list of build tags

PrometheusUserAgent

func PrometheusUserAgent() string

Returns a User-Agent string for Prometheus HTTP clients.

Returns: String in format Prometheus/{Version}

Example:

userAgent := version.PrometheusUserAgent()
// Returns: "Prometheus/2.45.0"

ComponentUserAgent

func ComponentUserAgent(component string) string

Returns a User-Agent string for a specific Prometheus component.

Parameters:

• component - The component name (e.g., "alertmanager", "pushgateway")

Returns: String in format {component}/{Version}

Example:

userAgent := version.ComponentUserAgent("alertmanager")
// Returns: "alertmanager/0.26.0"

Usage Example

Basic Usage

package main

import (
    "fmt"
    "log"

    "github.com/prometheus/common/version"
)

func main() {
    // Print full version information
    fmt.Println(version.Print("myapp"))

    // Log concise version info
    log.Printf("Starting myapp %s", version.Info())

    // Use component-specific user agent
    userAgent := version.ComponentUserAgent("myapp")
    log.Printf("User-Agent: %s", userAgent)
}

Build-Time Variables

To populate the version variables at build time, use linker flags:

go build -ldflags "\
    -X github.com/prometheus/common/version.Version=2.45.0 \
    -X github.com/prometheus/common/version.Revision=$(git rev-parse HEAD) \
    -X github.com/prometheus/common/version.Branch=$(git rev-parse --abbrev-ref HEAD) \
    -X github.com/prometheus/common/version.BuildUser=$(whoami)@$(hostname) \
    -X github.com/prometheus/common/version.BuildDate=$(date -u +'%Y%m%d-%H:%M:%S')" \
    -o myapp

Version Command

Common pattern for implementing a version command:

package main

import (
    "flag"
    "fmt"
    "os"

    "github.com/prometheus/common/version"
)

func main() {
    var versionFlag bool
    flag.BoolVar(&versionFlag, "version", false, "Print version information")
    flag.Parse()

    if versionFlag {
        fmt.Println(version.Print("myapp"))
        os.Exit(0)
    }

    // ... rest of application
}