ambient

package
v0.8.12 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 6, 2026 License: BSD-3-Clause Imports: 22 Imported by: 0

Documentation

Overview

Package ambient implements the daemon mode that monitors all process execs system-wide and traces matching process trees based on configurable rules.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type FilterEngine 

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

FilterEngine evaluates process exec events against configured rules.

func NewFilterEngine 

func NewFilterEngine(rules []config.AmbientRule) *FilterEngine

NewFilterEngine creates a FilterEngine from the given rules.

func (*FilterEngine) Match 

func (f *FilterEngine) Match(comm string, isContainerInit bool) *config.AmbientRule

Match evaluates a process against all rules, returning the first match or nil. comm is the kernel process name (up to 16 chars, null-terminated). isContainerInit indicates the process is PID 1 in a non-root PID namespace.

type PIDTracker 

type PIDTracker interface {
	TrackPID(pid int) error
	UntrackPID(pid int) error
}

PIDTracker abstracts BPF PID tracking operations for testability.

type Processor 

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

Processor routes BPF events to the appropriate trace sessions in daemon mode. It implements the eventprocessor.EventHandler interface.

func NewProcessor 

func NewProcessor(filter *FilterEngine, manager *SessionManager) *Processor

NewProcessor creates a new daemon mode event processor.

func (*Processor) CleanupStalePending 

func (p *Processor) CleanupStalePending(maxAge time.Duration)

CleanupStalePending removes pending env/exit data older than the given threshold.

func (*Processor) HandleAncestorTrace added in v0.8.5 

func (p *Processor) HandleAncestorTrace(ev *bpf.AncestorTraceEvent) error

HandleAncestorTrace logs BPF's 16-level real_parent walk when no tracked ancestor was found. Correlate with the subsequent exec_unclaimed / weld_fail event by (pid, timestamp). One event per unclaimed exec or unclaimed fork — rare, so the log volume is bounded.

func (*Processor) HandleCloneSyscall added in v0.8.5 

func (p *Processor) HandleCloneSyscall(ev *bpf.CloneSyscallEvent) error

HandleCloneSyscall logs a clone/clone3 syscall with its flags decoded into human-readable names. Correlate with sched_process_fork by (tgid, timestamp) to see the flags that produced a given fork. No-op unless debug-log is active — the tracepoints themselves are ambient-mode-gated at the BPF level, but the log volume can still be high; we skip the field-prep work when nobody's listening.

func (*Processor) HandleEnvChunk 

func (p *Processor) HandleEnvChunk(chunk *bpf.EnvChunkEvent) error

HandleEnvChunk buffers environment chunks for pending processes or routes to sessions.

func (*Processor) HandleEnvVar 

func (p *Processor) HandleEnvVar(envVar *bpf.EnvVarEvent) error

HandleEnvVar buffers individual env var events for pending processes or routes to sessions.

func (*Processor) HandleEvent 

func (p *Processor) HandleEvent(event *bpf.Event) error

HandleEvent routes regular events (EXEC, EXIT, TCP, EXEC_CANDIDATE).

func (*Processor) SetDebugCoverageSampling added in v0.8.5 

func (p *Processor) SetDebugCoverageSampling(rate int)

SetDebugCoverageSampling configures the exec_unmatched sampling rate. rate=0 disables, rate=N logs every Nth unmatched exec. Safe to call before Start(); not safe to change while the daemon is running.

type SessionManager 

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

SessionManager manages the lifecycle of trace sessions in daemon mode.

func NewSessionManager 

func NewSessionManager(
	loader PIDTracker,
	tracer trace.Tracer,
	converter *timesync.Converter,
	resolver *reversedns.Resolver,
	metadataManager *procmeta.Manager,
	limits config.AmbientLimits,
) *SessionManager

NewSessionManager creates a new session manager.

func (*SessionManager) ActiveSessions 

func (m *SessionManager) ActiveSessions() int

ActiveSessions returns the count of active sessions.

