package opentelemetry.proto.profiles.v1experimental

Get desktop application:
View/edit binary Protocol Buffers messages

Specifies the method of aggregating metric values, either DELTA (change since last report) or CUMULATIVE (total since a fixed start time).

Used in: ValueType

• AGGREGATION_TEMPORALITY_UNSPECIFIED = 0

  UNSPECIFIED is the default AggregationTemporality, it MUST not be used.

• AGGREGATION_TEMPORALITY_DELTA = 1

  * DELTA is an AggregationTemporality for a profiler which reports changes since last report time. Successive metrics contain aggregation of values from continuous and non-overlapping intervals. The values for a DELTA metric are based only on the time interval associated with one measurement cycle. There is no dependency on previous measurements like is the case for CUMULATIVE metrics. For example, consider a system measuring the number of requests that it receives and reports the sum of these requests every second as a DELTA metric: 1. The system starts receiving at time=t_0. 2. A request is received, the system measures 1 request. 3. A request is received, the system measures 1 request. 4. A request is received, the system measures 1 request. 5. The 1 second collection cycle ends. A metric is exported for the number of requests received over the interval of time t_0 to t_0+1 with a value of 3. 6. A request is received, the system measures 1 request. 7. A request is received, the system measures 1 request. 8. The 1 second collection cycle ends. A metric is exported for the number of requests received over the interval of time t_0+1 to t_0+2 with a value of 2.

• AGGREGATION_TEMPORALITY_CUMULATIVE = 2

  * CUMULATIVE is an AggregationTemporality for a profiler which reports changes since a fixed start time. This means that current values of a CUMULATIVE metric depend on all previous measurements since the start time. Because of this, the sender is required to retain this state in some form. If this state is lost or invalidated, the CUMULATIVE metric values MUST be reset and a new fixed start time following the last reported measurement time sent MUST be used. For example, consider a system measuring the number of requests that it receives and reports the sum of these requests every second as a CUMULATIVE metric: 1. The system starts receiving at time=t_0. 2. A request is received, the system measures 1 request. 3. A request is received, the system measures 1 request. 4. A request is received, the system measures 1 request. 5. The 1 second collection cycle ends. A metric is exported for the number of requests received over the interval of time t_0 to t_0+1 with a value of 3. 6. A request is received, the system measures 1 request. 7. A request is received, the system measures 1 request. 8. The 1 second collection cycle ends. A metric is exported for the number of requests received over the interval of time t_0 to t_0+2 with a value of 5. 9. The system experiences a fault and loses state. 10. The system recovers and resumes receiving at time=t_1. 11. A request is received, the system measures 1 request. 12. The 1 second collection cycle ends. A metric is exported for the number of requests received over the interval of time t_1 to t_1+1 with a value of 1. Note: Even though, when reporting changes since last report time, using CUMULATIVE is valid, it is not recommended.

Represents a mapping between Attribute Keys and Units.

Used in: Profile

• int64 attribute_key = 1

  Index into string table.

• int64 unit = 2

  Index into string table.

Indicates the semantics of the build_id field.

Used in: Mapping

• BUILD_ID_LINKER = 0

  Linker-generated build ID, stored in the ELF binary notes.

• BUILD_ID_BINARY_HASH = 1

  Build ID based on the content hash of the binary. Currently no particular hashing approach is standardized, so a given producer needs to define it themselves and thus unlike BUILD_ID_LINKER this kind of hash is producer-specific. We may choose to provide a standardized stable hash recommendation later.

Describes a function, including its human-readable name, system name, source file, and starting line number in the source.

Used in: Profile

• uint64 id = 1

  Unique nonzero id for the function. [deprecated]

• int64 name = 2

  Name of the function, in human-readable form if available.

  Index into string table

• int64 system_name = 3

  Name of the function, as identified by the system. For instance, it can be a C++ mangled name.

  Index into string table

• int64 filename = 4

  Source file containing the function.

  Index into string table

• int64 start_line = 5

  Line number in source file.

