telemetry

README

telemetry

This module exposes channels that are meant be used for logging to Azure Application Insights and Prometheus. The information that is conveyed through the channel is either to Azure Application Insights or used to set/increase an internal Prometheus metric.

This package is currently dependent on the modules "github.com/3lvia/hn-config-lib-go/vault" which again means that you need a running instance of Hashicorp Vault in order to use this functionality. This dependency will probably become optional in a future version. The Vault instance is used for the sole purpose of fetching the instrumentation key for Application Insights.

The functionality is made available through the func Start which internally starts a go-routine listening to the different channels that are contained in the returned instance of LogChans. The following code sample shows how to bootstrap the functionality:

import (
    "context"
    "github.com/3lvia/telemetry-go"
    "github.com/3lvia/hn-config-lib-go/vault"
    "github.com/prometheus/client_golang/prometheus/promhttp"
)

ctx := context.Background()
v, err := vault.New()
if err != nil {
    log.Fatal(err)
}
systemName := "my-system"
appName := "my-app"
applicationInsightsVaultPath := "mount/kv/path/to/appinsights-instrumentationkey"
logChannels := telemetry.Start(ctx, systemName, appName, applicationInsightsVaultPath, v)
// logChannels are ready to use!

// Start Prometheus metrics API
metricsPort := "2112"
http.Handle("/metrics", promhttp.Handler())
http.ListenAndServe(metricsPort, nil)

Log Channels

• CountChan Increases the named Prometheus counter.
• GaugeChan Sets the named Prometheus counter.
• ErrorChan Sends the error to Application Insights. It is registered as an Exception in App Insights.
• EventChan Sends the event to Application Insights. It is registered as a Cusom Event in App Insights.
• DebugChan Prints the debug string to the console.

About Prometheus Names

The metric instances that are used in the two channels CountChan and GaugeChan contain the element Name. It is assumed that this name contains a human readable sentence that describes the metric, for instance Number of succesful API requests.

This sentence is transformed internally as follows: Number of succesful API requests -> number_of_succesful_api_requests

Simultaneously, the given sentence-based name is used as the "Help" of the metric.

Empty Logger

Sometimes it's useful to be able to spin up log channels that don't do anything, but that also don't block as logging events are sent on the logging channels. Unit testing is on such scenario.

This package implements the concept of empty logging to handle this scenario, the code sample below shows how it's used:

import (
    "github.com/3lvia/telemetry-go"
)

logChannels := telemetry.StartEmpty()
// logChannels are ready to use!

HTTP wrapper

This package implements HTTP wrapper functionality. The purpose of this is to provide automatic logging of metrics for the number of handled requests (in total and failed) and for latency.

An interface telemetry.RequestHandler is exposed, and clients must implement this interface and then wrap it through the function telemetry.Wrap

 import (
     "net/http"
     "github.com/3lvia/telemetry-go"
 )

myHandler := handlerImplementingRequestHandler{}
httpHandler := telemetry.Wrap(myHandler)
http.Handle("/mypath", httpHandler)

It is the responsibility of the client application handler to return an instance of telemetry.Rountrip with the correct values. The wrapper will automatically increse/set the correct metrics and also handle the http response correctly.

telemetry.Roundtrip contains the following fields:

• HandlerName a constant for the given handler. This value will be used in the metrics name, see below.
• HTTPResponseCode the http response code to be set on the response.
• Contents a byte slice containing the data to be added as contents on the http response.

The following metrics will be maintained automatically:

• http_responses_total (count) The total number of registered http requests
• http_responses_ (count) The total number of registered http requests for the given handler
• http_latency_total (histogram) Measures the latency across all API requests
• http_latency_ (histogram) Measures the latency across all API requests for the named handler

Documentation

Index

• func Wrap(h RequestHandler, logChannels LogChans) http.Handler
• type Event
• type LogChans
  • func Start(ctx context.Context, options Options, v vault.SecretsManager) LogChans
  • func StartEmpty(opts ...Option) LogChans
• type Metric
• type Option
  • func WithWriter(w io.Writer) Option
• type Options
• type OptionsCollector
• type RequestHandler
• type RoundTrip

Functions

func Wrap

func Wrap(h RequestHandler, logChannels LogChans) http.Handler

Wrap the handler so that it can be presented as http.Handler. The wrapper will automatically set the correct Prometheus metrics for each handled request.

Types

type Event

type Event struct {
	Name string
	Data map[string]string
}

Event is raised when something interesting happens in the application. Consists of a name an a map of key/value pairs.

type LogChans

type LogChans struct {
	// CountChan increases the named Prometheus counter.
	CountChan chan Metric

	// GaugeChan increases the named Prometheus gauge.
	GaugeChan chan Metric

	// HistogramChan observes the named Prometheus histogram.
	HistogramChan chan Metric

	// ErrorChan sends the error to Application Insights.
	ErrorChan chan error

	// EventChan sends the event to Application Insights.
	EventChan chan Event

	// DebugChan prints a debug message to the console.
	DebugChan chan string
}

LogChans a set of channels used for communicating events, metrics, errors and other telemetry types to the logger.

func Start

func Start(ctx context.Context, options Options, v vault.SecretsManager) LogChans

Start starts the logger in a go routine and returns a set of channels that can be used to send telemetry to the logger.

func StartEmpty

func StartEmpty(opts ...Option) LogChans

StartEmpty starts a logger that doesn't log anything, but that will not block when log events are sent on the logging channels, the purpose being to provide support for testing scenarios when logging is not in focus.

type Metric

type Metric struct {
	Name  string
	Value float64
}

Metric is a named numeric value.

type Option

type Option func(*OptionsCollector)

Option specifies options for configuring the logging.

func WithWriter

func WithWriter(w io.Writer) Option

WithWriter lets clients set a writer which will receive logging events (in addition to the events being written to the standard destinations).

type Options

type Options struct {
	// SystemName the name of the containing system.
	SystemName string

	// AppName is the name of the running application/micro-service.
	AppName string

	// AppInsightsSecretPath the path to Application Insights instrumentation key in Vault.
	AppInsightsSecretPath string

	// SendMetricsToAppInsights indicates whether metrics should be sent to Application Insights
	// in addition to Prometheus.
	SendMetricsToAppInsights bool
}

Options is used to configure the functionality of this entire module.

type OptionsCollector

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

OptionsCollector collects all options before they are set.

type RequestHandler

type RequestHandler interface {
	Handle(r *http.Request) RoundTrip
}

RequestHandler the instance that is responsible for the business logic to be performed as a result of the incoming http request. Clients wishing t

type RoundTrip

type RoundTrip struct {
	HandlerName      string
	HTTPResponseCode int
	Contents         []byte
}

RoundTrip contains the results og a single http request. It is the responsibility of the RequestHandler to return an instance of RoundTrip with appropriate values.