package opentelemetry.proto.profiles.v1development

Get desktop application:
View/edit binary Protocol Buffers messages

Describes a function, including its human-readable name, system name, source file, and starting line number in the source. At least one of {name_strindex, system_name_strindex, filename_strindex} MUST be present. Status: [Alpha]

Used in: ProfilesDictionary

• int32 name_strindex = 1

  The function name. Empty string if not available.

• int32 system_name_strindex = 2

  Function name, as identified by the system. For instance, it can be a C++ mangled name. Empty string if not available.

• int32 filename_strindex = 3

  Source file containing the function. Empty string if not available.

• int64 start_line = 4

  Line number in source file. 1-based, 0 means unset.

A custom 'dictionary native' style of encoding attributes which is more convenient for profiles than opentelemetry.proto.common.v1.KeyValue Specifically, uses the ProfilesDictionary.string_table for keys and allows optional unit information. Status: [Alpha]

Used in: ProfilesDictionary

• int32 key_strindex = 1

  The index into the string table for the attribute's key.

• optional common.v1.AnyValue value = 2

  The value of the attribute.

• int32 unit_strindex = 3

  The index into the string table for the attribute's unit. zero indicates implicit (by semconv) or non-defined unit. If present, the unit string SHOULD be in UCUM format.

Details a specific line in a source code, linked to a function. Status: [Alpha]

Used in: Location

• int32 function_index = 1

  Reference to function in ProfilesDictionary.function_table.

• int64 line = 2

  Line number in source code. 1-based, 0 means unset.

• int64 column = 3

  Column number in source code. 1-based, 0 means unset.

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. Status: [Alpha]

Used in: ProfilesDictionary

• bytes trace_id = 1

  A unique identifier of the 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.

Contains function and line table debug information for a single frame. Status: [Alpha]

Used in: ProfilesDictionary

• int32 mapping_index = 1

  Reference to mapping in ProfilesDictionary.mapping_table. 0 means unknown or not applicable.

• uint64 address = 2

  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 lines = 3

  Multiple lines indicate 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: lines[0].function_name == "memcpy" lines[1].function_name == "printf"

• repeated int32 attribute_indices = 4

  References to attributes in ProfilesDictionary.attribute_table. [optional]

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

Used in: ProfilesDictionary

• uint64 memory_start = 1

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

• uint64 memory_limit = 2

  The limit of the address range occupied by this mapping.

• uint64 file_offset = 3

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

• int32 filename_strindex = 4

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

  Index into ProfilesDictionary.string_table.

• repeated int32 attribute_indices = 5

  References to attributes in ProfilesDictionary.attribute_table. [optional]

Represents a complete profile, including sample types, samples, mappings to binaries, stacks, locations, functions, string table, and additional metadata. It modifies and annotates pprof Profile with OpenTelemetry specific fields. Status: [Alpha]

Used in: ScopeProfiles

• optional ValueType sample_type = 1

  The type and unit of all Sample.values in this profile. For a cpu or off-cpu profile this might be: ["cpu","nanoseconds"] or ["off_cpu","nanoseconds"] For a heap profile, this might be: ["allocated_objects","count"] or ["allocated_space","bytes"],

• repeated Sample samples = 2

  The set of samples recorded in this profile.

• fixed64 time_unix_nano = 3

  Time of collection (UTC) as nanoseconds since the UNIX epoch.

• uint64 duration_nano = 4

  Duration of the profile in nanoseconds. For instant profiles like live heap snapshot, the duration can be zero but it may be preferable to set time_unix_nano to the process start time and duration_nano to the relative time when the profile was gathered so that Sample.timestamps_unix_nano values fall within the profile time range.

• optional ValueType period_type = 5

  The type and the unit of the events between sampled occurrences for periodic sampling profiles. It can be the same as sample_type or it can be different depending on the case, for example: - sample_type=(cpu, milliseconds), period_type=(cpu, milliseconds), period=10 signals that we sample the program every 10 milliseconds and capture samples that each represent that sampling distance. - sample_type=(off_cpu, nanoseconds), period_type=(context_switch, count), period=1000 describes a profile where sampling is done every so often in terms of context switches, but the recorded metric is the time spent by the thread off CPU. - sample_type=(inuse_space, bytes), period_type=(allocated_bytes, bytes), period=262144 might represent a heap profile where the recorded sample metric is the size of the live heap while the periodic sampling is done using the number of cumulatively allocated bytes.

