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 FillProcessInfo(p *Process) error
• func GetUnixSockForPid(pid int) string
• func Listen(opts Options) error
• func MakeProcessRequest(p *Process, signal byte, params []byte, f func(conn net.Conn) error) 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 MakeRequestToConn(conn net.Conn, signal byte, params []byte, f func(conn net.Conn) error) error
• func ParseGopsAddress(args []string) (string, error)
• type Options
• type Process
  • func GetGopsProcesses() ([]*Process, error)
  • func (p *Process) String() string

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)

	// AppInfo returns application information
	AppInfo = byte(0xa)

	// 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 FillProcessInfo

func FillProcessInfo(p *Process) 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 MakeProcessRequest

func MakeProcessRequest(p *Process, signal byte, params []byte, f func(conn net.Conn) error) error

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 MakeRequestToConn

func MakeRequestToConn(conn net.Conn, 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

	// AppId is a way to identify the host application
	AppId string

	// Type is the host application type
	AppType string

	// AppAlias is an alternate way to identify the host application
	AppAlias string

	// AppVersion is the application version
	AppVersion 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.

type Process

type Process struct {
	Pid         int
	Executable  string
	UnixSocket  string
	AppId       string
	AppType     string
	AppAlias    string
	AppVersion  string
	Contactable bool
}

func GetGopsProcesses

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

func (*Process) String

func (p *Process) String() string