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{})
• func SwapRootOperation(new Operation)
• type DataListener
  • func NewDataListener[T any](f func(data T)) DataListener
• type EventListener
• type Operation
  • func NewOperation(parent Operation) Operation
  • func NewRootOperation() Operation

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.

func SwapRootOperation

func SwapRootOperation(new Operation)

SwapRootOperation allows to atomically swap the current root operation with the given new one. Concurrent uses of the old root operation on already existing and running operation are still valid.

Types

type DataListener

type DataListener EventListener

func NewDataListener

func NewDataListener[T any](f func(data T)) DataListener

NewDataListener creates a specialized generic data listener, wrapped under a DataListener interface

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)

	// OnData allows to register a data listener to the operation
	OnData(DataListener)

	// EmitData sends data to the data listeners of the operation
	EmitData(any)

	// 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 operation. It 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)
  }

func NewRootOperation

func NewRootOperation() Operation

NewRootOperation creates and returns a new root operation, with no parent operation. Root operations are meant to be the top-level operation of an operation stack, therefore receiving all the operation events. It allows to prepare a new set of event listeners, to then atomically swap it with the current one.