Provides additional context for a sample, such as thread ID or allocation size, with optional units. [deprecated]

Used in: Sample

• int64 key = 1

  Index into string table

• int64 str = 2

  At most one of the following must be present

  Index into string table

• int64 num = 3

• int64 num_unit = 4

  Should only be present when num is present. Specifies the units of num. Use arbitrary string (for example, "requests") as a custom count unit. If no unit is specified, consumer may apply heuristic to deduce the unit. Consumers may also interpret units like "bytes" and "kilobytes" as memory units and units like "seconds" and "nanoseconds" as time units, and apply appropriate unit conversions to these.

  Index into string table

Details a specific line in a source code, linked to a function.

Used in: Location

• uint64 function_index = 1

  The index of the corresponding profile.Function for this line.

• int64 line = 2

  Line number in source code.

• int64 column = 3

  Column number in source code.

A pointer from a profile Sample to a trace Span. Connects a profile sample to a trace span, identified by unique trace and span IDs.

Used in: Profile

• bytes trace_id = 1

  A unique identifier of a trace that this linked span is part of. The ID is a 16-byte array.

• bytes span_id = 2

  A unique identifier for the linked span. The ID is an 8-byte array.

Describes function and line table debug information.

Used in: Profile

• uint64 id = 1

  Unique nonzero id for the location. A profile could use instruction addresses or any integer sequence as ids. [deprecated]

• uint64 mapping_index = 2

  The index of the corresponding profile.Mapping for this location. It can be unset if the mapping is unknown or not applicable for this profile type.

• uint64 address = 3

  The instruction address for this location, if available. It should be within [Mapping.memory_start...Mapping.memory_limit] for the corresponding mapping. A non-leaf address may be in the middle of a call instruction. It is up to display tools to find the beginning of the instruction if necessary.

• repeated Line line = 4

  Multiple line indicates this location has inlined functions, where the last entry represents the caller into which the preceding entries were inlined. E.g., if memcpy() is inlined into printf: line[0].function_name == "memcpy" line[1].function_name == "printf"

• bool is_folded = 5

  Provides an indication that multiple symbols map to this location's address, for example due to identical code folding by the linker. In that case the line information above represents one of the multiple symbols. This field must be recomputed when the symbolization state of the profile changes.

• uint32 type_index = 6

  Type of frame (e.g. kernel, native, python, hotspot, php). Index into string table.

• repeated uint64 attributes = 7

  References to attributes in Profile.attribute_table. [optional]

Describes the mapping of a binary in memory, including its address range, file offset, and metadata like build ID

Used in: Profile

• uint64 id = 1

  Unique nonzero id for the mapping. [deprecated]

• uint64 memory_start = 2

  Address at which the binary (or DLL) is loaded into memory.

• uint64 memory_limit = 3

  The limit of the address range occupied by this mapping.

• uint64 file_offset = 4

  Offset in the binary that corresponds to the first mapped address.

• int64 filename = 5

  The object this entry is loaded from. This can be a filename on disk for the main binary and shared libraries, or virtual abstractions like "[vdso]".

  Index into string table

• int64 build_id = 6

  A string that uniquely identifies a particular program version with high probability. E.g., for binaries generated by GNU tools, it could be the contents of the .note.gnu.build-id field.

  Index into string table

• BuildIdKind build_id_kind = 11

  Specifies the kind of build id. See BuildIdKind enum for more details [optional]

• repeated uint64 attributes = 12

  References to attributes in Profile.attribute_table. [optional]

• bool has_functions = 7

  The following fields indicate the resolution of symbolic info.

• bool has_filenames = 8

• bool has_line_numbers = 9

• bool has_inline_frames = 10

Represents a complete profile, including sample types, samples, mappings to binaries, locations, functions, string table, and additional metadata.

Used in: ProfileContainer

