libpf

package
v0.0.0-...-9bce22c Latest Latest
Warning

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

 Go to latest Published: Oct 28, 2024 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const SymbolNameUnknown = ""

SymbolNameUnknown is the value returned by SymbolMap functions when address has no symbol info.

View Source 
const SymbolValueInvalid = SymbolValue(0)

SymbolValueInvalid is the value returned by SymbolMap functions when symbol was not found.

Variables

View Source 
var InvalidAPMSpanID = APMSpanID{0, 0, 0, 0, 0, 0, 0, 0}
View Source 
var UnknownKernelFileID = NewFileID(math.MaxUint64-2, math.MaxUint64-2)

UnknownKernelFileID is used as 128-bit FileID when the host agent isn't able to derive a FileID for a kernel frame.

View Source 
var UnsymbolizedFileID = NewFileID(math.MaxUint64, math.MaxUint64)

UnsymbolizedFileID is used as 128-bit FileID when symbolization fails.

Functions

func AddJitter 

func AddJitter(baseDuration time.Duration, jitter float64) time.Duration

AddJitter adds +/- jitter (jitter is [0..1]) to baseDuration

func MapKeysToSlice 

func MapKeysToSlice[K comparable, V any](m map[K]V) []K

MapKeysToSlice creates a slice from a map's keys.

func MapSlice 

func MapSlice[T, V any](in []T, mapf func(T) V) []V

MapSlice returns a new slice by mapping given function over the input slice.

func MapValuesToSlice 

func MapValuesToSlice[K comparable, V any](m map[K]V) []V

MapValuesToSlice creates a slice from a map's values.

func NowAsUInt32 

func NowAsUInt32() uint32

NowAsUInt32 is a convenience function to avoid code repetition

func SleepWithJitter 

func SleepWithJitter(baseDuration time.Duration, jitter float64)

SleepWithJitter sleeps for baseDuration +/- jitter (jitter is [0..1])

func SleepWithJitterAndContext 

func SleepWithJitterAndContext(ctx context.Context, duration time.Duration, jitter float64) error

SleepWithJitterAndContext blocks for duration +/- jitter (jitter is [0..1]) or until ctx is canceled.

func SliceAllEqual 

func SliceAllEqual[T comparable](s []T, value T) bool

SliceAllEqual checks whether all items in a slice have a given value.

func SliceFrom 

func SliceFrom(data any) []byte

SliceFrom converts a Go struct pointer or slice to []byte to read data into

func SlicesEqual 

func SlicesEqual[T comparable](a, b []T) bool

SlicesEqual checks whether two slices are element-wise equal.

func WriteTempFile 

func WriteTempFile(data []byte, directory, prefix string) (string, error)

WriteTempFile writes a data buffer to a temporary file on the filesystem. It is the callers responsibility to clean up that file again. The function returns the filename if successful.

Types

type APMSpanID 

type APMSpanID [8]byte

type APMTraceID 

type APMTraceID [16]byte

type APMTransactionID 

type APMTransactionID = APMSpanID

type Address 

type Address uintptr

Address represents an address, or offset within a process

func (Address) Hash 

func (adr Address) Hash() uint64

Hash returns a 64 bits hash of the input.

func (Address) Hash32 

func (adr Address) Hash32() uint32

Hash32 returns a 32 bits hash of the input. It's main purpose is to be used as key for caching.

type AddressOrLineno 

type AddressOrLineno uint64

AddressOrLineno represents a line number in an interpreted file or an offset into a native file.

type FileID 

type FileID struct {
	basehash.Hash128
}

FileID is used for unique identifiers for files

func FileIDFromBase64 

func FileIDFromBase64(s string) (FileID, error)

FileIDFromBase64 converts a base64url encoded file ID into its binary representation. We store binary fields as keywords as base64 URL encoded strings. But when retrieving binary fields, ES sends them as base64 STD encoded strings.

func FileIDFromBytes 

func FileIDFromBytes(b []byte) (FileID, error)

FileIDFromBytes parses a byte slice into the internal data representation for a file ID.

func FileIDFromExecutableFile 

func FileIDFromExecutableFile(fileName string) (FileID, error)