func (*SessionManager) AddDescendant 

func (m *SessionManager) AddDescendant(pid, ppid uint32) *TraceSession

AddDescendant adds a child PID to its parent's session.

func (*SessionManager) CleanupStale 

func (m *SessionManager) CleanupStale()

CleanupStale removes sessions that have exceeded the timeout.

func (*SessionManager) CloseAllSessions added in v0.8.0 

func (m *SessionManager) CloseAllSessions() int

CloseAllSessions ends every active session's synthetic process.tree span and drops pending-starved sessions. Intended for daemon shutdown: without this, the OTEL BatchSpanProcessor's Shutdown only drains already-ended spans, and any still-active root span would be silently dropped.

func (*SessionManager) CreatePendingStarved added in v0.8.0 

func (m *SessionManager) CreatePendingStarved(rootPid uint32, rule *config.AmbientRule, rootMeta *procmeta.ProcessMetadata) error

CreatePendingStarved registers a pending context-starved session for the injector (rootPid). No OTEL span is started yet; materialization is deferred until a descendant's metadata resolves at least one of the rule's Expr expressions to a non-empty value.

Returns nil if session limits are already exhausted — in that case the caller should treat the match as dropped.

func (*SessionManager) CreateSession 

func (m *SessionManager) CreateSession(pid uint32, rule *config.AmbientRule, metadata *procmeta.ProcessMetadata) (*TraceSession, error)

CreateSession creates a new trace session for a matched process.

func (*SessionManager) DropPendingStarved added in v0.8.0 

func (m *SessionManager) DropPendingStarved(rootPid uint32)

DropPendingStarved removes pending state and untracks the root PID. Safe to call on a non-existent root (no-op).

func (*SessionManager) HandleExit 

func (m *SessionManager) HandleExit(pid uint32) (*TraceSession, bool)

HandleExit processes a PID exit, cleaning up session state. Returns true if the session is now complete (no more PIDs).

func (*SessionManager) HandleStarvedDescendantExec added in v0.8.0 

func (m *SessionManager) HandleStarvedDescendantExec(pid, ppid, uid uint32, timestamp uint64, metadata *procmeta.ProcessMetadata, comm string) (*TraceSession, bool)

HandleStarvedDescendantExec routes a descendant's exec event when its ancestor is a pending starved session. Returns:

  • (session, false): materialization just happened; caller should invoke session.HandleProcessExec for this descendant.
  • (nil, true): buffered; the caller should treat the exec as handled.
  • (nil, false): no pending starved ancestor; fall through to normal routing.

func (*SessionManager) HandleStarvedDescendantExit added in v0.8.8 

func (m *SessionManager) HandleStarvedDescendantExit(pid uint32, exitCode uint32, exitTime uint64, comm []byte) bool

HandleStarvedDescendantExit records that a pending-starved descendant has died before materialization. Returns true if the pid was in pending-starved state (and the exit was therefore handled), false otherwise — the caller falls through to its default "exit of an untracked pid" behavior in that case.

For exec-buffered descendants the exit info is stored alongside the buffered exec so materialization can replay both and close the span cleanly. For fork-only descendants (no exec data to replay) the pending entry is simply dropped: there is no span to emit and keeping the record around would only contribute a dead pid to session.pids at materialization. In either case the pid is removed from pendingStarvedByPid so future forks/execs on the same pid (if recycled) don't route here.

func (*SessionManager) HandleStarvedDescendantFork added in v0.8.0 

func (m *SessionManager) HandleStarvedDescendantFork(childPid, parentPid uint32) bool

HandleStarvedDescendantFork registers a fork'd child whose parent is in a pending starved session, so the child's later exec finds the pending session via pendingStarvedByPid lookup. Returns true if the child was associated with a pending starved session (caller should skip the normal descendant routing).

func (*SessionManager) MetadataManager 

func (m *SessionManager) MetadataManager() *procmeta.Manager

MetadataManager returns the metadata manager used by this session manager.

