src/cmd/vendor/github.com/google/pprof/doc/developer/profile.proto.md

This is a description of the profile.proto format.

# Overview

Profile.proto is a data representation for profile data. It is independent of
the type of data being collected and the sampling process used to collect that
data. On disk, it is represented as a gzip-compressed protocol buffer, described
at src/proto/profile.proto

A profile in this context refers to a collection of samples, each one
representing measurements performed at a certain point in the life of a job. A
sample associates a set of measurement values with a list of locations, commonly
representing the program call stack when the sample was taken.

Tools such as pprof analyze these samples and display this information in
multiple forms, such as identifying hottest locations, building graphical call
graphs or trees, etc.

# General structure of a profile

A profile is represented on a Profile message, which contain the following
fields:

* *sample*: A profile sample, with the values measured and the associated call
  stack as a list of location ids. Samples with identical call stacks can be
  merged by adding their respective values, element by element.
* *location*: A unique place in the program, commonly mapped to a single
  instruction address. It has a unique nonzero id, to be referenced from the
  samples. It contains source information in the form of lines, and a mapping id
  that points to a binary.
* *function*: A program function as defined in the program source. It has a
  unique nonzero id, referenced from the location lines. It contains a
  human-readable name for the function (eg a C++ demangled name), a system name
  (eg a C++ mangled name), the name of the corresponding source file, and other
  function attributes.
* *mapping*: A binary that is part of the program during the profile
  collection. It has a unique nonzero id, referenced from the locations. It
  includes details on how the binary was mapped during program execution. By
  convention the main program binary is the first mapping, followed by any
  shared libraries.
* *string_table*: All strings in the profile are represented as indices into
  this repeating field. The first string is empty, so index == 0 always
  represents the empty string.

# Measurement values

Measurement values are represented as 64-bit integers. The profile contains an
explicit description of each value represented, using a ValueType message, with
two fields:

* *Type*: A human-readable description of the type semantics. For example “cpu”
  to represent CPU time, “wall” or “time” for wallclock time, or “memory” for
  bytes allocated.
* *Unit*: A human-readable name of the unit represented by the 64-bit integer
  values. For example, it could be “nanoseconds” or “milliseconds” for a time
  value, or “bytes” or “megabytes” for a memory size. If this is just
  representing a number of events, the recommended unit name is “count”.

A profile can represent multiple measurements per sample, but all samples must
have the same number and type of measurements. The actual values are stored in
the Sample.value fields, each one described by the corresponding
Profile.sample_type field.

Some profiles have a uniform period that describe the granularity of the data
collection. For example, a CPU profile may have a period of 100ms, or a memory
allocation profile may have a period of 512kb. Profiles can optionally describe
such a value on the Profile.period and Profile.period_type fields. The profile
period is meant for human consumption and does not affect the interpretation of
the profiling data.

By convention, the first value on all profiles is the number of samples
collected at this call stack, with unit “count”. Because the profile does not
describe the sampling process beyond the optional period, it must include
unsampled values for all measurements. For example, a CPU profile could have
value[0] == samples, and value[1] == time in milliseconds.

## Locations, functions and mappings

Each sample lists the id of each location where the sample was collected, in
bottom-up order. Each location has an explicit unique nonzero integer id,
independent of its position in the profile, and holds additional information to
identify the corresponding source.

The profile source is expected to perform any adjustment required to the
locations in order to point to the calls in the stack. For example, if the
profile source extracts the call stack by walking back over the program stack,
it must adjust the instruction addresses to point to the actual call
instruction, instead of the instruction that each call will return to.

Sources usually generate profiles that fall into these two categories:

* *Unsymbolized profiles*: These only contain instruction addresses, and are to
  be symbolized by a separate tool. It is critical for each location to point to
  a valid mapping, which will provide the information required for
  symbolization. These are used for profiles of compiled languages, such as C++
  and Go.

* *Symbolized profiles*: These contain all the symbol information available for
  the profile. Mappings and instruction addresses are optional for symbolized
  locations. These are used for profiles of interpreted or jitted languages,
  such as Java or Python.  Also, the profile format allows the generation of
  mixed profiles, with symbolized and unsymbolized locations.

The symbol information is represented in the repeating lines field of the
Location message. A location has multiple lines if it reflects multiple program
sources, for example if representing inlined call stacks. Lines reference
functions by their unique nonzero id, and the source line number within the
source file listed by the function. A function contains the source attributes
for a function, including its name, source file, etc. Functions include both a
user and a system form of the name, for example to include C++ demangled and
mangled names. For profiles where only a single name exists, both should be set
to the same string.

Mappings are also referenced from locations by their unique nonzero id, and
include all information needed to symbolize addresses within the mapping. It
includes similar information to the Linux /proc/self/maps file. Locations
associated to a mapping should have addresses that land between the mapping
start and limit. Also, if available, mappings should include a build id to
uniquely identify the version of the binary being used.

## Labels

Samples optionally contain labels, which are annotations to discriminate samples
with identical locations. For example, a label can be used on a malloc profile
to indicate allocation size, so two samples on the same call stack with sizes
2MB and 4MB do not get merged into a single sample with two allocations and a
size of 6MB.

Labels can be string-based or numeric. They are represented by the Label
message, with a key identifying the label and either a string or numeric
value. For numeric labels, the measurement unit can be specified in the profile.
If no unit is specified and the key is "request" or "alignment",
then the units are assumed to be "bytes". Otherwise when no unit is specified
the key will be used as the measurement unit of the numeric value. All tags with
the same key should have the same unit.

## Keep and drop expressions

Some profile sources may have knowledge of locations that are uninteresting or
irrelevant. However, if symbolization is needed in order to identify these
locations, the profile source may not be able to remove them when the profile is
generated. The profile format provides a mechanism to identify these frames by
name, through regular expressions.

These expressions must match the function name in its entirety. Frames that
match Profile.drop\_frames will be dropped from the profile, along with any
frames below it. Frames that match Profile.keep\_frames will be kept, even if
they match drop\_frames.