process

Documentation

Index

• Constants
• Variables
• func SetSysProcAttribute(cmd *exec.Cmd)
• func Trace(start bool, pid IDType, description string, parentPID IDType, typ string)
• func TraceLogDisable(v bool)
• type Context
  • func GetContext(ctx context.Context) *Context
  • func (c *Context) GetPID() IDType
  • func (c *Context) GetParent() *Context
  • func (c *Context) Value(key any) any
• type Error
  • func (err *Error) Error() string
  • func (err *Error) Unwrap() error
• type FinishedFunc
• type IDType
  • func GetPID(ctx context.Context) IDType
  • func GetParentPID(ctx context.Context) IDType
• type Label
• type Manager
  • func GetManager() *Manager
  • func (pm *Manager) Add(ctx context.Context, description string, cancel context.CancelFunc, ...) (context.Context, IDType, FinishedFunc)
  • func (pm *Manager) AddContext(parent context.Context, description string) (ctx context.Context, cancel context.CancelFunc, finished FinishedFunc)
  • func (pm *Manager) AddContextTimeout(parent context.Context, timeout time.Duration, description string) (ctx context.Context, cancel context.CancelFunc, finshed FinishedFunc)
  • func (pm *Manager) AddTypedContext(parent context.Context, description, processType string, currentlyRunning bool) (ctx context.Context, cancel context.CancelFunc, finished FinishedFunc)
  • func (pm *Manager) Cancel(pid IDType)
  • func (pm *Manager) Exec(desc, cmdName string, args ...string) (string, string, error)
  • func (pm *Manager) ExecDir(ctx context.Context, timeout time.Duration, dir, desc, cmdName string, ...) (string, string, error)
  • func (pm *Manager) ExecDirEnv(ctx context.Context, timeout time.Duration, dir, desc string, env []string, ...) (string, string, error)
  • func (pm *Manager) ExecDirEnvStdIn(ctx context.Context, timeout time.Duration, dir, desc string, env []string, ...) (string, string, error)
  • func (pm *Manager) ExecTimeout(timeout time.Duration, desc, cmdName string, args ...string) (string, string, error)
  • func (pm *Manager) ProcessStacktraces(flat, noSystem bool) ([]*Process, int, int64, error)
  • func (pm *Manager) Processes(flat, noSystem bool) ([]*Process, int)
• type Process
• type Stack
• type StackEntry

Constants

const DescriptionPProfLabel = "process-description"

DescriptionPProfLabel is a label set on goroutines that have a process attached

const PIDPProfLabel = "pid"

PIDPProfLabel is a label set on goroutines that have a process attached

const PPIDPProfLabel = "ppid"

PPIDPProfLabel is a label set on goroutines that have a process attached

const ProcessTypePProfLabel = "process-type"

ProcessTypePProfLabel is a label set on goroutines that have a process attached

Variables

var (
	SystemProcessType  = "system"
	RequestProcessType = "request"
	NormalProcessType  = "normal"
	NoneProcessType    = "none"
)

var (

	// DefaultContext is the default context to run processing commands in
	DefaultContext = context.Background()
)

var ProcessContextKey any = "process-context"

ProcessContextKey is the key under which process contexts are stored

var (
	TraceCallback = defaultTraceCallback // this global can be overridden by particular logging packages - thus avoiding import cycles
)

Functions

func SetSysProcAttribute

func SetSysProcAttribute(cmd *exec.Cmd)

SetSysProcAttribute sets the common SysProcAttrs for commands

func Trace

func Trace(start bool, pid IDType, description string, parentPID IDType, typ string)

func TraceLogDisable

func TraceLogDisable(v bool)

TraceLogDisable disables (or revert the disabling) the trace log for the process lifecycle. eg: the logger system shouldn't print the trace log for themselves, that's cycle dependency (Logger -> ProcessManager -> TraceCallback -> Logger ...) Theoretically, such trace log should only be enabled when the logger system is ready with a proper level, so the default TraceCallback is a no-op.

Types

type Context

type Context struct {
	context.Context
	// contains filtered or unexported fields
}

Context is a wrapper around context.Context and contains the current pid for this context

func GetContext

func GetContext(ctx context.Context) *Context

GetContext will return a process context if one exists

func (*Context) GetPID

func (c *Context) GetPID() IDType

GetPID returns the PID for this context

func (*Context) GetParent

func (c *Context) GetParent() *Context

GetParent returns the parent process context (if any)

func (*Context) Value

func (c *Context) Value(key any) any

Value is part of the interface for context.Context. We mostly defer to the internal context - but we return this in response to the ProcessContextKey

type Error

type Error struct {
	PID         IDType
	Description string
	Err         error
	CtxErr      error
	Stdout      string
	Stderr      string
}

Error is a wrapped error describing the error results of Process Execution

func (*Error) Error

func (err *Error) Error() string

func (*Error) Unwrap

func (err *Error) Unwrap() error

Unwrap implements the unwrappable implicit interface for go1.13 Unwrap()

type FinishedFunc

type FinishedFunc = context.CancelFunc

FinishedFunc is a function that marks that the process is finished and can be removed from the process table - it is simply an alias for context.CancelFunc and is only for documentary purposes

type IDType

type IDType string

