Documentation

Overview

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

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section 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
      	// 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
          	// 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
                
                	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, 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) 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) 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    map[string][]string
                                                                            	NumLabel map[string][]int64
                                                                            	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