• repeated ValueType sample_type = 1

  A description of the samples associated with each Sample.value. For a cpu profile this might be: [["cpu","nanoseconds"]] or [["wall","seconds"]] or [["syscall","count"]] For a heap profile, this might be: [["allocations","count"], ["space","bytes"]], If one of the values represents the number of events represented by the sample, by convention it should be at index 0 and use sample_type.unit == "count".

• repeated Sample sample = 2

  The set of samples recorded in this profile.

• repeated Mapping mapping = 3

  Mapping from address ranges to the image/binary/library mapped into that address range. mapping[0] will be the main binary.

• repeated Location location = 4

  Locations referenced by samples via location_indices.

• repeated int64 location_indices = 15

  Array of locations referenced by samples.

• repeated Function function = 5

  Functions referenced by locations.

• repeated common.v1.KeyValue attribute_table = 16

  Lookup table for attributes.

• repeated AttributeUnit attribute_units = 17

  Represents a mapping between Attribute Keys and Units.

• repeated Link link_table = 18

  Lookup table for links.

• repeated string string_table = 6

  A common table for strings referenced by various messages. string_table[0] must always be "".

• int64 drop_frames = 7

  frames with Function.function_name fully matching the following regexp will be dropped from the samples, along with their successors.

  Index into string table.

• int64 keep_frames = 8

  frames with Function.function_name fully matching the following regexp will be kept, even if it matches drop_frames.

  Index into string table.

• int64 time_nanos = 9

  Time of collection (UTC) represented as nanoseconds past the epoch.

• int64 duration_nanos = 10

  Duration of the profile, if a duration makes sense.

• optional ValueType period_type = 11

  The kind of events between sampled occurrences. e.g [ "cpu","cycles" ] or [ "heap","bytes" ]

• int64 period = 12

  The number of events between sampled occurrences.

• repeated int64 comment = 13

  Free-form text associated with the profile. The text is displayed as is to the user by the tools that read profiles (e.g. by pprof). This field should not be used to store any machine-readable information, it is only for human-friendly content. The profile must stay functional if this field is cleaned.

  Indices into string table.

• int64 default_sample_type = 14

  Index into the string table of the type of the preferred sample value. If unset, clients should default to the last sample value.

A ProfileContainer represents a single profile. It wraps pprof profile with OpenTelemetry specific metadata.

Used in: ScopeProfiles

• bytes profile_id = 1

  A globally unique identifier for a profile. The ID is a 16-byte array. An ID with all zeroes is considered invalid. This field is required.

• fixed64 start_time_unix_nano = 2

  start_time_unix_nano is the start time of the profile. Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970. This field is semantically required and it is expected that end_time >= start_time.

• fixed64 end_time_unix_nano = 3

  end_time_unix_nano is the end time of the profile. Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970. This field is semantically required and it is expected that end_time >= start_time.

• repeated common.v1.KeyValue attributes = 4

  attributes is a collection of key/value pairs. Note, global attributes like server name can be set using the resource API. Examples of attributes: "/http/user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36" "/http/server_latency": 300 "abc.com/myattribute": true "abc.com/score": 10.239 The OpenTelemetry API specification further restricts the allowed value types: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#attribute Attribute keys MUST be unique (it is not allowed to have more than one attribute with the same key).

• uint32 dropped_attributes_count = 5

  dropped_attributes_count is the number of attributes that were discarded. Attributes can be discarded because their keys are too long or because there are too many attributes. If this value is 0, then no attributes were dropped.

• string original_payload_format = 6

  Specifies format of the original payload. Common values are defined in semantic conventions. [required if original_payload is present]

• bytes original_payload = 7

  Original payload can be stored in this field. This can be useful for users who want to get the original payload. Formats such as JFR are highly extensible and can contain more information than what is defined in this spec. Inclusion of original payload should be configurable by the user. Default behavior should be to not include the original payload. If the original payload is in pprof format, it SHOULD not be included in this field. The field is optional, however if it is present `profile` MUST be present and contain the same profiling information.

• optional Profile profile = 8

  This is a reference to a pprof profile. Required, even when original_payload is present.

