agent

README

Ziti Agent Library

This library contains client and server code for adding IPC agent support to programs. It has built in support for collecting various debugging information, such as stackdumps and various pprof dumps. It can be used to update logrus logging levels and may also be extended for custom operations.

Documentation

Overview

Package agent provides hooks programs can register to retrieve diagnostics data by using the Ziti CLI.

Package agent contains signals used to communicate to the gops agents.

Index

• Constants
• Variables
• func Close()
• func GetGopsProcesses() ([]*gopsProc, error)
• func GetUnixSockForPid(pid int) string
• func Listen(opts Options) error
• func MakeRequest(addr string, signal byte, params []byte, out io.Writer) error
• func MakeRequestF(addr string, signal byte, params []byte, f func(conn net.Conn) error) error
• func ParseGopsAddress(args []string) (string, error)
• type Options

Constants

const (
	// StackTrace represents a command to print stack trace.
	StackTrace = byte(0x1)

	// GC runs the garbage collector.
	GC = byte(0x2)

	// MemStats reports memory stats.
	MemStats = byte(0x3)

	// Version prints the Go version.
	Version = byte(0x4)

	// HeapProfile starts `go tool pprof` with the current memory profile.
	HeapProfile = byte(0x5)

	// CPUProfile starts `go tool pprof` with the current CPU profile
	CPUProfile = byte(0x6)

	// Stats returns Go runtime statistics such as number of goroutines, GOMAXPROCS, and NumCPU.
	Stats = byte(0x7)

	// Trace starts the Go execution tracer, waits 5 seconds and launches the trace tool.
	Trace = byte(0x8)

	// BinaryDump returns running binary file.
	BinaryDump = byte(0x9)

	// SetGCPercent sets the garbage collection target percentage.
	SetGCPercent = byte(0x10)

	// SetLogLevel sets the logrus level
	SetLogLevel = byte(0x11)

	// CustomOp reserved for application specific operations
	CustomOp = byte(0x12)

	// SetChannelLogLevel sets the log level for a channel
	SetChannelLogLevel = byte(0x13)

	// ClearChannelLogLevel clears the log level for a channel
	ClearChannelLogLevel = byte(0x14)

	// CustomOpAsync reserved for application specific operations which execute async
	CustomOpAsync = byte(0x15)
)

Variables

var (
	Magic      = []byte{0x1, 0xB, 0xA, 0xD, 0xE, 0xC, 0xA, 0xF, 0xE, 0xF, 0x0, 0x0, 0xD}
	SockPrefix = "gops-agent"
)

Functions

func Close

func Close()

Close closes the agent, removing temporary files and closing the TCP listener. If no agent is listening, Close does nothing.

func GetGopsProcesses

func GetGopsProcesses() ([]*gopsProc, error)

func GetUnixSockForPid

func GetUnixSockForPid(pid int) string

func Listen

func Listen(opts Options) error

Listen starts the gops agent on a host process. Once agent started, users can use the advanced gops features. The agent will listen to Interrupt signals and exit the process, if you need to perform further work on the Interrupt signal use the options parameter to configure the agent accordingly.

Note: The agent exposes an endpoint via a TCP connection that can be used by any program on the system. Review your security requirements before starting the agent.

func MakeRequest

func MakeRequest(addr string, signal byte, params []byte, out io.Writer) error

func MakeRequestF

func MakeRequestF(addr string, signal byte, params []byte, f func(conn net.Conn) error) error

func ParseGopsAddress

func ParseGopsAddress(args []string) (string, error)

ParseGopsAddress tries to parse the target string, be it remote host:port or local process's PID or executable name

Types

type Options

type Options struct {
	// Addr is the host:port the agent will be listening at.
	// Optional.
	Addr string

	// ConfigDir is the directory to store the configuration file,
	// PID of the gops process, filename, port as well as content.
	// Optional.
	ConfigDir string

	// ShutdownCleanup automatically cleans up resources if the
	// running process receives an interrupt. Otherwise, users
	// can call Close before shutting down.
	// Optional.
	ShutdownCleanup *bool

	// Custom Operations
	CustomOps map[byte]func(conn net.Conn) error
}

Options allows configuring the started agent.