hmetrics

Documentation

Overview

Package hmetrics is a self-contained client for Heroku Go runtime metrics.

Typical usage is through the `github.com/heroku/x/hmetrics/onload` package imported like so:

import _ "github.com/heroku/x/hmetrics/onload"

You can find more information about Heroku Go runtime metrics here: https://devcenter.heroku.com/articles/language-runtime-metrics-go

Index

• Variables
• func Report(ctx context.Context, endpoint string, ef ErrHandler) error
• type AlreadyStarted
  • func (as AlreadyStarted) Error() string
  • func (as AlreadyStarted) Fatal() bool
• type ErrHandler
• type HerokuMetricsURLUnset
  • func (e HerokuMetricsURLUnset) Error() string
  • func (e HerokuMetricsURLUnset) Fatal() bool

Examples

• Report (Advanced)
• Report (Basic)
• Report (Logging)

Variables

var (
	// DefaultEndpoint to report metrics to Heroku. The "HEROKU_METRICS_URL" env
	// var is set by the Heroku runtime when the `runtime-heroku-metrics` labs
	// flag is enabled. For more info see:
	// https://devcenter.heroku.com/articles/language-runtime-metrics
	//
	// DefaultEndpoint must be changed before Report is called.
	DefaultEndpoint = os.Getenv("HEROKU_METRICS_URL")
)

Functions

func Report

func Report(ctx context.Context, endpoint string, ef ErrHandler) error

Report go metrics to the endpoint until the context is canceled.

Only one call to the ErrHandler will happen at a time. Metrics can be dropped or delayed if a call to ErrHandler takes longer than the reprting interval. Processing of metrics continues if the ErrHandler returns nil, but aborts if the ErrHandler itself returns an error. It is safe to pass a nil ErrHandler.

Report is safe for concurrent usage, but calling it again w/o canceling the context passed previously returns an AlreadyStarted error. This is to ensure that metrics aren't duplicated. Report can be called again to restart reporting after the context is canceled.

Example (Advanced)

package main

import (
	"context"
	"log"
	"net/http"
	"os"

	"github.com/heroku/x/hmetrics"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	go func() {
		type fataler interface {
			Fatal() bool
		}
		for { // try again and again on non fatal errors
			if err := hmetrics.Report(ctx, hmetrics.DefaultEndpoint, func(err error) error {
				log.Println("Error reporting metrics to heroku:", err)
				return nil
			}); err != nil {
				if f, ok := err.(fataler); ok && f.Fatal() {
					log.Fatal(err)
				}
				log.Println(err)
			}
		}
	}()

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	if err := http.ListenAndServe(":"+port, nil); err != nil {
		log.Fatal(err)
	}
}

Example (Basic)

package main

import (
	"context"
	"log"
	"net/http"
	"os"

	"github.com/heroku/x/hmetrics"
)

func main() {
	// Don't care about canceling or errors
	go hmetrics.Report(context.Background(), hmetrics.DefaultEndpoint, nil) //nolint:errcheck

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	if err := http.ListenAndServe(":"+port, nil); err != nil {
		log.Fatal(err)
	}
}

Example (Logging)

package main

import (
	"context"
	"log"

	"github.com/heroku/x/hmetrics"
)

func main() {
	go func() {
		if err := hmetrics.Report(context.Background(), hmetrics.DefaultEndpoint, func(err error) error {
			log.Println("Error reporting metrics to heroku:", err)
			return nil
		}); err != nil {
			log.Fatal("Error starting hmetrics reporting:", err)
		}
	}()
}

Types

type AlreadyStarted

type AlreadyStarted struct{}

AlreadyStarted represents an Error condition of already being started.

func (AlreadyStarted) Error

func (as AlreadyStarted) Error() string

func (AlreadyStarted) Fatal

func (as AlreadyStarted) Fatal() bool

type ErrHandler

type ErrHandler func(err error) error

ErrHandler funcations are used to provide custom processing/handling of errors encountered during the collection or reporting of metrics to Heroku.

type HerokuMetricsURLUnset

type HerokuMetricsURLUnset struct{}

HerokuMetricsURLUnset represents the Error condition when the HEROKU_METRICS_URL environment variables is unset or an empty string.

func (HerokuMetricsURLUnset) Error

func (e HerokuMetricsURLUnset) Error() string

func (HerokuMetricsURLUnset) Fatal

func (e HerokuMetricsURLUnset) Fatal() bool