IDType is a pid type

func GetPID

func GetPID(ctx context.Context) IDType

GetPID returns the PID for this context

func GetParentPID

func GetParentPID(ctx context.Context) IDType

GetParentPID returns the ParentPID for this context

type Label

type Label struct {
	Name  string
	Value string
}

Label represents a pprof label assigned to goroutine stack

type Manager

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

Manager manages all processes and counts PIDs.

func GetManager

func GetManager() *Manager

GetManager returns a Manager and initializes one as singleton if there's none yet

func (*Manager) Add

func (pm *Manager) Add(ctx context.Context, description string, cancel context.CancelFunc, processType string, currentlyRunning bool) (context.Context, IDType, FinishedFunc)

Add create a new process

func (*Manager) AddContext

func (pm *Manager) AddContext(parent context.Context, description string) (ctx context.Context, cancel context.CancelFunc, finished FinishedFunc)

AddContext creates a new context and adds it as a process. Once the process is finished, finished must be called to remove the process from the process table. It should not be called until the process is finished but must always be called.

cancel should be used to cancel the returned context, however it will not remove the process from the process table. finished will cancel the returned context and remove it from the process table.

Most processes will not need to use the cancel function but there will be cases whereby you want to cancel the process but not immediately remove it from the process table.

func (*Manager) AddContextTimeout

func (pm *Manager) AddContextTimeout(parent context.Context, timeout time.Duration, description string) (ctx context.Context, cancel context.CancelFunc, finshed FinishedFunc)

AddContextTimeout creates a new context and add it as a process. Once the process is finished, finished must be called to remove the process from the process table. It should not be called until the process is finished but must always be called.

cancel should be used to cancel the returned context, however it will not remove the process from the process table. finished will cancel the returned context and remove it from the process table.

Most processes will not need to use the cancel function but there will be cases whereby you want to cancel the process but not immediately remove it from the process table.

func (*Manager) AddTypedContext

func (pm *Manager) AddTypedContext(parent context.Context, description, processType string, currentlyRunning bool) (ctx context.Context, cancel context.CancelFunc, finished FinishedFunc)

AddTypedContext creates a new context and adds it as a process. Once the process is finished, finished must be called to remove the process from the process table. It should not be called until the process is finished but must always be called.

cancel should be used to cancel the returned context, however it will not remove the process from the process table. finished will cancel the returned context and remove it from the process table.

Most processes will not need to use the cancel function but there will be cases whereby you want to cancel the process but not immediately remove it from the process table.

func (*Manager) Cancel

func (pm *Manager) Cancel(pid IDType)

Cancel a process in the ProcessManager.

func (*Manager) Exec

func (pm *Manager) Exec(desc, cmdName string, args ...string) (string, string, error)

Exec a command and use the default timeout.

func (*Manager) ExecDir

func (pm *Manager) ExecDir(ctx context.Context, timeout time.Duration, dir, desc, cmdName string, args ...string) (string, string, error)

ExecDir a command and use the default timeout.

func (*Manager) ExecDirEnv

func (pm *Manager) ExecDirEnv(ctx context.Context, timeout time.Duration, dir, desc string, env []string, cmdName string, args ...string) (string, string, error)

ExecDirEnv runs a command in given path and environment variables, and waits for its completion up to the given timeout (or DefaultTimeout if -1 is given). Returns its complete stdout and stderr outputs and an error, if any (including timeout)

func (*Manager) ExecDirEnvStdIn

func (pm *Manager) ExecDirEnvStdIn(ctx context.Context, timeout time.Duration, dir, desc string, env []string, stdIn io.Reader, cmdName string, args ...string) (string, string, error)

ExecDirEnvStdIn runs a command in given path and environment variables with provided stdIN, and waits for its completion up to the given timeout (or DefaultTimeout if timeout <= 0 is given). Returns its complete stdout and stderr outputs and an error, if any (including timeout)

func (*Manager) ExecTimeout

func (pm *Manager) ExecTimeout(timeout time.Duration, desc, cmdName string, args ...string) (string, string, error)

ExecTimeout a command and use a specific timeout duration.

func (*Manager) ProcessStacktraces

func (pm *Manager) ProcessStacktraces(flat, noSystem bool) ([]*Process, int, int64, error)

ProcessStacktraces gets the processes and stacktraces in a thread safe manner

func (*Manager) Processes

func (pm *Manager) Processes(flat, noSystem bool) ([]*Process, int)

Processes gets the processes in a thread safe manner

type Process

type Process struct {
	PID         IDType
	ParentPID   IDType
	Description string
	Start       time.Time
	Type        string

	Children []*Process `json:",omitempty"`
	Stacks   []*Stack   `json:",omitempty"`
}

A Process is a combined representation of a Process and a Stacktrace for the goroutines associated with it

type Stack

type Stack struct {
	Count       int64 // Number of goroutines with this stack trace
	Description string
	Labels      []*Label      `json:",omitempty"`
	Entry       []*StackEntry `json:",omitempty"`
}

Stack is a stacktrace relating to a goroutine. (Multiple goroutines may have the same stacktrace)

type StackEntry

type StackEntry struct {
	Function string
	File     string
	Line     int
}

StackEntry is an entry on a stacktrace