monitor

Documentation

Index

• func DefaultSocketPath(appName string, pid int) string
• func Emit(t Trace)
• func Enabled() bool
• func SetDescribeFunc(fn func() *Snapshot)
• func WriteDiscovery(appName string, pid int, sockPath string) (cleanup func(), err error)
• type AppInfo
• type BindingInfo
• type Config
• type DiscoveryEntry
  • func ListDiscovery() ([]DiscoveryEntry, error)
• type Envelope
• type EventListenerInfo
• type Insets
• type MsgType
• type ParamInfo
• type Request
• type RequestType
• type Sample
• type ScreenInfo
• type Sink
  • func Start(cfg Config) (*Sink, error)
  • func (s *Sink) SocketPath() string
  • func (s *Sink) Stop()
• type Snapshot
• type Trace
• type TraceError
• type WindowInfo

Functions

func DefaultSocketPath

func DefaultSocketPath(appName string, pid int) string

DefaultSocketPath returns the default unix socket path for the given app.

func Emit

func Emit(t Trace)

Emit records a trace. It stamps the sequence number and time, stores the record in the replay ring, and broadcasts it to all connected clients wrapped in an Envelope. It never blocks the caller: a slow client simply drops records.

func Enabled

func Enabled() bool

Enabled reports whether the monitor is currently running. Callers should gate any expensive work (e.g. JSON marshaling of arguments) behind this so there is zero cost when the monitor is off.

func SetDescribeFunc

func SetDescribeFunc(fn func() *Snapshot)

SetDescribeFunc registers the snapshot collector. Pass nil to clear.

func WriteDiscovery

func WriteDiscovery(appName string, pid int, sockPath string) (cleanup func(), err error)

WriteDiscovery writes a discovery file so external tools can find this app. The returned cleanup func removes it.

Types

type AppInfo

type AppInfo struct {
	Name      string `json:"name"`
	PID       int    `json:"pid"`
	Platform  string `json:"platform"`
	Transport string `json:"transport,omitempty"`
	DevServer string `json:"devServer,omitempty"`
	DebugMode bool   `json:"debugMode"`
}

AppInfo is static application metadata.

type BindingInfo

type BindingInfo struct {
	FQN     string      `json:"fqn"`
	Name    string      `json:"name"`
	ID      uint32      `json:"id"`
	Service string      `json:"service,omitempty"`
	Comment string      `json:"comment,omitempty"`
	Inputs  []ParamInfo `json:"inputs,omitempty"`
	Outputs []ParamInfo `json:"outputs,omitempty"`
}

BindingInfo describes one bound method the frontend can call.

type Config

type Config struct {
	// SocketPath is the unix socket to listen on. Required.
	SocketPath string
	// RingSize is the number of recent records replayed to a newly connected
	// client. Defaults to 4096 when <= 0.
	RingSize int
	// ClientBuffer is the per-client send-queue depth. Defaults to 1024.
	ClientBuffer int
}

Config configures a Sink.

type DiscoveryEntry

type DiscoveryEntry struct {
	Name      string    `json:"name"`
	PID       int       `json:"pid"`
	Sock      string    `json:"sock"`
	StartedAt time.Time `json:"startedAt"`
}

DiscoveryEntry describes a running, monitorable Wails app.

func ListDiscovery

func ListDiscovery() ([]DiscoveryEntry, error)

ListDiscovery returns all discoverable apps, skipping (and cleaning up) entries whose process is no longer alive.

type Envelope

type Envelope struct {
	Type     MsgType   `json:"t"`
	Trace    *Trace    `json:"trace,omitempty"`
	Snapshot *Snapshot `json:"snapshot,omitempty"`
	Sample   *Sample   `json:"sample,omitempty"`
}

Envelope is one server→client message.

type EventListenerInfo

type EventListenerInfo struct {
	Name  string `json:"name"`
	Count int    `json:"count"` // number of registered listeners
}

EventListenerInfo describes a backend-registered listener for an event name.

type Insets

type Insets struct {
	Left   int `json:"left"`
	Right  int `json:"right"`
	Top    int `json:"top"`
	Bottom int `json:"bottom"`
}

Insets are per-edge sizes (window borders).

type MsgType

type MsgType string

MsgType discriminates server-sent envelopes.

const (
	MsgTrace    MsgType = "trace"
	MsgSnapshot MsgType = "snapshot"
	MsgSample   MsgType = "sample"
)

type ParamInfo

type ParamInfo struct {
	Name string `json:"name,omitempty"`
	Type string `json:"type"`
}

ParamInfo is one input/output parameter of a bound method.

type Request

type Request struct {
	Type RequestType `json:"req"`
}

Request is one client→server message.

type RequestType

type RequestType string

RequestType discriminates client-sent requests.

