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

    Constants

    This section is empty.

    Variables

    This section is empty.

    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.