• int64 period = 6

  The distance between sampled occurrences for periodic sampling profiles. The value is of the period_type type and unit.

• bytes profile_id = 7

  A globally unique identifier for a profile. The ID is a 16-byte array. An ID with all zeroes is considered invalid. It MAY be used for deduplication and signal correlation purposes. It is acceptable to treat two profiles with different values in this field as not equal, even if they represented the same object at an earlier time. This field is optional; an ID may be assigned to an ID-less profile in a later step.

• uint32 dropped_attributes_count = 8

  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 = 9

  The original payload format. See also original_payload. It MUST be set together with original_payload or both left unset [optional]. The allowed values for the format string are defined by the OpenTelemetry specification. Some examples are "jfr", "pprof", "linux_perf". The original_payload MAY be used when converting from a source format (e.g. JFR) that carries information which cannot be losslessly represented in the Profiles format. Including the original data allows receivers to store or reexport the data without loss. Because the original payload can be large, its inclusion is optional.

• bytes original_payload = 10

  The original payload bytes. See also original_payload_format. It MUST be set together with original_payload_format or both left unset [optional].

• repeated int32 attribute_indices = 11

  References to attributes in attribute_table. [optional]

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. Status: [Alpha]

• repeated ResourceProfiles resource_profiles = 1

  An array of ResourceProfiles. For data coming from an SDK profiler, this array will typically contain one element. Host-level profilers will usually create one ResourceProfile per container, as well as one additional ResourceProfile grouping all samples from non-containerized processes. Other resource groupings are possible as well and clarified via Resource.attributes and semantic conventions. Tools that visualize profiles SHOULD prefer displaying resources_profiles[0].scope_profiles[0].profiles[0] by default.

• optional ProfilesDictionary dictionary = 2

  A single instance of ProfilesDictionary shared across the entire message.

ProfilesDictionary contains all the dictionary tables that are shared across the entire ProfilesData message. The following applies to all fields in this message: - A dictionary is an array of dictionary items. Users of the dictionary compactly reference the items using the index within the array. - The element at index 0 MUST be the zero value for the dictionary's element type (e.g. `""` for `string_table`, `Location{}` for `location_table`). This allows for _index fields pointing into the dictionary to use a 0 pointer value to indicate 'null' / 'not set'. Unless otherwise defined, a 'zero value' message value is one with all default field values, so as to minimize wire encoded size. - There SHOULD NOT be duplicate items in a dictionary. The identity of a dictionary item is based on its value, recursively as needed. If a particular implementation does emit duplicate items, it MUST NOT attempt to give them meaning based on the index or order. A profile processor MAY remove duplicates and this MUST NOT have any observable effects for consumers. - There SHOULD NOT be orphaned (unreferenced) items in a dictionary. A profile processor MAY remove ("garbage-collect") orphaned items and this MUST NOT have any observable effects for consumers. Status: [Alpha]

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

• repeated Mapping mapping_table = 1

  Mappings from address ranges to the image/binary/library mapped into that address range referenced by locations via Location.mapping_index. mapping_table[0] MUST be the zero value (Mapping{}) and present.

• repeated Location location_table = 2

  Locations referenced by samples via Stack.location_indices. location_table[0] MUST be the zero value (Location{}) and present.

• repeated Function function_table = 3

  Functions referenced by locations via Line.function_index. function_table[0] MUST be the zero value (Function{}) and present.

• repeated Link link_table = 4

  Links referenced by samples via Sample.link_index. link_table[0] MUST be the zero value (Link{}) and present. Note that whilst Link{trace_id=array[0], span_id=array[0]} and Link{trace_id=array[16], span_id=array[8]} filled with zero-value bytes are both appropriate zero/invalid values per the trace.proto:Span definition, the latter SHOULD be used for link_table[0] for better compatibility with codecs strictly expecting 16/8 byte array lengths.

• repeated string string_table = 5

  A common table for strings referenced by various messages. string_table[0] MUST be "" and present.