FileIDFromExecutableFile opens an executable file and calculates the FileID for it. The caller is responsible pre-validate it as an executable file and that the algorithm described in FileIDFromExecutableReader is suitable.

func FileIDFromExecutableReader 

func FileIDFromExecutableReader(reader io.ReadSeeker) (FileID, error)

FileIDFromExecutableReader hashes portions of the contents of the reader in order to generate a system-independent identifier. The file is expected to be an executable file (ELF or PE) where the header and footer has enough data to make the file unique.

*** WARNING *** ANY CHANGE IN BEHAVIOR CAN EASILY BREAK OUR INFRASTRUCTURE, POSSIBLY MAKING THE ENTIRETY OF THE DEBUG INDEX OR FRAME METADATA WORTHLESS (BREAKING BACKWARDS COMPATIBILITY).

func FileIDFromKernelBuildID 

func FileIDFromKernelBuildID(buildID string) FileID

FileIDFromKernelBuildID returns the FileID of a kernel image or module, which consists of a hash of its GNU BuildID in hex string form. The hashing step is to ensure that the FileID remains an opaque concept to the end user.

func FileIDFromString 

func FileIDFromString(s string) (FileID, error)

FileIDFromString parses a hexadecimal notation of a file ID into the internal data representation.

func NewFileID 

func NewFileID(hi, lo uint64) FileID

func (FileID) Compare 

func (f FileID) Compare(other FileID) int

Compare returns an integer comparing two hashes lexicographically. The result will be 0 if f == other, -1 if f < other, and +1 if f > other.

func (FileID) Equal 

func (f FileID) Equal(other FileID) bool

func (FileID) Hash32 

func (f FileID) Hash32() uint32

Hash32 returns a 32 bits hash of the input. It's main purpose is to be used as key for caching.

func (FileID) Less 

func (f FileID) Less(other FileID) bool

func (FileID) Swapped 

func (f FileID) Swapped() FileID

Swapped creates a new FileID with swapped high and low part. This function is its own inverse, so it can be used for the opposite operation. This is mostly used to connect Linux kernel module and its debug file build IDs. This provides 2 properties:

  • FileIDs must be different between kernel files and their debug files.
  • A kernel FileID (debug and non-debug) must only depend on its GNU BuildID (see FileIDFromKernelBuildID), and can always be computed in the Host Agent or during indexing without external information.

type FrameID 

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

FrameID represents a frame as an address in an executable file or as a line in a source code file.

func NewFrameID 

func NewFrameID(fileID FileID, addressOrLineno AddressOrLineno) FrameID

NewFrameID creates a new FrameID from the fileId and address or line.

func NewFrameIDFromBytes 

func NewFrameIDFromBytes(bytes []byte) (FrameID, error)

NewFrameIDFromBytes creates a new FrameID from a byte array of length 24.

func NewFrameIDFromString 

func NewFrameIDFromString(frameEncoded string) (FrameID, error)

NewFrameIDFromString creates a new FrameID from its base64 string representation.

func (FrameID) AddressOrLine 

func (f FrameID) AddressOrLine() AddressOrLineno

AddressOrLine returns the addressOrLine part of the frameID.

func (*FrameID) AsIP 

func (f *FrameID) AsIP() net.IP

AsIP returns the FrameID as a net.IP type to be used for the PC range in profiling-symbols-*.

func (FrameID) Bytes 

func (f FrameID) Bytes() []byte

Bytes returns the frameid as byte sequence.

func (FrameID) EncodeTo 

func (f FrameID) EncodeTo(dst []byte)

EncodeTo encodes the frame ID into the base64 encoded representation and stores it in the provided destination byte array. The length of the destination must be at least EncodedLen().

func (FrameID) EncodedLen 

func (FrameID) EncodedLen() int

EncodedLen returns the length of the FrameID's base64 representation.

func (FrameID) FileID 

func (f FrameID) FileID() FileID

FileID returns the fileID part of the frameID.

func (FrameID) Hash 

func (f FrameID) Hash() uint64

Hash calculates a hash from the frameid. xxh3 is 4x faster than fnv.

func (FrameID) Hash32 

func (f FrameID) Hash32() uint32

Hash32 returns a 32 bits hash of the input. It's main purpose is to be used as key for caching.

