apm

README

APM

Wrapper around Sentry and zerolog to provide a simple way to instrument your Go applications.

Features

• Painless transactions and spans - apm.StartSpan()
• Context-aware logging and error handling - apm.NewContext(), apm.NewLogger()
• Automatic HTTP client instrumentation - apm.WrapClient(), apm.WrapRoundTripper()

Usage

package main

// configure APM on your app initialization
apm.SetName("my-app")
apm.SetLogLevel("debug")
apm.SetSentryDSN("https://sentry.io/your-dsn")

// optionally, if you have gitlab.com/etke.cc/go/healthchecks client
apm.SetHealthchecks(healthchecksClient)

// thats it! you are ready to go

// create a new context with correct sentry hub and logger
ctx := apm.NewContext()

// or instrument an existing context
ctx = apm.NewContext(context.Background())

// wrap your http client
client := apm.WrapClient() // wraps http.DefaultClient when no client is provided

// automatic request instrumentation and retries for 5xx errors
client.Do(req)

// work with transactions and spans. No transaction in context? Will be created automatically!
span := apm.StartSpan(ctx, "my-span")

Documentation

Index

• Constants
• func EchoLogger() echo.Logger
• func Error(ctx context.Context, err error)
• func Flush(ctx ...context.Context)
• func GetHub(ctx ...context.Context) *sentry.Hub
• func HealthcheckFail(optionalBody ...io.Reader)
• func Log(ctx ...context.Context) *zerolog.Logger
• func NewContext(parent ...context.Context) context.Context
• func NewLogger(ctx context.Context, sentryOpts ...zlogsentry.WriterOption) *zerolog.Logger
• func NewLoggerPlain() *zerolog.Logger
• func Recover(err any, repanic bool, ctx ...context.Context)
• func SetHealthchecks(h Healthchecks)
• func SetLogLevel(level string)
• func SetName(name string)
• func SetSentryDSN(dsn string)
• func StartSpan(ctx context.Context, operation string) *sentry.Span
• func WithSentry() echo.MiddlewareFunc
• func WrapClient(c *http.Client, opts ...RoundTripperOption) *http.Client
• func WrapRoundTripper(rt http.RoundTripper, opts ...RoundTripperOption) http.RoundTripper
• type Healthchecks
• type RoundTripper
  • func (rt *RoundTripper) RoundTrip(req *http.Request) (*http.Response, error)
• type RoundTripperOption
  • func WithMaxRetries(maxRetries int) RoundTripperOption
  • func WithRetryDelay(retryDelay time.Duration) RoundTripperOption

Constants

const (
	// MaxRetries for http requests
	MaxRetries = 5
	// RetryDelay for http requests
	RetryDelay = 5 * time.Second
)

Functions

func EchoLogger

func EchoLogger() echo.Logger

EchoLogger is a wrapper around the zerolog logger (without sentry) that implements the echo.Logger interface.

func Error

func Error(ctx context.Context, err error)

Error captures the error and sends it to sentry and healthchecks

func Flush

func Flush(ctx ...context.Context)

Flush sends the events to sentry

func GetHub

func GetHub(ctx ...context.Context) *sentry.Hub

GetHub returns the hub from the context (if context is provided and has a hub) or the current hub

func HealthcheckFail

func HealthcheckFail(optionalBody ...io.Reader)

HealthcheckFail sends a healthcheck fail event (if healthchecks are configured)

func Log

func Log(ctx ...context.Context) *zerolog.Logger

Log returns a logger with the context provided, if no context is provided, it will return a logger with a new context

func NewContext

func NewContext(parent ...context.Context) context.Context

NewContext creates a new context with a logger and sentry hub

func NewLogger

func NewLogger(ctx context.Context, sentryOpts ...zlogsentry.WriterOption) *zerolog.Logger

NewLogger returns a new logger with sentry integration (if possible)

func NewLoggerPlain

func NewLoggerPlain() *zerolog.Logger

NewLoggerPlain returns a new logger without sentry integration

func Recover

func Recover(err any, repanic bool, ctx ...context.Context)

Recover sends the error to sentry

func SetHealthchecks

func SetHealthchecks(h Healthchecks)

SetHealthchecks sets the healthchecks client

func SetLogLevel

func SetLogLevel(level string)

SetLogLevel sets the log level

func SetName

func SetName(name string)

SetName sets the name of the application

func SetSentryDSN

func SetSentryDSN(dsn string)

SetSentryDSN sets the sentry DSN

func StartSpan

func StartSpan(ctx context.Context, operation string) *sentry.Span

StartSpan starts a new span, and if there is no transaction, it starts a new transaction

func WithSentry

func WithSentry() echo.MiddlewareFunc

WithSentry is a middleware that creates a new transaction for each request.

func WrapClient

func WrapClient(c *http.Client, opts ...RoundTripperOption) *http.Client

WrapClient wraps an http.Client with APM instrumentation and retry logic

func WrapRoundTripper

func WrapRoundTripper(rt http.RoundTripper, opts ...RoundTripperOption) http.RoundTripper

WrapRoundTripper wraps an http.RoundTripper with APM instrumentation and retry logic

Types

type Healthchecks

type Healthchecks interface {
	Fail(optionalBody ...io.Reader)
}

Healthchecks is the interface for gitlab.com/etke.cc/go/healthchecks, to avoid direct dependecy on the package for project where it is not needed

type RoundTripper

type RoundTripper struct {
	// contains filtered or unexported fields
}

RoundTripper is an http.RoundTripper that instruments http requests

func (*RoundTripper) RoundTrip

func (rt *RoundTripper) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements the http.RoundTripper interface, creating a transaction and span for each http request and handling retries for 5xx responses

type RoundTripperOption

type RoundTripperOption func(*RoundTripper)

RoundTripperOption is a function that configures an APMRoundTripper

func WithMaxRetries

func WithMaxRetries(maxRetries int) RoundTripperOption

WithMaxRetries sets the maximum number of retries for http requests, otherwise defaults to 5

func WithRetryDelay

func WithRetryDelay(retryDelay time.Duration) RoundTripperOption

WithRetryDelay sets the delay between retries for http requests, otherwise defaults to 5 seconds