• repeated KeyValueAndUnit attribute_table = 6

  A common table for attributes referenced by the Profile, Sample, Mapping and Location messages, through their attribute_indices field. Each entry is a key/value pair with an optional unit in UCUM format. Since this is a dictionary table, multiple entries with the same key MAY be present, unlike direct attribute tables like Resource.attributes. However, the referencing attribute_indices fields MUST maintain the key uniqueness requirement. It's recommended to use attributes for variables with bounded cardinality, such as categorical variables (https://en.wikipedia.org/wiki/Categorical_variable). Using an attribute of a floating point type (e.g., CPU time) in a sample can quickly make every attribute value unique, defeating the purpose of the dictionary and impractically increasing the profile size. 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" "abc.com/myattribute": true "allocation_size": 128 bytes attribute_table[0] MUST be the zero value (KeyValueAndUnit{}) and present.

• repeated Stack stack_table = 7

  Stacks referenced by samples via Sample.stack_index. stack_table[0] MUST be the zero value (Stack{}) and present.

A collection of ScopeProfiles from a Resource. Status: [Alpha]

Used in: collector.profiles.v1development.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 this resource.

• string schema_url = 3

  The Schema URL, if known. This is the identifier of the Schema that the resource data is recorded in. Notably, the last part of the URL path is the version number of the schema: http[s]://server[:port]/path/<version>. 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 has its 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. A Sample MUST have have at least one entry in values or timestamps_unix_nano. If both fields are populated, they MUST contain the same number of elements, and the elements at the same index MUST refer to the same event. For the purposes of efficiently representing aggregated data observations, a Sample is regarded as having a shared identity and an associated collection of per-observation data points. A Sample's identity (i.e. primary key) is the tuple of {stack_index, set_of(attribute_indices), link_index}. Samples having the same identity SHOULD be combined by appending timestamps and values to the data arrays. Examples of different ways ('shapes') of representing a sample with the total value of 10: Timestamps only (consumers must assume the value is 1 for each timestamp): values: [] timestamps_unix_nano: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] Single aggregated value without timestamps (one element representing the total): values: [10] timestamps_unix_nano: [] Per-timestamp value (each point in time records a specific value): values: [2, 2, 3, 3] timestamps_unix_nano: [1, 2, 3, 4] All Samples for a Profile SHOULD have the same shape, i.e. all data observation series should consistently adopt the same data recording style. Status: [Alpha]

Used in: Profile

• int32 stack_index = 1

  Reference to stack in ProfilesDictionary.stack_table.

• repeated int32 attribute_indices = 2

  References to attributes in ProfilesDictionary.attribute_table. [optional]

• int32 link_index = 3

  Reference to link in ProfilesDictionary.link_table. [optional] 0 means no link exists.

• repeated int64 values = 4

  Measured values. The type and unit of each value is defined by Profile.sample_type.

• repeated fixed64 timestamps_unix_nano = 5

  Timestamps (UTC) as nanoseconds since the UNIX epoch. The timestamps SHOULD fall within the [Profile.time_unix_nano, Profile.time_unix_nano + Profile.duration_nano) interval.

A collection of Profiles produced by an InstrumentationScope. Status: [Alpha]

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 Profile profiles = 2

  A list of Profiles that originate from this instrumentation scope.

• string schema_url = 3

  The Schema URL, if known. This is the identifier of the Schema that the profile data is recorded in. Notably, the last part of the URL path is the version number of the schema: http[s]://server[:port]/path/<version>. 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 "scope" field and all profiles in the "profiles" field.

A Stack represents a stack trace as a list of locations (leaf first). For example, the stack trace resulting from the call stack main -> foo -> bar would be encoded into the location_indices list [2, 1, 0] which references the locations in location_table as: [Location{"main"}, Location{"foo"}, Location{"bar"}]. Status: [Alpha]

Used in: ProfilesDictionary

• repeated int32 location_indices = 1

  References to locations in ProfilesDictionary.location_table. The first location is the leaf frame.

ValueType describes the type and units of a value. Status: [Alpha]

Used in: Profile

• int32 type_strindex = 1

  Index into ProfilesDictionary.string_table.

• int32 unit_strindex = 2

  Index into ProfilesDictionary.string_table.