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