ProfilesData represents the profiles data that can be stored in persistent storage, OR can be embedded by other protocols that transfer OTLP profiles data but do not implement the OTLP protocol. The main difference between this message and collector protocol is that in this message there will not be any "control" or "metadata" specific to OTLP protocol. When new fields are added into this message, the OTLP request MUST be updated as well.

• repeated ResourceProfiles resource_profiles = 1

  An array of ResourceProfiles. For data coming from a single resource this array will typically contain one element. Intermediary nodes that receive data from multiple origins typically batch the data before forwarding further and in that case this array will contain multiple elements.

A collection of ScopeProfiles from a Resource.

Used in: collector.profiles.v1experimental.ExportProfilesServiceRequest, ProfilesData

• optional resource.v1.Resource resource = 1

  The resource for the profiles in this message. If this field is not set then no resource info is known.

• repeated ScopeProfiles scope_profiles = 2

  A list of ScopeProfiles that originate from a resource.

• string schema_url = 3

  The Schema URL, if known. This is the identifier of the Schema that the resource data is recorded in. To learn more about Schema URL see https://opentelemetry.io/docs/specs/otel/schemas/#schema-url This schema_url applies to the data in the "resource" field. It does not apply to the data in the "scope_profiles" field which have their own schema_url field.

Each Sample records values encountered in some program context. The program context is typically a stack trace, perhaps augmented with auxiliary information like the thread-id, some indicator of a higher level request being handled etc.

Used in: Profile

• repeated uint64 location_index = 1

  The indices recorded here correspond to locations in Profile.location. The leaf is at location_index[0]. [deprecated, superseded by locations_start_index / locations_length]

• uint64 locations_start_index = 7

  locations_start_index along with locations_length refers to to a slice of locations in Profile.location. Supersedes location_index.

• uint64 locations_length = 8

  locations_length along with locations_start_index refers to a slice of locations in Profile.location. Supersedes location_index.

• uint32 stacktrace_id_index = 9

  A 128bit id that uniquely identifies this stacktrace, globally. Index into string table. [optional]

• repeated int64 value = 2

  The type and unit of each value is defined by the corresponding entry in Profile.sample_type. All samples must have the same number of values, the same as the length of Profile.sample_type. When aggregating multiple samples into a single sample, the result has a list of values that is the element-wise sum of the lists of the originals.

• repeated Label label = 3

  label includes additional context for this sample. It can include things like a thread id, allocation size, etc. NOTE: While possible, having multiple values for the same label key is strongly discouraged and should never be used. Most tools (e.g. pprof) do not have good (or any) support for multi-value labels. And an even more discouraged case is having a string label and a numeric label of the same name on a sample. Again, possible to express, but should not be used. [deprecated, superseded by attributes]

• repeated uint64 attributes = 10

  References to attributes in Profile.attribute_table. [optional]

• uint64 link = 12

  Reference to link in Profile.link_table. [optional]

• repeated uint64 timestamps_unix_nano = 13

  Timestamps associated with Sample represented in nanoseconds. These timestamps are expected to fall within the Profile's time range. [optional]

A collection of ProfileContainers produced by an InstrumentationScope.

Used in: ResourceProfiles

• optional common.v1.InstrumentationScope scope = 1

  The instrumentation scope information for the profiles in this message. Semantically when InstrumentationScope isn't set, it is equivalent with an empty instrumentation scope name (unknown).

• repeated ProfileContainer profiles = 2

  A list of ProfileContainers that originate from an instrumentation scope.

• string schema_url = 3

  The Schema URL, if known. This is the identifier of the Schema that the metric data is recorded in. To learn more about Schema URL see https://opentelemetry.io/docs/specs/otel/schemas/#schema-url This schema_url applies to all profiles in the "profiles" field.

ValueType describes the type and units of a value, with an optional aggregation temporality.

Used in: Profile

• int64 type = 1

  Index into string table.

• int64 unit = 2

  Index into string table.

• AggregationTemporality aggregation_temporality = 3