telemetry

README

Telemetry

• Open Telemetry
• am-dbg

Open Telemetry

Otel integration exposes machine's states and transitions as Otel traces, compatible with Jaeger. Tracers are inherited from parent machines and form a tree.

Machine tree structure:

- mach:ID
  - states
    - Foo
      - Foo (trace)
      - Foo (trace)
      - ...
    - ...
  - transitions
    - [add] Foo
      - FooEnter (trace)
      - FooState (trace)
      - ...
    - ...
  - submachines
    - mach:ID2
      - ...
    - ...

See pkg/telemetry for more info or import an existing asset

am-dbg

am-dbg telemetry delivers DbgMsg and DbgMsgStruct via simple net/rpc to tools/cmd/am-dbg. It can be consumed by a custom client as well.

Documentation

Overview

Package telemetry provides telemetry exporters for asyncmachine: am-dbg, Prometheus, and OpenTelemetry.

Index

• Constants
• func TransitionsToDBG(mach *am.Machine, url string) error
• type DbgMsg
• type DbgMsgStruct
  • func (d *DbgMsgStruct) Clock(_ am.S, _ string) uint64
  • func (d *DbgMsgStruct) Is(_ am.S, _ am.S) bool
• type DbgMsgTx
  • func (d *DbgMsgTx) Clock(statesIndex am.S, state string) uint64
  • func (d *DbgMsgTx) Is(statesIndex am.S, states am.S) bool
  • func (d *DbgMsgTx) Is1(statesIndex am.S, state string) bool
  • func (d *DbgMsgTx) TimeSum() uint64
• type OtelMachTracer
  • func NewOtelMachTracer(tracer trace.Tracer, opts *OtelMachTracerOpts) *OtelMachTracer
  • func (ot *OtelMachTracer) End()
  • func (ot *OtelMachTracer) HandlerEnd(tx *am.Transition, _ string, _ string)
  • func (ot *OtelMachTracer) HandlerStart(tx *am.Transition, emitter string, handler string)
  • func (ot *OtelMachTracer) Inheritable() bool
  • func (ot *OtelMachTracer) MachineDispose(id string)
  • func (ot *OtelMachTracer) MachineInit(mach *am.Machine)
  • func (ot *OtelMachTracer) NewSubmachine(parent, mach *am.Machine)
  • func (ot *OtelMachTracer) QueueEnd(*am.Machine)
  • func (ot *OtelMachTracer) TransitionEnd(tx *am.Transition)
  • func (ot *OtelMachTracer) TransitionInit(tx *am.Transition)
• type OtelMachTracerOpts
• type OtelMachineData

Constants

const DbgHost = "localhost:6831"

Functions

func TransitionsToDBG

func TransitionsToDBG(mach *am.Machine, url string) error

TransitionsToDBG sends transitions to the am-dbg server. TODO test TransitionsToDBG TODO support changes to mach.StateNames TODO rewrite to Tracer API?

Types

type DbgMsg

type DbgMsg interface {
	// Clock returns the state's clock, using the passed index
	Clock(statesIndex am.S, state string) uint64
	// Is returns true if the state is active, using the passed index
	Is(statesIndex am.S, states am.S) bool
}

DbgMsg is the interface for the messages to be sent to the am-dbg server.

type DbgMsgStruct

type DbgMsgStruct struct {
	// Machine ID
	ID string
	// state names defining the indexes for diffs
	StatesIndex am.S
	// all the states with relations
	States am.Struct
}

DbgMsgStruct contains the state and relations data.

func (*DbgMsgStruct) Clock

func (d *DbgMsgStruct) Clock(_ am.S, _ string) uint64

func (*DbgMsgStruct) Is

func (d *DbgMsgStruct) Is(_ am.S, _ am.S) bool

type DbgMsgTx

type DbgMsgTx struct {
	MachineID string
	// Transition ID
	ID string
	// map of positions from the index to state clocks
	Clocks am.T
	// result of the transition
	Accepted bool
	// mutation type
	Type am.MutationType
	// called states
	CalledStates []string
	// all the transition steps
	Steps []*am.Step
	// log entries created during the transition
	LogEntries []*am.LogEntry
	// log entries before the transition, which happened after the prev one
	PreLogEntries []*am.LogEntry
	// transition was triggered by an auto state
	IsAuto bool
	// queue length at the start of the transition
	Queue int
	// don't send this over the wire
	Time *time.Time
}

DbgMsgTx contains transition data.

func (*DbgMsgTx) Clock

func (d *DbgMsgTx) Clock(statesIndex am.S, state string) uint64

func (*DbgMsgTx) Is

func (d *DbgMsgTx) Is(statesIndex am.S, states am.S) bool

func (*DbgMsgTx) Is1

func (d *DbgMsgTx) Is1(statesIndex am.S, state string) bool

func (*DbgMsgTx) TimeSum

func (d *DbgMsgTx) TimeSum() uint64

type OtelMachTracer

type OtelMachTracer struct {
	Tracer        trace.Tracer
	Machines      map[string]*OtelMachineData
	MachinesMx    sync.Mutex
	MachinesOrder []string
	Logf          func(format string, args ...any)
	// contains filtered or unexported fields
}

OtelMachTracer implements machine.Tracer for OpenTelemetry. Support tracing multiple machines

func NewOtelMachTracer

func NewOtelMachTracer(tracer trace.Tracer, opts *OtelMachTracerOpts,
) *OtelMachTracer

NewOtelMachTracer creates a new machine tracer from an OpenTelemetry tracer. Requires OtelMachTracer.Dispose to be called at the end.

func (*OtelMachTracer) End

func (ot *OtelMachTracer) End()

func (*OtelMachTracer) HandlerEnd

func (ot *OtelMachTracer) HandlerEnd(tx *am.Transition, _ string, _ string)

func (*OtelMachTracer) HandlerStart

func (ot *OtelMachTracer) HandlerStart(
	tx *am.Transition, emitter string, handler string,
)

func (*OtelMachTracer) Inheritable

func (ot *OtelMachTracer) Inheritable() bool

func (*OtelMachTracer) MachineDispose

func (ot *OtelMachTracer) MachineDispose(id string)

func (*OtelMachTracer) MachineInit

func (ot *OtelMachTracer) MachineInit(mach *am.Machine)

func (*OtelMachTracer) NewSubmachine

func (ot *OtelMachTracer) NewSubmachine(parent, mach *am.Machine)

NewSubmachine links 2 machines with a parent-child relationship.

func (*OtelMachTracer) QueueEnd

func (ot *OtelMachTracer) QueueEnd(*am.Machine)

func (*OtelMachTracer) TransitionEnd

func (ot *OtelMachTracer) TransitionEnd(tx *am.Transition)

func (*OtelMachTracer) TransitionInit

func (ot *OtelMachTracer) TransitionInit(tx *am.Transition)

type OtelMachTracerOpts

type OtelMachTracerOpts struct {
	// if true, only state changes will be traced
	SkipTransitions bool
	Logf            func(format string, args ...any)
}

type OtelMachineData

type OtelMachineData struct {
	ID string
	// handler ctx & span to be used for more detailed tracing inside handlers
	HandlerTrace context.Context
	HandlerSpan  trace.Span
	Lock         sync.Mutex
	Ended        bool
	// contains filtered or unexported fields
}