instrument

Documentation

Overview

Copyright 2018 Granitic. All rights reserved. Use of this source code is governed by an Apache 2.0 license that can be found in the LICENSE file at the root of this project.

Package instrument provides patterns and helper functions for instrumenting some flow of control (typically a web service request or scheduled activity).

This instrumentation is often the capture of timing data for the purposes of monitoring performance, but the type of instrumentation depends on the implementation of the
interfaces in this package.

Instrumentor

The key concept in this package is that of the Instrumentor, which is a common interface to instrumentation that is shared by your code and the
Granitic framework. It is expected that an instance of Instrumentator will be stored in the context.Context that is passed through your code. This
allows your code to use the helper functions in this package to either gain access to the Instrumentor or use one-line method calls to initiate instrumentation of a method

Web service instrumentation

Grantic's HttpServer has support for instrumenting your web service requests. See the facility/httpserver package documentation for more details.

Index

• func AddInstrumentorToContext(ctx context.Context, ri Instrumentor) context.Context
• type Additional
• type EndEvent
  • func Event(ctx context.Context, id string, metadata ...interface{}) EndEvent
  • func Method(ctx context.Context, metadata ...interface{}) EndEvent
• type Instrumentor
  • func InstrumentorFromContext(ctx context.Context) Instrumentor
• type RequestInstrumentationManager

Functions

func AddInstrumentorToContext

func AddInstrumentorToContext(ctx context.Context, ri Instrumentor) context.Context

AddInstrumentorToContext stores the supplied Instrumentor in a new context, derived from the supplied context.

Types

type Additional

type Additional uint

Additional is used as a flag to indicate what additional data being passed to the Instrumentor represents. These are used by Granitic to pass additional data about a request into a Instrumentor that is not known at the point instrumentation starts

const (
	REQUEST_ID      Additional = iota //string representation of a unique ID for the request
	REQUEST_VERSION                   //instance of ws.RequiredVersion
	USER_IDENTITY                     //instance of iam.ClientIdentity
	HANDLER                           //The handler that is processing the request (*ws.Handler)
)

type EndEvent

type EndEvent func()

func Event

func Event(ctx context.Context, id string, metadata ...interface{}) EndEvent

Event is convenience function that calls InstrumentorFromContext then StartEvent. This function fails silently if the result of InstrumentorFromContext is nil (e.g there is no Instrumentor in the context)

func Method

func Method(ctx context.Context, metadata ...interface{}) EndEvent

Method is a convenience function that calls Event with the name of the calling function as the ID. The format of the method name will be /path/to/package.(type).FunctionName

This function fails silently if the result of InstrumentorFromContext is nil (e.g there is no Instrumentor in the context)

type Instrumentor

type Instrumentor interface {
	// StartEvent indicates that a new instrumentable activity has begun with the supplied ID. Implementation specific additional
	// information about the event can be supplied via the metadata varg
	//
	// The function returned by this method should be called when the event ends. This facilitates a pattern like defer StartEvent(id)()
	StartEvent(id string, metadata ...interface{}) EndEvent

	// Fork creates a new context and Instrumentor suitable for passing to a child goroutine
	Fork(ctx context.Context) (context.Context, Instrumentor)

	//Integrate incorporates the data from a forked Instrumentor that was passed to a goroutine
	Integrate(instrumentor Instrumentor)

	//Amend allows Granitic to provide additional information about the request that was not available when instrumentation started
	Amend(additional Additional, value interface{})
}

Instrumentor is implemented by types that can add additional information to a request that is being instrumented in the form of sub/child events that are instrumented separately and additional framework data that was not available when instrumentation began.

Interfaces are not expected to be explicitly goroutine safe - the Fork and Integrate methods are intended for use when the request under instrumentation spawns new goroutines

func InstrumentorFromContext

func InstrumentorFromContext(ctx context.Context) Instrumentor

InstrumentorFromContext returns a Instrumentor from the supplied context, or nil if no Instrumentor is present

type RequestInstrumentationManager

type RequestInstrumentationManager interface {

	// Begin starts instrumentation and returns a Instrumentor that is able to instrument sub/child events of the request.
	// It is expected that most implementation will also store the Instrumentor in the context so it can be easily recovered
	// at any point in the request using the function InstrumentorFromContext.
	Begin(ctx context.Context, res http.ResponseWriter, req *http.Request) (context.Context, Instrumentor, func())
}

RequestInstrumentationManager is implemented by components that can instrument a web service request. This often involves recording timing data at various points in a request's lifecycle. Implementations can be attached to an instance of the Granitic HttpServer.