profile

Documentation

Overview

Package profile provides a representation of profile.proto and methods to encode/decode profiles in this format.

Index

• func CompatibilizeSampleTypes(ps []*Profile) error
• type Function
• type Line
• type Location
• type Mapping
  • func ParseProcMaps(rd io.Reader) ([]*Mapping, error)
  • func (m *Mapping) Unsymbolizable() bool
• type Profile
  • func Merge(srcs []*Profile) (*Profile, error)
  • func Parse(r io.Reader) (*Profile, error)
  • func ParseData(data []byte) (*Profile, error)
  • func ParseUncompressed(data []byte) (*Profile, error)
  • func (p *Profile) Aggregate(inlineFrame, function, filename, linenumber, columnnumber, address bool) error
  • func (p *Profile) CheckValid() error
  • func (p *Profile) Compact() *Profile
  • func (p *Profile) Copy() *Profile
  • func (p *Profile) FilterSamplesByName(focus, ignore, hide, show *regexp.Regexp) (fm, im, hm, hnm bool)
  • func (p *Profile) FilterSamplesByTag(focus, ignore TagMatch) (fm, im bool)
  • func (p *Profile) FilterTagsByName(show, hide *regexp.Regexp) (sm, hm bool)
  • func (p *Profile) HasFileLines() bool
  • func (p *Profile) HasFunctions() bool
  • func (p *Profile) Normalize(pb *Profile) error
  • func (p *Profile) NumLabelUnits() (map[string]string, map[string][]string)
  • func (p *Profile) ParseMemoryMap(rd io.Reader) error
  • func (p *Profile) ParseMemoryMapFromScanner(s *bufio.Scanner) error
  • func (p *Profile) Prune(dropRx, keepRx *regexp.Regexp)
  • func (p *Profile) PruneFrom(dropRx *regexp.Regexp)
  • func (p *Profile) RemoveLabel(key string)
  • func (p *Profile) RemoveNumLabel(key string)
  • func (p *Profile) RemoveUninteresting() error
  • func (p *Profile) SampleIndexByName(sampleIndex string) (int, error)
  • func (p *Profile) Scale(ratio float64)
  • func (p *Profile) ScaleN(ratios []float64) error
  • func (p *Profile) SetLabel(key string, value []string)
  • func (p *Profile) SetNumLabel(key string, value []int64, unit []string)
  • func (p *Profile) ShowFrom(showFrom *regexp.Regexp) (matched bool)
  • func (p *Profile) String() string
  • func (p *Profile) Write(w io.Writer) error
  • func (p *Profile) WriteUncompressed(w io.Writer) error
• type Sample
  • func (s *Sample) DiffBaseSample() bool
  • func (s *Sample) HasLabel(key, value string) bool
• type TagMatch
• type ValueType

Functions

func CompatibilizeSampleTypes

func CompatibilizeSampleTypes(ps []*Profile) error

CompatibilizeSampleTypes makes profiles compatible to be compared/merged. It keeps sample types that appear in all profiles only and drops/reorders the sample types as necessary.

In the case of sample types order is not the same for given profiles the order is derived from the first profile.

Profiles are modified in-place.

It returns an error if the sample type's intersection is empty.

Types

type Function

type Function struct {
	ID         uint64
	Name       string
	SystemName string
	Filename   string
	StartLine  int64
	// contains filtered or unexported fields
}

Function corresponds to Profile.Function

type Line

type Line struct {
	Function *Function
	Line     int64
	Column   int64
	// contains filtered or unexported fields
}

Line corresponds to Profile.Line

type Location

type Location struct {
	ID       uint64
	Mapping  *Mapping
	Address  uint64
	Line     []Line
	IsFolded bool
	// contains filtered or unexported fields
}

Location corresponds to Profile.Location

type Mapping

type Mapping struct {
	ID              uint64
	Start           uint64
	Limit           uint64
	Offset          uint64
	File            string
	BuildID         string
	HasFunctions    bool
	HasFilenames    bool
	HasLineNumbers  bool
	HasInlineFrames bool

	// Name of the kernel relocation symbol ("_text" or "_stext"), extracted from File.
	// For linux kernel mappings generated by some tools, correct symbolization depends
	// on knowing which of the two possible relocation symbols was used for `Start`.
	// This is given to us as a suffix in `File` (e.g. "[kernel.kallsyms]_stext").
	//
	// Note, this public field is not persisted in the proto. For the purposes of
	// copying / merging / hashing profiles, it is considered subsumed by `File`.
	KernelRelocationSymbol string
	// contains filtered or unexported fields
}

Mapping corresponds to Profile.Mapping

func ParseProcMaps

func ParseProcMaps(rd io.Reader) ([]*Mapping, error)

ParseProcMaps parses a memory map in the format of /proc/self/maps. ParseMemoryMap should be called after setting on a profile to associate locations to the corresponding mapping based on their address.

func (*Mapping) Unsymbolizable

func (m *Mapping) Unsymbolizable() bool

Unsymbolizable returns true if a mapping points to a binary for which locations can't be symbolized in principle, at least now. Examples are "[vdso]", "[vsyscall]" and some others, see the code.