const (
	ReqDescribe RequestType = "describe"
)

type Sample

type Sample struct {
	Time time.Time `json:"time"`

	// Process-wide resident memory, in bytes (RSS from the OS). Zero if the
	// platform probe is unavailable.
	RSS uint64 `json:"rss"`
	// CPU usage since the previous sample, as a percentage of one core. May
	// exceed 100 on multi-core workloads.
	CPUPct float64 `json:"cpuPct"`

	// Go runtime stats — always available, no syscall.
	HeapAlloc  uint64 `json:"heapAlloc"`
	HeapSys    uint64 `json:"heapSys"`
	Goroutines int    `json:"goroutines"`
	NumGC      uint32 `json:"numGC"`

	// Thread / file-descriptor counts from the OS (zero if unavailable).
	Threads int `json:"threads"`
	FDs     int `json:"fds"`
}

Sample is one periodic resource-usage reading for the monitored process. It shares a time axis with Trace records, so a consumer can correlate a span of binding calls/events with the RAM/CPU the process was using at that moment.

type ScreenInfo

type ScreenInfo struct {
	Name        string  `json:"name"`
	ID          string  `json:"id"`
	IsPrimary   bool    `json:"isPrimary"`
	ScaleFactor float32 `json:"scaleFactor"` // DPI / 96
	Rotation    float32 `json:"rotation"`
	BoundsW     int     `json:"boundsW"`
	BoundsH     int     `json:"boundsH"`
	BoundsX     int     `json:"boundsX"`
	BoundsY     int     `json:"boundsY"`
	WorkW       int     `json:"workW"`
	WorkH       int     `json:"workH"`
}

ScreenInfo describes the display a window is currently on.

type Sink

type Sink struct {
	// contains filtered or unexported fields
}

Sink owns the unix listener, the replay ring, and the set of connected clients.

func Start

func Start(cfg Config) (*Sink, error)

Start creates the unix listener, installs the global sink, and begins accepting clients. Only one sink may be active at a time; starting a second replaces (but does not stop) the first, so callers should Stop the previous one first.

func (*Sink) SocketPath

func (s *Sink) SocketPath() string

SocketPath returns the path this sink is listening on.

func (*Sink) Stop

func (s *Sink) Stop()

Stop closes the listener, disconnects clients, clears the global sink, and removes the socket file. It is idempotent.

type Snapshot

type Snapshot struct {
	App       AppInfo             `json:"app"`
	Windows   []WindowInfo        `json:"windows"`
	Bindings  []BindingInfo       `json:"bindings"`
	Listeners []EventListenerInfo `json:"listeners"`
}

Snapshot is a point-in-time description of the running app: its windows, the bound methods the frontend can call, the events the backend listens for, and app metadata. It is requested on demand by a consumer (the TUI) and is independent of the live trace stream.

type Trace

type Trace struct {
	Seq        uint64          `json:"seq"`
	Time       time.Time       `json:"time"`
	Kind       string          `json:"kind"` // "call" | "result" | "error" | "event" | "cancel"
	Dir        string          `json:"dir"`  // "in" (JS->Go) | "out" (Go->JS)
	CallID     string          `json:"callId,omitempty"`
	Object     int             `json:"object"`
	ObjectName string          `json:"objectName,omitempty"`
	Method     string          `json:"method"`
	Window     string          `json:"window,omitempty"`
	ClientID   string          `json:"clientId,omitempty"`
	Args       json.RawMessage `json:"args,omitempty"`
	Result     json.RawMessage `json:"result,omitempty"`
	Error      *TraceError     `json:"error,omitempty"`
	DurationMS float64         `json:"durationMs,omitempty"`
}

Trace is a single IPC event, serialized as one NDJSON line on the wire.

type TraceError

type TraceError struct {
	Message string `json:"message"`
	Kind    string `json:"kind,omitempty"`
}

TraceError describes a failed call or errored event.

type WindowInfo

type WindowInfo struct {
	ID          uint        `json:"id"`
	Name        string      `json:"name"`
	Width       int         `json:"width"`
	Height      int         `json:"height"`
	X           int         `json:"x"` // absolute desktop coordinates
	Y           int         `json:"y"`
	RelX        int         `json:"relX"` // position relative to current screen
	RelY        int         `json:"relY"`
	Border      Insets      `json:"border"` // window chrome thickness
	Focused     bool        `json:"focused"`
	Fullscreen  bool        `json:"fullscreen"`
	Maximised   bool        `json:"maximised"`
	Minimised   bool        `json:"minimised"`
	Resizable   bool        `json:"resizable"`
	IgnoreMouse bool        `json:"ignoreMouse"`
	Zoom        float64     `json:"zoom"`
	Screen      *ScreenInfo `json:"screen,omitempty"`
}

WindowInfo describes one live window.