granitic: Index | Files

package instrument

import ""

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.


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.


Package Files

instrument.go request.go

func AddInstrumentorToContext Uses

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

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

type Additional Uses

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 (
    //RequestID marks a string representation of a unique ID for the request
    RequestID Additional = iota
    //RequestVersion marks an instance of ws.RequiredVersion
    //UserIdentity marks instance of iam.ClientIdentity
    //Handler is he handler that is processing the request (*ws.Handler)

type EndEvent Uses

type EndEvent func()

EndEvent is a function that is returned when an instrumentation event is started and should be called when the event ends

func Event Uses

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 Uses

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 Uses

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 Uses

func InstrumentorFromContext(ctx context.Context) Instrumentor

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

type RequestInstrumentationManager Uses

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.

Package instrument imports 4 packages (graph). Updated 2019-04-14. Refresh now. Tools for package owners.