x: github.com/heroku/x/hmetrics Index | Examples | Files | Directories

package hmetrics

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

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

Examples

Package Files

hmetrics.go

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")
)

func Report Uses

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.

Code:

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)
}

Code:

// 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)
}

Code:

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)
    }
}()

type AlreadyStarted Uses

type AlreadyStarted struct{}

AlreadyStarted represents an Error condition of already being started.

func (AlreadyStarted) Error Uses

func (as AlreadyStarted) Error() string

func (AlreadyStarted) Fatal Uses

func (as AlreadyStarted) Fatal() bool

type ErrHandler Uses

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 Uses

type HerokuMetricsURLUnset struct{}

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

func (HerokuMetricsURLUnset) Error Uses

func (e HerokuMetricsURLUnset) Error() string

func (HerokuMetricsURLUnset) Fatal Uses

func (e HerokuMetricsURLUnset) Fatal() bool

Directories

PathSynopsis
onloadPackage onload automatically starts hmetrics reporting, ignoring errors and retrying reporting, backing off in 10 second increments.

Package hmetrics imports 12 packages (graph) and is imported by 1 packages. Updated 2019-09-07. Refresh now. Tools for package owners.