ochealth

README

ochealth

Purpose

ochealth exports health.State data via OpenCensus.

ochealth allows you to take the state from a health server and export the data in it via OpenCensus metrics. For example, to track the readiness of your server over time you can use OpenCensus to export via Prometheus metrics where you can graph and alert on your service not being ready. It also allows you to export version information so you can easily correlate version changes with changes in other metrics making it easier to identify regressions.

For more information see register.go.

Example Usage

package ochealth_test

import (
	"fmt"
	"net/http/httptest"

	ocprom "contrib.go.opencensus.io/exporter/prometheus"
	"github.com/anz-bank/pkg/health"
	"github.com/anz-bank/pkg/health/ochealth"
)

func Example() {
	// normally set with go build linker option
	health.CommitHash = "0123456789abcdef0123456789abcdef01234567"
	health.Semver = "v1.2.3"

	// Real code handles errors.
	server, _ := health.NewHTTPServer()
	_ = ochealth.Register(server.State, ochealth.WithPrefix("myapp"))
	prom, _ := ocprom.NewExporter(ocprom.Options{})

	server.SetReady(true)

	r := httptest.NewRequest("GET", "/", nil)
	w := httptest.NewRecorder()
	prom.ServeHTTP(w, r)

	fmt.Print(w.Body.String())
	//nolint:lll
	// output:
	// # HELP myapp_ready Readiness state of server
	// # TYPE myapp_ready gauge
	// myapp_ready 1
	// # HELP myapp_version Version information
	// # TYPE myapp_version gauge
	// myapp_version{build_log_url="undefined",commit_hash="0123456789abcdef0123456789abcdef01234567",container_tag="undefined",repo_url="undefined",semver="v1.2.3"} 1
}

Documentation

Overview

Package ochealth exports health.State data via OpenCensus.

ochealth allows you to take the state from a health server and export the data in it via OpenCensus metrics. For example, to track the readiness of your server over time you can use OpenCensus to export via Prometheus metrics where you can graph and alert on your service not being ready. It also allows you to export version information so you can easily correlate version changes with changes in other metrics making it easier to identify regressions.

The servers in github.com/anz-bank/pkg/health all have a State field. This can be passed to the Register function in this package to have that state provided as OpenCensus metrics.

Two metrics are published by this package: - anz_health_ready - anz_health_version

The "ready" metric tracks the real-time value of the Ready field in the State, exporting false as 0 and true as 1.

The "version" metric is constant - it is exported as 1 and never changes. It is the labels on this that are the part of interest. The fields of the Version in the State are exported as labels on the metric. The current labels are "build_log_url", "commit_hash", "container_tag", "semver" and "repo_url".

The prefix "anz_health" is configurable with the WithPrefix Option that can be passed to Register. The prefix can be removed entirely by using the empty string as a prefix.

Additional labels can be added to the metrics with the WithConstLabels Option. NOTE: This currently panics due to a bug in the OpenCensus Go library. The panic will be removed when https://github.com/census-instrumentation/opencensus-go/pull/1221 is merged and released.

Index

• func Register(s *health.State, options ...Option) error
• type Option
  • func WithConstLabels(labels map[metricdata.LabelKey]metricdata.LabelValue) Option
  • func WithPrefix(metricPrefix string) Option

Functions

func Register

func Register(s *health.State, options ...Option) error

Register creates a metrics registry with values from the given health.State and adds it to the global metric producer to be available to all the metric exporters. The metrics registry tracks changes to the non-constant values in the health.State.

Types

type Option

type Option func(*registerOptions)

Option is used to configure the registration of the health state. The With* functions should be used to obtain options for passing to Register.

func WithConstLabels

func WithConstLabels(labels map[metricdata.LabelKey]metricdata.LabelValue) Option

WithConstLabels returns an Option that adds additional labels with constant values to the metrics published by this package.

func WithPrefix

func WithPrefix(metricPrefix string) Option

WithPrefix returns an option that sets the prefix on the metric name published by this package. The default is "anz_health" which can be overidden with this option. The empty string removes the prefix. Any other value will be used as the prefix with an underscore separating the prefix from the base metric name.