type Profile

type Profile struct {
	SampleType        []*ValueType
	DefaultSampleType string
	Sample            []*Sample
	Mapping           []*Mapping
	Location          []*Location
	Function          []*Function
	Comments          []string
	DocURL            string

	DropFrames string
	KeepFrames string

	TimeNanos     int64
	DurationNanos int64
	PeriodType    *ValueType
	Period        int64
	// contains filtered or unexported fields
}

Profile is an in-memory representation of profile.proto.

func Merge

func Merge(srcs []*Profile) (*Profile, error)

Merge merges all the profiles in profs into a single Profile. Returns a new profile independent of the input profiles. The merged profile is compacted to eliminate unused samples, locations, functions and mappings. Profiles must have identical profile sample and period types or the merge will fail. profile.Period of the resulting profile will be the maximum of all profiles, and profile.TimeNanos will be the earliest nonzero one. Merges are associative with the caveat of the first profile having some specialization in how headers are combined. There may be other subtleties now or in the future regarding associativity.

func Parse

func Parse(r io.Reader) (*Profile, error)

Parse parses a profile and checks for its validity. The input may be a gzip-compressed encoded protobuf or one of many legacy profile formats which may be unsupported in the future.

func ParseData

func ParseData(data []byte) (*Profile, error)

ParseData parses a profile from a buffer and checks for its validity.

func ParseUncompressed

func ParseUncompressed(data []byte) (*Profile, error)

ParseUncompressed parses an uncompressed protobuf into a profile.

func (*Profile) Aggregate

func (p *Profile) Aggregate(inlineFrame, function, filename, linenumber, columnnumber, address bool) error

Aggregate merges the locations in the profile into equivalence classes preserving the request attributes. It also updates the samples to point to the merged locations.

func (*Profile) CheckValid

func (p *Profile) CheckValid() error

CheckValid tests whether the profile is valid. Checks include, but are not limited to:

• len(Profile.Sample[n].value) == len(Profile.value_unit)
• Sample.id has a corresponding Profile.Location

func (*Profile) Compact

func (p *Profile) Compact() *Profile

Compact performs garbage collection on a profile to remove any unreferenced fields. This is useful to reduce the size of a profile after samples or locations have been removed.

func (*Profile) Copy

func (p *Profile) Copy() *Profile

Copy makes a fully independent copy of a profile.

func (*Profile) FilterSamplesByName

func (p *Profile) FilterSamplesByName(focus, ignore, hide, show *regexp.Regexp) (fm, im, hm, hnm bool)

FilterSamplesByName filters the samples in a profile and only keeps samples where at least one frame matches focus but none match ignore. Returns true is the corresponding regexp matched at least one sample.

func (*Profile) FilterSamplesByTag

func (p *Profile) FilterSamplesByTag(focus, ignore TagMatch) (fm, im bool)

FilterSamplesByTag removes all samples from the profile, except those that match focus and do not match the ignore regular expression.

func (*Profile) FilterTagsByName

func (p *Profile) FilterTagsByName(show, hide *regexp.Regexp) (sm, hm bool)

FilterTagsByName filters the tags in a profile and only keeps tags that match show and not hide.

func (*Profile) HasFileLines

func (p *Profile) HasFileLines() bool

HasFileLines determines if all locations in this profile have symbolized file and line number information.

func (*Profile) HasFunctions

func (p *Profile) HasFunctions() bool

HasFunctions determines if all locations in this profile have symbolized function information.

func (*Profile) Normalize

func (p *Profile) Normalize(pb *Profile) error

Normalize normalizes the source profile by multiplying each value in profile by the ratio of the sum of the base profile's values of that sample type to the sum of the source profile's value of that sample type.

func (*Profile) NumLabelUnits

func (p *Profile) NumLabelUnits() (map[string]string, map[string][]string)

NumLabelUnits returns a map of numeric label keys to the units associated with those keys and a map of those keys to any units that were encountered but not used. Unit for a given key is the first encountered unit for that key. If multiple units are encountered for values paired with a particular key, then the first unit encountered is used and all other units are returned in sorted order in map of ignored units. If no units are encountered for a particular key, the unit is then inferred based on the key.

func (*Profile) ParseMemoryMap

func (p *Profile) ParseMemoryMap(rd io.Reader) error

ParseMemoryMap parses a memory map in the format of /proc/self/maps, and overrides the mappings in the current profile. It renumbers the samples and locations in the profile correspondingly.

func (*Profile) ParseMemoryMapFromScanner

func (p *Profile) ParseMemoryMapFromScanner(s *bufio.Scanner) error

ParseMemoryMapFromScanner parses a memory map in the format of /proc/self/maps or a variety of legacy format, and overrides the mappings in the current profile. It renumbers the samples and locations in the profile correspondingly.

func (*Profile) Prune

func (p *Profile) Prune(dropRx, keepRx *regexp.Regexp)

Prune removes all nodes beneath a node matching dropRx, and not matching keepRx. If the root node of a Sample matches, the sample will have an empty stack.