func (*SessionManager) PendingStarvedRootByPid added in v0.8.0 

func (m *SessionManager) PendingStarvedRootByPid(pid uint32) uint32

PendingStarvedRootByPid returns the root PID of a pending starved session that `pid` belongs to (directly or as a buffered descendant), or 0 if none.

func (*SessionManager) RouteByPID 

func (m *SessionManager) RouteByPID(pid uint32) *TraceSession

RouteByPID returns the session for the given PID, or nil.

type TraceSession 

type TraceSession struct {
	ID        string
	Rule      *config.AmbientRule
	RootPID   uint32
	CreatedAt time.Time
	Draining  bool // root has exited, waiting for descendants
	// contains filtered or unexported fields
}

TraceSession represents a single traced process tree in daemon mode.

func NewTraceSession 

func NewTraceSession(id string, rule *config.AmbientRule, rootPID uint32, formatter *output.OTELFormatter) *TraceSession

NewTraceSession creates a new trace session for the given root PID.

func (*TraceSession) AddPID 

func (s *TraceSession) AddPID(pid uint32)

AddPID adds a descendant PID to this session.

func (*TraceSession) EndSession added in v0.6.0 

func (s *TraceSession) EndSession(endTime time.Time)

EndSession finalizes the formatter's root "process.tree" span for this session.

func (*TraceSession) HandleProcessExec 

func (s *TraceSession) HandleProcessExec(pid, ppid, uid uint32, timestamp uint64, metadata *procmeta.ProcessMetadata) error

HandleProcessExec delegates to the session's formatter.

func (*TraceSession) HandleProcessExit 

func (s *TraceSession) HandleProcessExit(pid, ppid, uid uint32, exitCode uint32, timestamp uint64, comm []byte) error

HandleProcessExit delegates to the session's formatter.

func (*TraceSession) HandleTCPClose 

func (s *TraceSession) HandleTCPClose(pid uint32, skaddr uint64, saddr, daddr []byte, sport, dport, family uint16, timestamp uint64) error

HandleTCPClose delegates to the session's formatter.

func (*TraceSession) HandleTCPConnect 

func (s *TraceSession) HandleTCPConnect(pid uint32, skaddr uint64, saddr, daddr []byte, sport, dport, family uint16, timestamp uint64) error

HandleTCPConnect delegates to the session's formatter.

func (*TraceSession) HasPID 

func (s *TraceSession) HasPID(pid uint32) bool

HasPID returns whether the given PID belongs to this session.

func (*TraceSession) PIDList added in v0.8.4 

func (s *TraceSession) PIDList() []uint32

PIDList returns a snapshot of every PID currently in this session. Safe to call concurrently — returns a copy.

func (*TraceSession) PIDs 

func (s *TraceSession) PIDs() int

PIDs returns the number of PIDs in this session.

func (*TraceSession) RemovePID 

func (s *TraceSession) RemovePID(pid uint32) bool

RemovePID removes a PID and returns true if the session has no more PIDs.

func (*TraceSession) ResolvedTraceExprValue added in v0.8.1 

func (s *TraceSession) ResolvedTraceExprValue() string

ResolvedTraceExprValue returns the raw pre-hash value of the trace_id expression (or literal) at session creation. Diagnostic use only.

func (*TraceSession) ResolvedTraceID added in v0.8.1 

func (s *TraceSession) ResolvedTraceID() string

ResolvedTraceID returns the 32-char hex trace ID applied at StartSession, or "" if auto-generated. Diagnostic use only.

func (*TraceSession) ResolvedTraceSource added in v0.8.1 

func (s *TraceSession) ResolvedTraceSource() string

ResolvedTraceSource returns one of attributes.Source* describing how the trace_id was derived. Diagnostic use only.

func (*TraceSession) StartSession added in v0.6.0 

func (s *TraceSession) StartSession(ctx context.Context, metadata *procmeta.ProcessMetadata, startTime time.Time)

StartSession initializes the formatter's root "process.tree" span for this session.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.