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] [Since v1.4.0]

Used in: ProfilesDictionary

• int32 name_strindex = 1

  The function name. Empty string if not available. [Since v1.4.0]

• 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. [Since v1.4.0]

• int32 filename_strindex = 3

  Source file containing the function. Empty string if not available. [Since v1.4.0]

• int64 start_line = 4

  Line number in source file. 1-based, 0 means unset. [Since v1.4.0]

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] [Since v1.8.0]

Used in: ProfilesDictionary

• int32 key_strindex = 1

  The index into the string table for the attribute's key. [Since v1.8.0]

• optional common.v1.AnyValue value = 2

  The value of the attribute. [Since v1.8.0]

• 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. [Since v1.8.0]

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

Used in: Location

• int32 function_index = 1

  Reference to function in ProfilesDictionary.function_table. [Since v1.4.0]

• int64 line = 2

  Line number in source code. 1-based, 0 means unset. [Since v1.4.0]

• int64 column = 3

  Column number in source code. 1-based, 0 means unset. [Since v1.4.0]

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] [Since v1.4.0]

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. [Since v1.4.0]

• bytes span_id = 2

  A unique identifier for the linked span. The ID is an 8-byte array. [Since v1.4.0]

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

Used in: ProfilesDictionary

• int32 mapping_index = 1

  Reference to mapping in ProfilesDictionary.mapping_table. 0 means unknown or not applicable. [Since v1.4.0]

• 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. [Since v1.4.0]

• 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" [Since v1.9.0]

• repeated int32 attribute_indices = 4

  References to attributes in ProfilesDictionary.attribute_table. [optional] [Since v1.4.0]

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

Used in: ProfilesDictionary

• uint64 memory_start = 1

  Address at which the binary (or DLL) is loaded into memory. [Since v1.4.0]

• uint64 memory_limit = 2

  The limit of the address range occupied by this mapping. [Since v1.4.0]

• uint64 file_offset = 3

  Offset in the binary that corresponds to the first mapped address. [Since v1.4.0]

• 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]". [Since v1.4.0]

  Index into ProfilesDictionary.string_table.

• repeated int32 attribute_indices = 5

  References to attributes in ProfilesDictionary.attribute_table. [optional] [Since v1.4.0]

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] [Since v1.4.0]

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"], [Since v1.4.0]

• repeated Sample samples = 2

  The set of samples recorded in this profile. [Since v1.9.0]

• fixed64 time_unix_nano = 3

  Time of collection (UTC) as nanoseconds since the UNIX epoch. [Since v1.4.0]

• 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. [Since v1.8.0]

• 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. [Since v1.8.0]

• int64 period = 6

  The distance between sampled occurrences for periodic sampling profiles. The value is of the period_type type and unit. [Since v1.8.0]

• 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. [Since v1.9.0]

• 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. [Since v1.9.0]

• 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. [Since v1.9.0]

• 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]. [Since v1.9.0]

• repeated int32 attribute_indices = 11

  References to attributes in attribute_table. [optional] [Since v1.9.0]

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] [Since v1.4.0]

• 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. [Since v1.4.0]

• optional ProfilesDictionary dictionary = 2

  A single instance of ProfilesDictionary shared across the entire message. [Since v1.7.0]

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] [Since v1.7.0]

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. [Since v1.7.0]

• repeated Location location_table = 2

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

• repeated Function function_table = 3

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

• 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. [Since v1.7.0]

• repeated string string_table = 5

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

• 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: "user_agent.original": "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" "com.example.myattribute": true "allocation_size": 128 bytes attribute_table[0] MUST be the zero value (KeyValueAndUnit{}) and present. [Since v1.7.0]

• repeated Stack stack_table = 7

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

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

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. [Since v1.4.0]

• repeated ScopeProfiles scope_profiles = 2

  A list of ScopeProfiles that originate from this resource. [Since v1.4.0]

• 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. [Since v1.4.0]

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] [Since v1.4.0]

Used in: Profile

• int32 stack_index = 1

  Reference to stack in ProfilesDictionary.stack_table. [Since v1.8.0]

• repeated int32 attribute_indices = 2

  References to attributes in ProfilesDictionary.attribute_table. [optional] [Since v1.5.0]

• int32 link_index = 3

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

• repeated int64 values = 4

  Measured values. The type and unit of each value is defined by Profile.sample_type. [Since v1.10.0]

• 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. [Since v1.8.0]

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

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). [Since v1.4.0]

• repeated Profile profiles = 2

  A list of Profiles that originate from this instrumentation scope. [Since v1.4.0]

• 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. [Since v1.4.0]

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] [Since v1.8.0]

Used in: ProfilesDictionary

• repeated int32 location_indices = 1

  References to locations in ProfilesDictionary.location_table. The first location is the leaf frame. [Since v1.8.0]

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

Used in: Profile

• int32 type_strindex = 1

  Index into ProfilesDictionary.string_table. [Since v1.4.0]

• int32 unit_strindex = 2

  Index into ProfilesDictionary.string_table. [Since v1.4.0]