func (*Profile) PruneFrom

func (p *Profile) PruneFrom(dropRx *regexp.Regexp)

PruneFrom removes all nodes beneath the lowest node matching dropRx, not including itself.

Please see the example below to understand this method as well as the difference from Prune method.

A sample contains Location of [A,B,C,B,D] where D is the top frame and there's no inline.

PruneFrom(A) returns [A,B,C,B,D] because there's no node beneath A. Prune(A, nil) returns [B,C,B,D] by removing A itself.

PruneFrom(B) returns [B,C,B,D] by removing all nodes beneath the first B when scanning from the bottom. Prune(B, nil) returns [D] because a matching node is found by scanning from the root.

func (*Profile) RemoveLabel

func (p *Profile) RemoveLabel(key string)

RemoveLabel removes all labels associated with the specified key for all samples in the profile.

func (*Profile) RemoveNumLabel

func (p *Profile) RemoveNumLabel(key string)

RemoveNumLabel removes all numerical labels associated with the specified key for all samples in the profile.

func (*Profile) RemoveUninteresting

func (p *Profile) RemoveUninteresting() error

RemoveUninteresting prunes and elides profiles using built-in tables of uninteresting function names.

func (*Profile) SampleIndexByName

func (p *Profile) SampleIndexByName(sampleIndex string) (int, error)

SampleIndexByName returns the appropriate index for a value of sample index. If numeric, it returns the number, otherwise it looks up the text in the profile sample types.

func (*Profile) Scale

func (p *Profile) Scale(ratio float64)

Scale multiplies all sample values in a profile by a constant and keeps only samples that have at least one non-zero value.

func (*Profile) ScaleN

func (p *Profile) ScaleN(ratios []float64) error

ScaleN multiplies each sample values in a sample by a different amount and keeps only samples that have at least one non-zero value.

func (*Profile) SetLabel

func (p *Profile) SetLabel(key string, value []string)

SetLabel sets the specified key to the specified value for all samples in the profile.

func (*Profile) SetNumLabel

func (p *Profile) SetNumLabel(key string, value []int64, unit []string)

SetNumLabel sets the specified key to the specified value for all samples in the profile. "unit" is a slice that describes the units that each corresponding member of "values" is measured in (e.g. bytes or seconds). If there is no relevant unit for a given value, that member of "unit" should be the empty string. "unit" must either have the same length as "value", or be nil.

func (*Profile) ShowFrom

func (p *Profile) ShowFrom(showFrom *regexp.Regexp) (matched bool)

ShowFrom drops all stack frames above the highest matching frame and returns whether a match was found. If showFrom is nil it returns false and does not modify the profile.

Example: consider a sample with frames [A, B, C, B], where A is the root. ShowFrom(nil) returns false and has frames [A, B, C, B]. ShowFrom(A) returns true and has frames [A, B, C, B]. ShowFrom(B) returns true and has frames [B, C, B]. ShowFrom(C) returns true and has frames [C, B]. ShowFrom(D) returns false and drops the sample because no frames remain.

func (*Profile) String

func (p *Profile) String() string

String dumps a text representation of a profile. Intended mainly for debugging purposes.

func (*Profile) Write

func (p *Profile) Write(w io.Writer) error

Write writes the profile as a gzip-compressed marshaled protobuf.

func (*Profile) WriteUncompressed

func (p *Profile) WriteUncompressed(w io.Writer) error

WriteUncompressed writes the profile as a marshaled protobuf.

type Sample

type Sample struct {
	Location []*Location
	Value    []int64
	// Label is a per-label-key map to values for string labels.
	//
	// In general, having multiple values for the given label key is strongly
	// discouraged - see docs for the sample label field in profile.proto.  The
	// main reason this unlikely state is tracked here is to make the
	// decoding->encoding roundtrip not lossy. But we expect that the value
	// slices present in this map are always of length 1.
	Label map[string][]string
	// NumLabel is a per-label-key map to values for numeric labels. See a note
	// above on handling multiple values for a label.
	NumLabel map[string][]int64
	// NumUnit is a per-label-key map to the unit names of corresponding numeric
	// label values. The unit info may be missing even if the label is in
	// NumLabel, see the docs in profile.proto for details. When the value is
	// slice is present and not nil, its length must be equal to the length of
	// the corresponding value slice in NumLabel.
	NumUnit map[string][]string
	// contains filtered or unexported fields
}

Sample corresponds to Profile.Sample

func (*Sample) DiffBaseSample

func (s *Sample) DiffBaseSample() bool

DiffBaseSample returns true if a sample belongs to the diff base and false otherwise.

func (*Sample) HasLabel

func (s *Sample) HasLabel(key, value string) bool

HasLabel returns true if a sample has a label with indicated key and value.

type TagMatch

type TagMatch func(s *Sample) bool

TagMatch selects tags for filtering

type ValueType

type ValueType struct {
	Type string // cpu, wall, inuse_space, etc
	Unit string // seconds, nanoseconds, bytes, etc
	// contains filtered or unexported fields
}

ValueType corresponds to Profile.ValueType