dyngo

Documentation

Overview

Package dyngo is the Go implementation of Datadog's Instrumentation Gateway which provides an event-based instrumentation API based on a stack representation of instrumented functions along with nested event listeners. It allows to both correlate passed and future function calls in order to react and monitor specific function call scenarios, while keeping the monitoring state local to the monitoring logic thanks to nested Go function closures. dyngo is not intended to be directly used and should be instead wrapped behind statically and strongly typed wrapper types. Indeed, dyngo is a generic implementation relying on empty interface values (values of type `interface{}`) and using it directly can be error-prone due to the lack of compile-time type-checking. For example, AppSec provides the package `httpsec`, built on top of dyngo, as its HTTP instrumentation API and which defines the abstract HTTP operation representation expected by the AppSec monitoring.

Index

• func FinishOperation(op Operation, results interface{})
• func StartOperation(op Operation, args interface{})
• type EventListener
• type Operation
  • func NewOperation(parent Operation) Operation
• type UnregisterFunc
  • func Register(listeners ...EventListener) UnregisterFunc

Functions

func FinishOperation

func FinishOperation(op Operation, results interface{})

FinishOperation finishes the operation along with its results and emits a finish event with the operation results. The operation is then disabled and its event listeners removed.

func StartOperation

func StartOperation(op Operation, args interface{})

StartOperation starts a new operation along with its arguments and emits a start event with the operation arguments.

Types

type EventListener

type EventListener interface {
	// ListenedType returns the Go type the event listener listens to.
	ListenedType() reflect.Type
	// Call the underlying event listener function. The type of the value v
	// is the type the event listener listens to, according to the type
	// returned by ListenedType().
	Call(op Operation, v interface{})
}

EventListener interface allowing to identify the Go type listened to and dispatch calls to the underlying event listener function.

type Operation

type Operation interface {
	// On allows to register an event listener to the operation. The event
	// listener will be removed from the operation once it finishes.
	On(EventListener)

	// Parent return the parent operation. It returns nil for the root
	// operation.
	Parent() Operation
	// contains filtered or unexported methods
}

Operation interface type allowing to register event listeners to the operation. The event listeners will be automatically removed from the operation once it finishes so that it no longer can be called on finished operations.

func NewOperation

func NewOperation(parent Operation) Operation

NewOperation creates and returns a new operationIt must be started by calling StartOperation, and finished by calling FinishOperation. The returned operation should be used in wrapper types to provide statically typed start and finish functions. The following example shows how to wrap an operation so that its functions are statically typed (instead of dyngo's interface{} values):

package mypackage
import "dyngo"
type (
  MyOperation struct {
    dyngo.Operation
  }
  MyOperationArgs { /* ... */ }
  MyOperationRes { /* ... */ }
)
func StartOperation(args MyOperationArgs, parent dyngo.Operation) MyOperation {
  op := MyOperation{Operation: dyngo.NewOperation(parent)}
  dyngo.StartOperation(op, args)
  return op
}
func (op MyOperation) Finish(res MyOperationRes) {
    dyngo.FinishOperation(op, res)
  }

type UnregisterFunc

type UnregisterFunc func()

UnregisterFunc is a function allowing to unregister from an operation the previously registered event listeners.

func Register

func Register(listeners ...EventListener) UnregisterFunc

Register global operation event listeners to listen to.