func (FrameID) String 

func (f FrameID) String() string

String returns the base64 encoded representation.

type FrameMetadata 

type FrameMetadata struct {
	FileID         FileID
	AddressOrLine  AddressOrLineno
	LineNumber     SourceLineno
	FunctionOffset uint32
	FunctionName   string
	Filename       string
}

type FrameType 

type FrameType int

FrameType defines the type of frame. This usually corresponds to the interpreter type that emitted it, but can additionally contain meta-information like error frames.

A frame type can represent one of the following things:

  • A successfully unwound frame. This is represented simply as the `InterpreterType` ID.
  • A partial (non-critical failure), indicated by ORing the `InterpreterType` ID with the error bit.
  • A fatal failure that caused further unwinding to be aborted. This is indicated using the special value support.FrameMarkerAbort (0xFF). It thus also contains the error bit, but does not fit into the `InterpreterType` enum.
const (

	// PHPFrame identifies PHP interpreter frames.
	PHPFrame FrameType = support.FrameMarkerPHP
	// PHPJITFrame identifies PHP JIT interpreter frames.
	PHPJITFrame FrameType = support.FrameMarkerPHPJIT
	// PythonFrame identifies the Python interpreter frames.
	PythonFrame FrameType = support.FrameMarkerPython
	// NativeFrame identifies native frames.
	NativeFrame FrameType = support.FrameMarkerNative
	// KernelFrame identifies kernel frames.
	KernelFrame FrameType = support.FrameMarkerKernel
	// HotSpotFrame identifies Java HotSpot VM frames.
	HotSpotFrame FrameType = support.FrameMarkerHotSpot
	// RubyFrame identifies the Ruby interpreter frames.
	RubyFrame FrameType = support.FrameMarkerRuby
	// PerlFrame identifies the Perl interpreter frames.
	PerlFrame FrameType = support.FrameMarkerPerl
	// V8Frame identifies the V8 interpreter frames.
	V8Frame FrameType = support.FrameMarkerV8
	// DotnetFrame identifies the Dotnet interpreter frames.
	DotnetFrame FrameType = support.FrameMarkerDotnet
	// AbortFrame identifies frames that report that further unwinding was aborted due to an error.
	AbortFrame FrameType = support.FrameMarkerAbort
)

Convenience shorthands to create various frame types.

Code should not compare against the constants below directly, but instead use the provided methods to query the required information (IsError, Interpreter, ...) to improve forward compatibility and clarify intentions.

func FrameTypeFromString 

func FrameTypeFromString(name string) FrameType

func (FrameType) Error 

func (ty FrameType) Error() FrameType

Error adds the error bit into the frame type.

func (FrameType) Interpreter 

func (ty FrameType) Interpreter() InterpreterType

Interpreter returns the interpreter that produced the frame.

func (FrameType) IsError 

func (ty FrameType) IsError() bool

IsError checks whether the frame is an error frame.

func (FrameType) IsInterpType 

func (ty FrameType) IsInterpType(ity InterpreterType) bool

IsInterpType checks whether the frame type belongs to the given interpreter.

func (FrameType) String 

func (ty FrameType) String() string

String implements the Stringer interface.

type InterpreterType 

type InterpreterType int

InterpreterType variables can hold one of the interpreter type values defined below. 

const (
	// UnknownInterp signifies that the interpreter is unknown.
	UnknownInterp InterpreterType = support.FrameMarkerUnknown
	// PHP identifies the PHP interpreter.
	PHP InterpreterType = support.FrameMarkerPHP
	// PHPJIT identifies PHP JIT processes.
	PHPJIT InterpreterType = support.FrameMarkerPHPJIT
	// Python identifies the Python interpreter.
	Python InterpreterType = support.FrameMarkerPython
	// Native identifies native code.
	Native InterpreterType = support.FrameMarkerNative
	// Kernel identifies kernel code.
	Kernel InterpreterType = support.FrameMarkerKernel
	// HotSpot identifies the Java HotSpot VM.
	HotSpot InterpreterType = support.FrameMarkerHotSpot
	// Ruby identifies the Ruby interpreter.
	Ruby InterpreterType = support.FrameMarkerRuby
	// Perl identifies the Perl interpreter.
	Perl InterpreterType = support.FrameMarkerPerl
	// V8 identifies the V8 interpreter.
	V8 InterpreterType = support.FrameMarkerV8
	// Dotnet identifies the Dotnet interpreter.
	Dotnet InterpreterType = support.FrameMarkerDotnet
)
const (

	// APMInt identifies the pseudo-interpreter for the APM integration.
	APMInt InterpreterType = 0x100
)

