systracer

README

SysTracer: Linux 系统活动跟踪器

SysTracer 是长亭所开发的，用于跟踪 Linux 内核的关键活动并产生事件的跟踪程序。

借助 Linux Tracing 技术和内核分析手段，SysTracer 可以进行被动且实时地跟踪。

Documentation

Overview

Package systracer is the framework of linux event tracing system developed by Chaitin Tech.

Index

• Variables
• type Condition
• type Event
• type Manager
  • func New(ctx context.Context, group *errgroup.Group, options ...Option) (Manager, error)
• type Option
  • func WithInstanceName(name string) Option
  • func WithLimitInterval(dur time.Duration) Option
  • func WithLogger(logger *zap.Logger) Option
  • func WithOptions(opts ...Option) Option
  • func WithTraceFSPath(path string) Option
• type ProbeEvent
• type ReturnEvent
• type StringAddr
• type Trace

Variables

var ErrBadTracePoint = errors.New("bad tracepoint")

ErrBadTracePoint is the error returned when the target trace point cannot be attached to.

Types

type Condition

type Condition struct{}

Condition is common embed field for defining an extra condition for current field.

type Event

type Event struct {
	TaskPID   uint32
	Timestamp time.Time
	// contains filtered or unexported fields
}

Event stores common event data made by all types of concrete tracing events. The format is defined by "<debugfs>/tracing/trace" file.

The comm field is ommitted out since it is always imcomplete (rendered as "<...>) and is not essentially required by all events.

type Manager

type Manager interface {
	// TraceKProbe creates either a kprobe (when handled
	// event is ProbeEvent) or a kretprobe (when handled
	// event is ReturnEvent).
	TraceKProbe(
		location string, handler interface{},
	) (Trace, <-chan struct{}, error)

	// TraceUProbe creates either a uprobe (when handled
	// event is ProbeEvent) or a uretprobe (when handled
	// event is ReturnEvent).
	TraceUProbe(
		library, location string, handler interface{},
	) (Trace, <-chan struct{}, error)
}

Manager is the manager of traces.

The manager is the monolithic consumer to read from trace pipe "<tracefs>/instances/<namespace>/trace_pipe" and generate events per registered events.

func New

func New(
	ctx context.Context, group *errgroup.Group, options ...Option,
) (Manager, error)

New will create an instance of the manager.

type Option

type Option func(*option)

Option to initialize the systrace subsystem.

func WithInstanceName

func WithInstanceName(name string) Option

WithInstanceName is the name of the trace instance. The default value is "systrace".

func WithLimitInterval

func WithLimitInterval(dur time.Duration) Option

WithLimitInterval specifies the interval of receiving event from trace pipe. Setting this value to 0 will disable the reception limit. The default value is 0.

func WithLogger

func WithLogger(logger *zap.Logger) Option

WithLogger specifies the logger for the manager. The default value is zap.L().

func WithOptions

func WithOptions(opts ...Option) Option

WithOptions aggregate a set of options together.

func WithTraceFSPath

func WithTraceFSPath(path string) Option

WithTraceFSPath is the path of the tracefs. The default value is "/sys/kernel/debug/tracing".

type ProbeEvent

type ProbeEvent struct {
	Event
}

ProbeEvent is the event triggered when touching any of the breakpoint inside a function.

type ReturnEvent

type ReturnEvent struct {
	Event
}

ReturnEvent is the event triggered when a return instruction in function is executed.

type StringAddr

type StringAddr struct {
	String string
	Addr   uint64
}

StringAddr is the special type used in the place of the string to fetch the address canary when decoding the string, when it is meaningful.

type Trace

type Trace interface {
	ID() uint64
	SetCondition(string) error
	SetEnabled(bool)
	GetDone() uint64
	GetLost() uint64
	Close()
}

Trace is a controlling handle for trace events.

The trace handle is initially not started to avoid deadlocking when used as collectors. The caller must manually activate them after their master thread has been initialized.

And the trace can be stopped at runtime, it is recommended to disable certain tracing when there's no subscribers and the master thread nned not to track the real time state with the trace.