Pseudo-interpreters without a corresponding frame type.

func InterpreterTypeFromString 

func InterpreterTypeFromString(name string) InterpreterType

func (InterpreterType) Frame 

func (i InterpreterType) Frame() FrameType

Frame converts the interpreter type into the corresponding frame type.

func (InterpreterType) String 

func (i InterpreterType) String() string

String converts the frame type int to the related string value to be displayed in the UI.

type PID 

type PID uint32

PID represent Unix Process ID (pid_t)

func (PID) Hash32 

func (p PID) Hash32() uint32

type Set 

type Set[T comparable] map[T]Void

Set is a convenience alias for a map with a `Void` key.

func SliceToSet 

func SliceToSet[T comparable](s []T) Set[T]

SliceToSet creates a set from a slice, deduplicating it.

func (Set[T]) ToSlice 

func (s Set[T]) ToSlice() []T

ToSlice converts the Set keys into a slice.

type SourceLineno 

type SourceLineno uint64

SourceLineno represents a line number within a source file. It is intended to be used for the source line numbers associated with offsets in native code, or for source line numbers in interpreted code.

type Symbol 

type Symbol struct {
	Name    SymbolName
	Address SymbolValue
	Size    int
}

Symbol represents the name of a symbol

type SymbolFinder 

type SymbolFinder interface {
	LookupSymbol(symbolName SymbolName) (*Symbol, error)

	LookupSymbolAddress(symbolName SymbolName) (SymbolValue, error)
}

SymbolFinder implements a way to find symbol data

type SymbolMap 

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

SymbolMap represents collections of symbols that can be resolved or reverse mapped

func NewSymbolMap 

func NewSymbolMap(capacity int) *SymbolMap

func (*SymbolMap) Add 

func (symmap *SymbolMap) Add(s Symbol)

Add a symbol to the map

func (*SymbolMap) Finalize 

func (symmap *SymbolMap) Finalize()

Finalize symbol map by sorting and constructing the nameToSymbol table after all symbols are inserted via Add() calls

func (*SymbolMap) Len 

func (symmap *SymbolMap) Len() int

Len returns the number of elements in the map.

func (*SymbolMap) LookupByAddress 

func (symmap *SymbolMap) LookupByAddress(val SymbolValue) (SymbolName, Address, bool)

LookupByAddress translates the address to a symbolic information. Return empty string and absolute address if it did not match any symbol.

func (*SymbolMap) LookupSymbol 

func (symmap *SymbolMap) LookupSymbol(symbolName SymbolName) (*Symbol, error)

LookupSymbol obtains symbol information. Returns nil and an error if not found.

func (*SymbolMap) LookupSymbolAddress 

func (symmap *SymbolMap) LookupSymbolAddress(symbolName SymbolName) (SymbolValue, error)

LookupSymbolAddress returns the address of a symbol. Returns SymbolValueInvalid and error if not found.

func (*SymbolMap) VisitAll 

func (symmap *SymbolMap) VisitAll(cb func(Symbol))

VisitAll calls the provided callback with all the symbols in the map.

type SymbolName 

type SymbolName string

SymbolName represents the name of a symbol

type SymbolValue 

type SymbolValue uint64

SymbolValue represents the value associated with a symbol, e.g. either an offset or an absolute address

type Trace 

type Trace struct {
	Files              []FileID
	Linenos            []AddressOrLineno
	FrameTypes         []FrameType
	MappingStart       []Address
	MappingEnd         []Address
	MappingFileOffsets []uint64
	Hash               TraceHash
}

Trace represents a stack trace. Each tuple (Files[i], Linenos[i]) represents a stack frame via the file ID and line number at the offset i in the trace. The information for the most recently called function is at offset 0.

func (*Trace) AppendFrame 

func (trace *Trace) AppendFrame(ty FrameType, file FileID, addrOrLine AddressOrLineno)

AppendFrame appends a frame to the columnar frame array without mapping information.

func (*Trace) AppendFrameFull 

func (trace *Trace) AppendFrameFull(ty FrameType, file FileID, addrOrLine AddressOrLineno,
	mappingStart Address, mappingEnd Address, mappingFileOffset uint64)

AppendFrameFull appends a frame with mapping info to the columnar frame array.

func (*Trace) AppendFrameID 

func (trace *Trace) AppendFrameID(ty FrameType, frameID FrameID)

AppendFrameID appends a frame to the columnar frame array without mapping information.

type TraceAndCounts 

type TraceAndCounts struct {
	Hash           TraceHash
	Timestamp      UnixTime64
	Count          uint16
	Comm           string
	PodName        string
	ContainerName  string
	APMServiceName string
}

type TraceHash 

type TraceHash struct {
	basehash.Hash128
}

TraceHash represents the unique hash of a trace

func NewTraceHash 

func NewTraceHash(hi, lo uint64) TraceHash

func TraceHashFromBytes 

func TraceHashFromBytes(b []byte) (TraceHash, error)

TraceHashFromBytes parses a byte slice of a trace hash into the internal data representation.

func TraceHashFromString 

func TraceHashFromString(s string) (TraceHash, error)

TraceHashFromString parses a byte slice of a trace hash into the internal data representation.

func (TraceHash) EncodeTo 

func (h TraceHash) EncodeTo(dst []byte)

EncodeTo encodes the hash into the base64 encoded representation and stores it in the provided destination byte array. The length of the destination must be at least EncodedLen().

func (TraceHash) EncodedLen 

func (TraceHash) EncodedLen() int

EncodedLen returns the length of the hash's base64 representation.

func (TraceHash) Equal 

func (h TraceHash) Equal(other TraceHash) bool

func (TraceHash) Hash32 

func (h TraceHash) Hash32() uint32

Hash32 returns a 32 bits hash of the input. It's main purpose is to be used for LRU caching.

func (TraceHash) Less 

func (h TraceHash) Less(other TraceHash) bool

type UnixTime32 

type UnixTime32 uint32

UnixTime32 is another type to represent seconds since epoch. In most cases 32bit time values are good enough until year 2106. Our time series database backend uses this type for TimeStamps as well, so there is no need to use a different type than uint32. Also, Go's semantics on map[time.Time] are particularly nasty footguns, and since the code is mostly dealing with UNIX timestamps, we may as well use uint32s instead. To restore some semblance of type safety, we declare a type alias here.

func (UnixTime32) MarshalJSON 

func (t UnixTime32) MarshalJSON() ([]byte, error)

type UnixTime64 

type UnixTime64 uint64

UnixTime64 represents nanoseconds or (reduced precision) seconds since epoch.

func (UnixTime64) MarshalJSON 

func (t UnixTime64) MarshalJSON() ([]byte, error)

func (UnixTime64) Unix 

func (t UnixTime64) Unix() int64

Unix returns the value as seconds since epoch.

type Void 

type Void struct{}

Void allows to use maps as sets without memory allocation for the values. From the "Go Programming Language": 

The struct type with no fields is called the empty struct, written struct{}. It has size zero
and carries no information but may be useful nonetheless. Some Go programmers
use it instead of bool as the value type of a map that represents a set, to emphasize
that only the keys are significant, but the space saving is marginal and the syntax more
cumbersome, so we generally avoid it.

Source Files

View all Source files

Directories

Path Synopsis
Package basehash provides basic types to implement hash identifiers.
 Package basehash provides basic types to implement hash identifiers.
Package hash provides the same hash primitives as used by the eBPF.
 Package hash provides the same hash primitives as used by the eBPF.
package pfelf implements functions for processing of ELF files and extracting data from them.
 package pfelf implements functions for processing of ELF files and extracting data from them.
Package xsync provides thin wrappers around locking primitives in an effort towards better documenting the relationship between locks and the data they protect.
 Package xsync provides thin wrappers around locking primitives in an effort towards better documenting the relationship between locks and the data they protect.

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.