Found new managed modules references#1283
Merged
Merged
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| }, | ||
| { | ||
| "name": "v1.11.0", | ||
| "digest": "b4c21f5721b64e4e8c7f871314cdebfeb1fe7e423cef183990365a892f596808b7d4e02af6a9860334684f787c1feffb1b661d19ba71aad507cc2c6b456c46db" |
There was a problem hiding this comment.
[Posted at 2026-07-22T12:34:06Z]
Intermediate transition
$ casdiff v1.10.0 \
v1.11.0 \
--format=markdown6 files changed: 0 removed, 0 renamed, 1 added, 5 changed content.
6 files changed: 0 removed, 0 renamed, 1 added, 5 changed content.
Files added:
+ shake256:0d1c9369ac685e0bdc1ffbe2744e2f07498168af5e6f82270701cb0a6f44f6775556c19b84b7bd7630512659c68c7bc7d4160d5a5a63fec9a823c372dca2d23c opentelemetry/proto/processcontext/v1development/process_context.protoFiles changed content:
buf.md:
--- shake256:a5f1db61212d594f876df08d637ab2471c5ce8133de641eb5fcf1ad427c2648bf74657473b2691d1ab2bba6d24daf3f6d2e298921617800704d9f73d7f2928d3 buf.md
+++ shake256:2c4433c14b51cf40358b2c22ed9f6335ca4e76831b0d12dd887e6cc3c2c87afd652d2159ff8b1c29512c1c2ada9aa67c066d7d298823b815453f6609b2f0513d buf.md
@@ -8,7 +8,7 @@
```
deps:
- - buf.build/opentelemetry/opentelemetry:<SEMVER_RELEASE_VERSION>
+ - {{bsrhost}}/opentelemetry/opentelemetry:<SEMVER_RELEASE_VERSION>
```
For more information, see the [documentation](https://buf.build/docs/bsr/overview).
opentelemetry/proto/collector/profiles/v1development/profiles_service.proto:
--- shake256:095933bf1ec7011cd60e0f421c006d5f94707774188d2acd0f8979da5c66014c6d9c59749bc787642583ea5bd8ded31b203072ca9820aa53efc2811e3d6263c4 opentelemetry/proto/collector/profiles/v1development/profiles_service.proto
+++ shake256:85f2d08e7658716fa12e3708b38b4ee4d6dbb4138a483fee082247e174dfd5580d5ba485ec6bc3b3c6d0fc54ba992c0bdfbc25cff1d7a49f51cd2a1ccfd0a591 opentelemetry/proto/collector/profiles/v1development/profiles_service.proto
@@ -30,6 +30,7 @@
rpc Export(ExportProfilesServiceRequest) returns (ExportProfilesServiceResponse) {}
}
+// Status: [Alpha]
message ExportProfilesServiceRequest {
// An array of ResourceProfiles.
// For data coming from a single resource this array will typically contain one
@@ -42,6 +43,7 @@
opentelemetry.proto.profiles.v1development.ProfilesDictionary dictionary = 2;
}
+// Status: [Alpha]
message ExportProfilesServiceResponse {
// The details of a partially successful export request.
//
@@ -61,6 +63,7 @@
ExportProfilesPartialSuccess partial_success = 1;
}
+// Status: [Alpha]
message ExportProfilesPartialSuccess {
// The number of rejected profiles.
//
opentelemetry/proto/common/v1/common.proto:
--- shake256:0e653b2208b91f3a711867dd082339237fedddd445d929885e00e52b60653903fe569b1fe99ab44cf7dd2eb72da0a581f2bc96a0f0e5cb58db0526ea5d27ba6c opentelemetry/proto/common/v1/common.proto
+++ shake256:097bbf1f07eb73ba289ea12b5727283166d08239d702030db2dcce8b3ea1878c6db621b1d2a95e6354977c1c471cba1267f8fa0636c4b79d32c2d8d80512b0c9 opentelemetry/proto/common/v1/common.proto
@@ -45,7 +45,7 @@
// Profiling signal and process the data as if this value were absent or
// empty, ignoring its semantic content for the non-Profiling signal.
//
- // Status: [Development]
+ // Status: [Alpha]
int32 string_value_strindex = 8;
}
}
@@ -76,7 +76,7 @@
// attributes, etc.
message KeyValue {
// The key name of the pair.
- // key_ref MUST NOT be set if key is used.
+ // key_strindex MUST NOT be set if key is used.
string key = 1;
// The value of the pair.
@@ -92,7 +92,7 @@
// Profiling signal and process the data as if this value were absent or
// empty, ignoring its semantic content for the non-Profiling signal.
//
- // Status: [Development]
+ // Status: [Alpha]
int32 key_strindex = 3;
}
opentelemetry/proto/metrics/v1/metrics.proto:
--- shake256:971a5d39d2c3b851bef250244f991753d96e45c52fa53f4a874238098e5019535c66dab663aee020ff0e969d3cbc09c406335af81fd90d3f017dbbba809a2363 opentelemetry/proto/metrics/v1/metrics.proto
+++ shake256:57b8c0a8cdeaf2d041aae974946f4bf0c0da3a92ef7556d9547985690a793e070527a9ace5932153cdf4f4ba870207eba72e9702cc1efb45bf885ab9bffc758b opentelemetry/proto/metrics/v1/metrics.proto
@@ -195,7 +195,7 @@
string description = 2;
// The unit in which the metric value is reported. Follows the format
- // described by https://unitsofmeasure.org/ucum.html.
+ // described by https://ucum.org/ucum and https://units-of-measurement.org/
string unit = 3;
// Data determines the aggregation type (if any) of the metric, what is the
opentelemetry/proto/profiles/v1development/profiles.proto:
--- shake256:e90264d4b8bc6bed09c61b67af92c7409abc74b1003559e055ab12d52b6473d8ebebcc7fc108090335304e091e2a3483f7ba894210465ca6d3e5b06e4b09521a opentelemetry/proto/profiles/v1development/profiles.proto
+++ shake256:16bccfa8028eb699701b6fb14599348de2a9a239bcb56c55a4ad11ec2a835f5e5848f8ac000c52890bad71a2722e369ee409a37ef4ef3e1dabc76884484579ec opentelemetry/proto/profiles/v1development/profiles.proto
@@ -67,17 +67,17 @@
// │ n-1
// │ 1-n ┌───────────────────────────────────────┐
// ▼ │ ▽
-// ┌──────────────────┐ 1-n ┌─────────────────┐ ┌──────────┐
+// ┌──────────────────┐ n-n ┌─────────────────┐ ┌──────────┐
// │ Sample │ ──────▷ │ KeyValueAndUnit │ │ Link │
// └──────────────────┘ └─────────────────┘ └──────────┘
// │ △ △
-// │ n-1 │ │ 1-n
+// │ n-1 │ │ n-n
// ▽ │ │
// ┌──────────────────┐ │ │
// │ Stack │ │ │
// └──────────────────┘ │ │
-// │ 1-n │ │
-// │ 1-n ┌────────────────┘ │
+// │ n-n │ │
+// │ n-n ┌────────────────┘ │
// ▽ │ │
// ┌──────────────────┐ n-1 ┌─────────────┐
// │ Location │ ──────▷ │ Mapping │
@@ -89,70 +89,78 @@
// │ Line │
// └──────────────────┘
// │
-// │ 1-1
+// │ n-1
// ▽
// ┌──────────────────┐
// │ Function │
// └──────────────────┘
//
-// ProfilesDictionary represents the profiles data shared across the
-// entire message being sent. The following applies to all fields in this
-// 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.
//
-// - A dictionary MUST have a zero value encoded as the first element. This
+// - 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 dupes in a dictionary. The identity of dictionary
-// items is based on their value, recursively as needed. If a particular
-// implementation does emit duplicated items, it MUST NOT attempt to give them
-// meaning based on the index or order. A profile processor may remove
-// duplicate items and this MUST NOT have any observable effects for
-// consumers.
+// - 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
+// profile processor MAY remove ("garbage-collect") orphaned items and this
// MUST NOT have any observable effects for consumers.
//
+// Status: [Alpha]
message ProfilesDictionary {
// 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 always be zero value (Mapping{}) and present.
+ // mapping_table[0] MUST be the zero value (Mapping{}) and present.
repeated Mapping mapping_table = 1;
// Locations referenced by samples via Stack.location_indices.
//
- // location_table[0] must always be zero value (Location{}) and present.
+ // location_table[0] MUST be the zero value (Location{}) and present.
repeated Location location_table = 2;
// Functions referenced by locations via Line.function_index.
//
- // function_table[0] must always be zero value (Function{}) and present.
+ // function_table[0] MUST be the zero value (Function{}) and present.
repeated Function function_table = 3;
// Links referenced by samples via Sample.link_index.
//
- // link_table[0] must always be zero value (Link{}) and present.
+ // 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 Link link_table = 4;
// A common table for strings referenced by various messages.
//
- // string_table[0] must always be "" and present.
+ // string_table[0] MUST be "" and present.
repeated string string_table = 5;
// A common table for attributes referenced by the Profile, Sample, Mapping
- // and Location messages below through attribute_indices field. Each entry is
- // a key/value pair with an optional unit. Since this is a dictionary table,
- // multiple entries with the same key may be present, unlike direct attribute
- // tables like Resource.attributes. The referencing attribute_indices fields,
- // though, do maintain the key uniqueness requirement.
+ // 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
@@ -166,12 +174,12 @@
// "abc.com/myattribute": true
// "allocation_size": 128 bytes
//
- // attribute_table[0] must always be zero value (KeyValueAndUnit{}) and present.
+ // attribute_table[0] MUST be the zero value (KeyValueAndUnit{}) and present.
repeated KeyValueAndUnit attribute_table = 6;
// Stacks referenced by samples via Sample.stack_index.
//
- // stack_table[0] must always be zero value (Stack{}) and present.
+ // stack_table[0] MUST be the zero value (Stack{}) and present.
repeated Stack stack_table = 7;
}
@@ -185,6 +193,8 @@
//
// When new fields are added into this message, the OTLP request MUST be updated
// as well.
+//
+// Status: [Alpha]
message ProfilesData {
// An array of ResourceProfiles.
// For data coming from an SDK profiler, this array will typically contain one
@@ -193,16 +203,18 @@
// 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
+ // Tools that visualize profiles SHOULD prefer displaying
// resources_profiles[0].scope_profiles[0].profiles[0] by default.
repeated ResourceProfiles resource_profiles = 1;
- // One instance of ProfilesDictionary
+ // A single instance of ProfilesDictionary shared across the entire message.
ProfilesDictionary dictionary = 2;
}
// A collection of ScopeProfiles from a Resource.
+//
+// Status: [Alpha]
message ResourceProfiles {
reserved 1000;
@@ -210,7 +222,7 @@
// If this field is not set then no resource info is known.
opentelemetry.proto.resource.v1.Resource resource = 1;
- // A list of ScopeProfiles that originate from a resource.
+ // A list of ScopeProfiles that originate from this resource.
repeated ScopeProfiles scope_profiles = 2;
// The Schema URL, if known. This is the identifier of the Schema that the resource data
@@ -218,18 +230,20 @@
// 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 have their own schema_url field.
+ // to the data in the "scope_profiles" field, which has its own schema_url field.
string schema_url = 3;
}
// A collection of Profiles produced by an InstrumentationScope.
+//
+// Status: [Alpha]
message ScopeProfiles {
// 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).
opentelemetry.proto.common.v1.InstrumentationScope scope = 1;
- // A list of Profiles that originate from an instrumentation scope.
+ // A list of Profiles that originate from this instrumentation scope.
repeated Profile profiles = 2;
// The Schema URL, if known. This is the identifier of the Schema that the profile data
@@ -246,21 +260,24 @@
// Measurements represented with this format should follow the
// following conventions:
//
-// - Consumers should treat unset optional fields as if they had been
-// set with their default value.
+// - Consumers SHOULD treat unset optional fields as if they had been
+// set with their default value. We discourage using the protobuf
+// presence semantics, even if available in the protobuf generated API.
//
-// - When possible, measurements should be stored in "unsampled" form
-// that is most useful to humans. There should be enough
+// - When possible, measurements SHOULD be stored in "unsampled" form
+// that is most useful to humans. There should be enough
// information present to determine the original sampled values.
//
// - The profile is represented as a set of samples, where each sample
// references a stack trace which is a list of locations, each belonging
// to a mapping.
+//
// - There is a N->1 relationship from Stack.location_indices entries to
-// locations. For every Stack.location_indices entry there must be a
+// locations. For every Stack.location_indices entry there MUST be a
// unique Location with that index.
+//
// - There is an optional N->1 relationship from locations to
-// mappings. For every nonzero Location.mapping_id there must be a
+// mappings. For every nonzero Location.mapping_id there MUST be a
// unique Mapping with that index.
// Represents a complete profile, including sample types, samples, mappings to
@@ -268,9 +285,7 @@
// metadata. It modifies and annotates pprof Profile with OpenTelemetry
// specific fields.
//
-// Note that whilst fields in this message retain the name and field id from pprof in most cases
-// for ease of understanding data migration, it is not intended that pprof:Profile and
-// OpenTelemetry:Profile encoding be wire compatible.
+// Status: [Alpha]
message Profile {
// The type and unit of all Sample.values in this profile.
// For a cpu or off-cpu profile this might be:
@@ -284,23 +299,35 @@
// The following fields 3-12 are informational, do not affect
// interpretation of results.
- // Time of collection. Value is UNIX Epoch time in nanoseconds since 00:00:00
- // UTC on 1 January 1970.
+ // Time of collection (UTC) as nanoseconds since the UNIX epoch.
fixed64 time_unix_nano = 3;
- // Duration of the profile. 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. This ensures Sample.timestamps_unix_nano values such as
- // allocation timestamp fall into the profile time range.
+ // 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.
uint64 duration_nano = 4;
- // The kind of events between sampled occurrences.
- // e.g [ "cpu","cycles" ] or [ "heap","bytes" ]
+ // 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.
ValueType period_type = 5;
- // The number of events between sampled occurrences.
+ // The distance between sampled occurrences for periodic sampling profiles.
+ // The value is of the period_type type and unit.
int64 period = 6;
// 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
+ // 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.
@@ -312,28 +339,20 @@
// attributes. If this value is 0, then no attributes were dropped.
uint32 dropped_attributes_count = 8;
- // The original payload format. See also original_payload. Optional, but the
- // format and the bytes must be set or unset together.
+ // 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 optionally provided when the conversion to the
- // OLTP format was done from a different format with some loss of the fidelity
- // and the receiver may want to store the original payload to allow future
- // lossless export or reinterpretation. Some examples of the original format
- // are JFR (Java Flight Recorder), pprof, Linux perf.
- //
- // Even when the original payload is in a format that is semantically close to
- // OTLP, such as pprof, a conversion may still be lossy in some cases (e.g. if
- // the pprof file contains custom extensions or conventions).
- //
- // The original payload can be large in size, so including the original
- // payload should be configurable by the profiler or collector options. The
- // default behavior should be to not include the original payload.
+ // 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.
string original_payload_format = 9;
- // The original payload bytes. See also original_payload_format. Optional, but
- // format and the bytes must be set or unset together.
+ // The original payload bytes. See also original_payload_format. It MUST be set
+ // together with original_payload_format or both left unset [optional].
bytes original_payload = 10;
// References to attributes in attribute_table. [optional]
@@ -342,8 +361,10 @@
// 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]
message Link {
- // A unique identifier of a trace that this linked span is part of. The ID is a
+ // A unique identifier of the trace that this linked span is part of. The ID is a
// 16-byte array.
bytes trace_id = 1;
@@ -352,6 +373,8 @@
}
// ValueType describes the type and units of a value.
+//
+// Status: [Alpha]
message ValueType {
// Index into ProfilesDictionary.string_table.
int32 type_strindex = 1;
@@ -365,56 +388,55 @@
// information like the thread-id, some indicator of a higher level request
// being handled etc.
//
-// A Sample MUST have have at least one values or timestamps_unix_nano entry. 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.
+// 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.
-// Samples having the same identity SHOULD be combined by inserting timestamps and values to the data arrays.
+// 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:
//
-// Report of a stacktrace at 10 timestamps (consumers must assume the value is 1 for each point):
+// 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]
//
-// Report of a stacktrace with an aggregated value without timestamps:
-// values: [10]
+// Single aggregated value without timestamps (one element representing the total):
+// values: [10]
// timestamps_unix_nano: []
//
-// Report of a stacktrace at 4 timestamps where each point records a specific value:
+// 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]
message Sample {
-
- // A Sample's identity (i.e. 'primary key') is the tuple of {stack_index, set_of(attribute_indices), link_index}
-
// Reference to stack in ProfilesDictionary.stack_table.
int32 stack_index = 1;
// References to attributes in ProfilesDictionary.attribute_table. [optional]
repeated int32 attribute_indices = 2;
// Reference to link in ProfilesDictionary.link_table. [optional]
- // It can be unset / set to 0 if no link exists, as link_table[0] is always a 'null' default value.
+ // 0 means no link exists.
int32 link_index = 3;
// The following fields may contain per-observation data and do not form part of the Sample's identity.
- // The type and unit of each value is defined by Profile.sample_type.
+ // Measured values. The type and unit of each value is defined by Profile.sample_type.
repeated int64 values = 4;
- // Timestamps associated with Sample. Value is UNIX Epoch time in nanoseconds
- // since 00:00:00 UTC on 1 January 1970. The timestamps should fall within the
- // [Profile.time_unix_nano, Profile.time_unix_nano + Profile.duration_nano)
- // time range.
+ // 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.
repeated fixed64 timestamps_unix_nano = 5;
}
// Describes the mapping of a binary in memory, including its address range,
// file offset, and metadata like build ID
+//
+// Status: [Alpha]
message Mapping {
// Address at which the binary (or DLL) is loaded into memory.
uint64 memory_start = 1;
@@ -423,33 +445,40 @@
// Offset in the binary that corresponds to the first mapped address.
uint64 file_offset = 3;
// 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]".
+ // disk for the main binary and shared libraries, or a virtual
+ // abstraction like "[vdso]".
int32 filename_strindex = 4; // Index into ProfilesDictionary.string_table.
// References to attributes in ProfilesDictionary.attribute_table. [optional]
repeated int32 attribute_indices = 5;
}
-// A Stack represents a stack trace as a list of locations.
+// 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]
message Stack {
// References to locations in ProfilesDictionary.location_table.
// The first location is the leaf frame.
repeated int32 location_indices = 1;
}
-// Describes function and line table debug information.
+// Contains function and line table debug information for a single frame.
+//
+// Status: [Alpha]
message Location {
// Reference to mapping in ProfilesDictionary.mapping_table.
- // It can be unset / set to 0 if the mapping is unknown or not applicable for
- // this profile type, as mapping_table[0] is always a 'null' default mapping.
+ // 0 means unknown or not applicable.
int32 mapping_index = 1;
// The instruction address for this location, if available. It
- // should be within [Mapping.memory_start...Mapping.memory_limit]
+ // 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.
uint64 address = 2;
- // Multiple line indicates this location has inlined functions,
+ // Multiple lines indicate this location has inlined functions,
// where the last entry represents the caller into which the
// preceding entries were inlined.
//
@@ -462,17 +491,22 @@
}
// Details a specific line in a source code, linked to a function.
+//
+// Status: [Alpha]
message Line {
// Reference to function in ProfilesDictionary.function_table.
int32 function_index = 1;
- // Line number in source code. 0 means unset.
+ // Line number in source code. 1-based, 0 means unset.
int64 line = 2;
- // Column number in source code. 0 means unset.
+ // Column number in source code. 1-based, 0 means unset.
int64 column = 3;
}
// Describes a function, including its human-readable name, system name,
-// source file, and starting line number in the source.
+// 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]
message Function {
// The function name. Empty string if not available.
int32 name_strindex = 1;
@@ -481,13 +515,16 @@
int32 system_name_strindex = 2;
// Source file containing the function. Empty string if not available.
int32 filename_strindex = 3;
- // Line number in source file. 0 means unset.
+ // Line number in source file. 1-based, 0 means unset.
int64 start_line = 4;
}
// A custom 'dictionary native' style of encoding attributes which is more convenient
// for profiles than opentelemetry.proto.common.v1.KeyValue
-// Specifically, uses the string table for keys and allows optional unit information.
+// Specifically, uses the ProfilesDictionary.string_table for keys
+// and allows optional unit information.
+//
+// Status: [Alpha]
message KeyValueAndUnit {
// The index into the string table for the attribute's key.
int32 key_strindex = 1;
@@ -495,5 +532,6 @@
opentelemetry.proto.common.v1.AnyValue value = 2;
// 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.
int32 unit_strindex = 3;
}
| { | ||
| "module_name": "googleapis/cloud-run", | ||
| "latest_reference": "5f933a6c53e57f87e47e3725fceca08cf24b5b16" | ||
| "latest_reference": "38046d1d720f00070ea976c5aa6a3e3954c9b8c3" |
There was a problem hiding this comment.
[Posted at 2026-07-22T12:34:07Z]
Overall transition
$ casdiff 5f933a6c53e57f87e47e3725fceca08cf24b5b16 \
38046d1d720f00070ea976c5aa6a3e3954c9b8c3 \
--format=markdown0 files changed: 0 removed, 0 renamed, 0 added, 0 changed content.
| { | ||
| "module_name": "googleapis/googleapis", | ||
| "latest_reference": "5f933a6c53e57f87e47e3725fceca08cf24b5b16" | ||
| "latest_reference": "38046d1d720f00070ea976c5aa6a3e3954c9b8c3" |
There was a problem hiding this comment.
[Posted at 2026-07-22T12:34:08Z]
Overall transition
$ casdiff 5f933a6c53e57f87e47e3725fceca08cf24b5b16 \
38046d1d720f00070ea976c5aa6a3e3954c9b8c3 \
--format=markdown0 files changed: 0 removed, 0 renamed, 0 added, 0 changed content.
| { | ||
| "module_name": "opentelemetry/opentelemetry", | ||
| "latest_reference": "v1.10.0" | ||
| "latest_reference": "v1.11.0" |
There was a problem hiding this comment.
[Posted at 2026-07-22T12:34:09Z]
Overall transition
$ casdiff v1.10.0 \
v1.11.0 \
--format=markdown6 files changed: 0 removed, 0 renamed, 1 added, 5 changed content.
Files added:
+ shake256:0d1c9369ac685e0bdc1ffbe2744e2f07498168af5e6f82270701cb0a6f44f6775556c19b84b7bd7630512659c68c7bc7d4160d5a5a63fec9a823c372dca2d23c opentelemetry/proto/processcontext/v1development/process_context.protoFiles changed content:
buf.md:
--- shake256:a5f1db61212d594f876df08d637ab2471c5ce8133de641eb5fcf1ad427c2648bf74657473b2691d1ab2bba6d24daf3f6d2e298921617800704d9f73d7f2928d3 buf.md
+++ shake256:2c4433c14b51cf40358b2c22ed9f6335ca4e76831b0d12dd887e6cc3c2c87afd652d2159ff8b1c29512c1c2ada9aa67c066d7d298823b815453f6609b2f0513d buf.md
@@ -8,7 +8,7 @@
```
deps:
- - buf.build/opentelemetry/opentelemetry:<SEMVER_RELEASE_VERSION>
+ - {{bsrhost}}/opentelemetry/opentelemetry:<SEMVER_RELEASE_VERSION>
```
For more information, see the [documentation](https://buf.build/docs/bsr/overview).
opentelemetry/proto/collector/profiles/v1development/profiles_service.proto:
--- shake256:095933bf1ec7011cd60e0f421c006d5f94707774188d2acd0f8979da5c66014c6d9c59749bc787642583ea5bd8ded31b203072ca9820aa53efc2811e3d6263c4 opentelemetry/proto/collector/profiles/v1development/profiles_service.proto
+++ shake256:85f2d08e7658716fa12e3708b38b4ee4d6dbb4138a483fee082247e174dfd5580d5ba485ec6bc3b3c6d0fc54ba992c0bdfbc25cff1d7a49f51cd2a1ccfd0a591 opentelemetry/proto/collector/profiles/v1development/profiles_service.proto
@@ -30,6 +30,7 @@
rpc Export(ExportProfilesServiceRequest) returns (ExportProfilesServiceResponse) {}
}
+// Status: [Alpha]
message ExportProfilesServiceRequest {
// An array of ResourceProfiles.
// For data coming from a single resource this array will typically contain one
@@ -42,6 +43,7 @@
opentelemetry.proto.profiles.v1development.ProfilesDictionary dictionary = 2;
}
+// Status: [Alpha]
message ExportProfilesServiceResponse {
// The details of a partially successful export request.
//
@@ -61,6 +63,7 @@
ExportProfilesPartialSuccess partial_success = 1;
}
+// Status: [Alpha]
message ExportProfilesPartialSuccess {
// The number of rejected profiles.
//
opentelemetry/proto/common/v1/common.proto:
--- shake256:0e653b2208b91f3a711867dd082339237fedddd445d929885e00e52b60653903fe569b1fe99ab44cf7dd2eb72da0a581f2bc96a0f0e5cb58db0526ea5d27ba6c opentelemetry/proto/common/v1/common.proto
+++ shake256:097bbf1f07eb73ba289ea12b5727283166d08239d702030db2dcce8b3ea1878c6db621b1d2a95e6354977c1c471cba1267f8fa0636c4b79d32c2d8d80512b0c9 opentelemetry/proto/common/v1/common.proto
@@ -45,7 +45,7 @@
// Profiling signal and process the data as if this value were absent or
// empty, ignoring its semantic content for the non-Profiling signal.
//
- // Status: [Development]
+ // Status: [Alpha]
int32 string_value_strindex = 8;
}
}
@@ -76,7 +76,7 @@
// attributes, etc.
message KeyValue {
// The key name of the pair.
- // key_ref MUST NOT be set if key is used.
+ // key_strindex MUST NOT be set if key is used.
string key = 1;
// The value of the pair.
@@ -92,7 +92,7 @@
// Profiling signal and process the data as if this value were absent or
// empty, ignoring its semantic content for the non-Profiling signal.
//
- // Status: [Development]
+ // Status: [Alpha]
int32 key_strindex = 3;
}
opentelemetry/proto/metrics/v1/metrics.proto:
--- shake256:971a5d39d2c3b851bef250244f991753d96e45c52fa53f4a874238098e5019535c66dab663aee020ff0e969d3cbc09c406335af81fd90d3f017dbbba809a2363 opentelemetry/proto/metrics/v1/metrics.proto
+++ shake256:57b8c0a8cdeaf2d041aae974946f4bf0c0da3a92ef7556d9547985690a793e070527a9ace5932153cdf4f4ba870207eba72e9702cc1efb45bf885ab9bffc758b opentelemetry/proto/metrics/v1/metrics.proto
@@ -195,7 +195,7 @@
string description = 2;
// The unit in which the metric value is reported. Follows the format
- // described by https://unitsofmeasure.org/ucum.html.
+ // described by https://ucum.org/ucum and https://units-of-measurement.org/
string unit = 3;
// Data determines the aggregation type (if any) of the metric, what is the
opentelemetry/proto/profiles/v1development/profiles.proto:
--- shake256:e90264d4b8bc6bed09c61b67af92c7409abc74b1003559e055ab12d52b6473d8ebebcc7fc108090335304e091e2a3483f7ba894210465ca6d3e5b06e4b09521a opentelemetry/proto/profiles/v1development/profiles.proto
+++ shake256:16bccfa8028eb699701b6fb14599348de2a9a239bcb56c55a4ad11ec2a835f5e5848f8ac000c52890bad71a2722e369ee409a37ef4ef3e1dabc76884484579ec opentelemetry/proto/profiles/v1development/profiles.proto
@@ -67,17 +67,17 @@
// │ n-1
// │ 1-n ┌───────────────────────────────────────┐
// ▼ │ ▽
-// ┌──────────────────┐ 1-n ┌─────────────────┐ ┌──────────┐
+// ┌──────────────────┐ n-n ┌─────────────────┐ ┌──────────┐
// │ Sample │ ──────▷ │ KeyValueAndUnit │ │ Link │
// └──────────────────┘ └─────────────────┘ └──────────┘
// │ △ △
-// │ n-1 │ │ 1-n
+// │ n-1 │ │ n-n
// ▽ │ │
// ┌──────────────────┐ │ │
// │ Stack │ │ │
// └──────────────────┘ │ │
-// │ 1-n │ │
-// │ 1-n ┌────────────────┘ │
+// │ n-n │ │
+// │ n-n ┌────────────────┘ │
// ▽ │ │
// ┌──────────────────┐ n-1 ┌─────────────┐
// │ Location │ ──────▷ │ Mapping │
@@ -89,70 +89,78 @@
// │ Line │
// └──────────────────┘
// │
-// │ 1-1
+// │ n-1
// ▽
// ┌──────────────────┐
// │ Function │
// └──────────────────┘
//
-// ProfilesDictionary represents the profiles data shared across the
-// entire message being sent. The following applies to all fields in this
-// 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.
//
-// - A dictionary MUST have a zero value encoded as the first element. This
+// - 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 dupes in a dictionary. The identity of dictionary
-// items is based on their value, recursively as needed. If a particular
-// implementation does emit duplicated items, it MUST NOT attempt to give them
-// meaning based on the index or order. A profile processor may remove
-// duplicate items and this MUST NOT have any observable effects for
-// consumers.
+// - 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
+// profile processor MAY remove ("garbage-collect") orphaned items and this
// MUST NOT have any observable effects for consumers.
//
+// Status: [Alpha]
message ProfilesDictionary {
// 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 always be zero value (Mapping{}) and present.
+ // mapping_table[0] MUST be the zero value (Mapping{}) and present.
repeated Mapping mapping_table = 1;
// Locations referenced by samples via Stack.location_indices.
//
- // location_table[0] must always be zero value (Location{}) and present.
+ // location_table[0] MUST be the zero value (Location{}) and present.
repeated Location location_table = 2;
// Functions referenced by locations via Line.function_index.
//
- // function_table[0] must always be zero value (Function{}) and present.
+ // function_table[0] MUST be the zero value (Function{}) and present.
repeated Function function_table = 3;
// Links referenced by samples via Sample.link_index.
//
- // link_table[0] must always be zero value (Link{}) and present.
+ // 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 Link link_table = 4;
// A common table for strings referenced by various messages.
//
- // string_table[0] must always be "" and present.
+ // string_table[0] MUST be "" and present.
repeated string string_table = 5;
// A common table for attributes referenced by the Profile, Sample, Mapping
- // and Location messages below through attribute_indices field. Each entry is
- // a key/value pair with an optional unit. Since this is a dictionary table,
- // multiple entries with the same key may be present, unlike direct attribute
- // tables like Resource.attributes. The referencing attribute_indices fields,
- // though, do maintain the key uniqueness requirement.
+ // 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
@@ -166,12 +174,12 @@
// "abc.com/myattribute": true
// "allocation_size": 128 bytes
//
- // attribute_table[0] must always be zero value (KeyValueAndUnit{}) and present.
+ // attribute_table[0] MUST be the zero value (KeyValueAndUnit{}) and present.
repeated KeyValueAndUnit attribute_table = 6;
// Stacks referenced by samples via Sample.stack_index.
//
- // stack_table[0] must always be zero value (Stack{}) and present.
+ // stack_table[0] MUST be the zero value (Stack{}) and present.
repeated Stack stack_table = 7;
}
@@ -185,6 +193,8 @@
//
// When new fields are added into this message, the OTLP request MUST be updated
// as well.
+//
+// Status: [Alpha]
message ProfilesData {
// An array of ResourceProfiles.
// For data coming from an SDK profiler, this array will typically contain one
@@ -193,16 +203,18 @@
// 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
+ // Tools that visualize profiles SHOULD prefer displaying
// resources_profiles[0].scope_profiles[0].profiles[0] by default.
repeated ResourceProfiles resource_profiles = 1;
- // One instance of ProfilesDictionary
+ // A single instance of ProfilesDictionary shared across the entire message.
ProfilesDictionary dictionary = 2;
}
// A collection of ScopeProfiles from a Resource.
+//
+// Status: [Alpha]
message ResourceProfiles {
reserved 1000;
@@ -210,7 +222,7 @@
// If this field is not set then no resource info is known.
opentelemetry.proto.resource.v1.Resource resource = 1;
- // A list of ScopeProfiles that originate from a resource.
+ // A list of ScopeProfiles that originate from this resource.
repeated ScopeProfiles scope_profiles = 2;
// The Schema URL, if known. This is the identifier of the Schema that the resource data
@@ -218,18 +230,20 @@
// 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 have their own schema_url field.
+ // to the data in the "scope_profiles" field, which has its own schema_url field.
string schema_url = 3;
}
// A collection of Profiles produced by an InstrumentationScope.
+//
+// Status: [Alpha]
message ScopeProfiles {
// 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).
opentelemetry.proto.common.v1.InstrumentationScope scope = 1;
- // A list of Profiles that originate from an instrumentation scope.
+ // A list of Profiles that originate from this instrumentation scope.
repeated Profile profiles = 2;
// The Schema URL, if known. This is the identifier of the Schema that the profile data
@@ -246,21 +260,24 @@
// Measurements represented with this format should follow the
// following conventions:
//
-// - Consumers should treat unset optional fields as if they had been
-// set with their default value.
+// - Consumers SHOULD treat unset optional fields as if they had been
+// set with their default value. We discourage using the protobuf
+// presence semantics, even if available in the protobuf generated API.
//
-// - When possible, measurements should be stored in "unsampled" form
-// that is most useful to humans. There should be enough
+// - When possible, measurements SHOULD be stored in "unsampled" form
+// that is most useful to humans. There should be enough
// information present to determine the original sampled values.
//
// - The profile is represented as a set of samples, where each sample
// references a stack trace which is a list of locations, each belonging
// to a mapping.
+//
// - There is a N->1 relationship from Stack.location_indices entries to
-// locations. For every Stack.location_indices entry there must be a
+// locations. For every Stack.location_indices entry there MUST be a
// unique Location with that index.
+//
// - There is an optional N->1 relationship from locations to
-// mappings. For every nonzero Location.mapping_id there must be a
+// mappings. For every nonzero Location.mapping_id there MUST be a
// unique Mapping with that index.
// Represents a complete profile, including sample types, samples, mappings to
@@ -268,9 +285,7 @@
// metadata. It modifies and annotates pprof Profile with OpenTelemetry
// specific fields.
//
-// Note that whilst fields in this message retain the name and field id from pprof in most cases
-// for ease of understanding data migration, it is not intended that pprof:Profile and
-// OpenTelemetry:Profile encoding be wire compatible.
+// Status: [Alpha]
message Profile {
// The type and unit of all Sample.values in this profile.
// For a cpu or off-cpu profile this might be:
@@ -284,23 +299,35 @@
// The following fields 3-12 are informational, do not affect
// interpretation of results.
- // Time of collection. Value is UNIX Epoch time in nanoseconds since 00:00:00
- // UTC on 1 January 1970.
+ // Time of collection (UTC) as nanoseconds since the UNIX epoch.
fixed64 time_unix_nano = 3;
- // Duration of the profile. 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. This ensures Sample.timestamps_unix_nano values such as
- // allocation timestamp fall into the profile time range.
+ // 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.
uint64 duration_nano = 4;
- // The kind of events between sampled occurrences.
- // e.g [ "cpu","cycles" ] or [ "heap","bytes" ]
+ // 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.
ValueType period_type = 5;
- // The number of events between sampled occurrences.
+ // The distance between sampled occurrences for periodic sampling profiles.
+ // The value is of the period_type type and unit.
int64 period = 6;
// 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
+ // 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.
@@ -312,28 +339,20 @@
// attributes. If this value is 0, then no attributes were dropped.
uint32 dropped_attributes_count = 8;
- // The original payload format. See also original_payload. Optional, but the
- // format and the bytes must be set or unset together.
+ // 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 optionally provided when the conversion to the
- // OLTP format was done from a different format with some loss of the fidelity
- // and the receiver may want to store the original payload to allow future
- // lossless export or reinterpretation. Some examples of the original format
- // are JFR (Java Flight Recorder), pprof, Linux perf.
- //
- // Even when the original payload is in a format that is semantically close to
- // OTLP, such as pprof, a conversion may still be lossy in some cases (e.g. if
- // the pprof file contains custom extensions or conventions).
- //
- // The original payload can be large in size, so including the original
- // payload should be configurable by the profiler or collector options. The
- // default behavior should be to not include the original payload.
+ // 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.
string original_payload_format = 9;
- // The original payload bytes. See also original_payload_format. Optional, but
- // format and the bytes must be set or unset together.
+ // The original payload bytes. See also original_payload_format. It MUST be set
+ // together with original_payload_format or both left unset [optional].
bytes original_payload = 10;
// References to attributes in attribute_table. [optional]
@@ -342,8 +361,10 @@
// 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]
message Link {
- // A unique identifier of a trace that this linked span is part of. The ID is a
+ // A unique identifier of the trace that this linked span is part of. The ID is a
// 16-byte array.
bytes trace_id = 1;
@@ -352,6 +373,8 @@
}
// ValueType describes the type and units of a value.
+//
+// Status: [Alpha]
message ValueType {
// Index into ProfilesDictionary.string_table.
int32 type_strindex = 1;
@@ -365,56 +388,55 @@
// information like the thread-id, some indicator of a higher level request
// being handled etc.
//
-// A Sample MUST have have at least one values or timestamps_unix_nano entry. 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.
+// 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.
-// Samples having the same identity SHOULD be combined by inserting timestamps and values to the data arrays.
+// 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:
//
-// Report of a stacktrace at 10 timestamps (consumers must assume the value is 1 for each point):
+// 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]
//
-// Report of a stacktrace with an aggregated value without timestamps:
-// values: [10]
+// Single aggregated value without timestamps (one element representing the total):
+// values: [10]
// timestamps_unix_nano: []
//
-// Report of a stacktrace at 4 timestamps where each point records a specific value:
+// 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]
message Sample {
-
- // A Sample's identity (i.e. 'primary key') is the tuple of {stack_index, set_of(attribute_indices), link_index}
-
// Reference to stack in ProfilesDictionary.stack_table.
int32 stack_index = 1;
// References to attributes in ProfilesDictionary.attribute_table. [optional]
repeated int32 attribute_indices = 2;
// Reference to link in ProfilesDictionary.link_table. [optional]
- // It can be unset / set to 0 if no link exists, as link_table[0] is always a 'null' default value.
+ // 0 means no link exists.
int32 link_index = 3;
// The following fields may contain per-observation data and do not form part of the Sample's identity.
- // The type and unit of each value is defined by Profile.sample_type.
+ // Measured values. The type and unit of each value is defined by Profile.sample_type.
repeated int64 values = 4;
- // Timestamps associated with Sample. Value is UNIX Epoch time in nanoseconds
- // since 00:00:00 UTC on 1 January 1970. The timestamps should fall within the
- // [Profile.time_unix_nano, Profile.time_unix_nano + Profile.duration_nano)
- // time range.
+ // 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.
repeated fixed64 timestamps_unix_nano = 5;
}
// Describes the mapping of a binary in memory, including its address range,
// file offset, and metadata like build ID
+//
+// Status: [Alpha]
message Mapping {
// Address at which the binary (or DLL) is loaded into memory.
uint64 memory_start = 1;
@@ -423,33 +445,40 @@
// Offset in the binary that corresponds to the first mapped address.
uint64 file_offset = 3;
// 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]".
+ // disk for the main binary and shared libraries, or a virtual
+ // abstraction like "[vdso]".
int32 filename_strindex = 4; // Index into ProfilesDictionary.string_table.
// References to attributes in ProfilesDictionary.attribute_table. [optional]
repeated int32 attribute_indices = 5;
}
-// A Stack represents a stack trace as a list of locations.
+// 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]
message Stack {
// References to locations in ProfilesDictionary.location_table.
// The first location is the leaf frame.
repeated int32 location_indices = 1;
}
-// Describes function and line table debug information.
+// Contains function and line table debug information for a single frame.
+//
+// Status: [Alpha]
message Location {
// Reference to mapping in ProfilesDictionary.mapping_table.
- // It can be unset / set to 0 if the mapping is unknown or not applicable for
- // this profile type, as mapping_table[0] is always a 'null' default mapping.
+ // 0 means unknown or not applicable.
int32 mapping_index = 1;
// The instruction address for this location, if available. It
- // should be within [Mapping.memory_start...Mapping.memory_limit]
+ // 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.
uint64 address = 2;
- // Multiple line indicates this location has inlined functions,
+ // Multiple lines indicate this location has inlined functions,
// where the last entry represents the caller into which the
// preceding entries were inlined.
//
@@ -462,17 +491,22 @@
}
// Details a specific line in a source code, linked to a function.
+//
+// Status: [Alpha]
message Line {
// Reference to function in ProfilesDictionary.function_table.
int32 function_index = 1;
- // Line number in source code. 0 means unset.
+ // Line number in source code. 1-based, 0 means unset.
int64 line = 2;
- // Column number in source code. 0 means unset.
+ // Column number in source code. 1-based, 0 means unset.
int64 column = 3;
}
// Describes a function, including its human-readable name, system name,
-// source file, and starting line number in the source.
+// 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]
message Function {
// The function name. Empty string if not available.
int32 name_strindex = 1;
@@ -481,13 +515,16 @@
int32 system_name_strindex = 2;
// Source file containing the function. Empty string if not available.
int32 filename_strindex = 3;
- // Line number in source file. 0 means unset.
+ // Line number in source file. 1-based, 0 means unset.
int64 start_line = 4;
}
// A custom 'dictionary native' style of encoding attributes which is more convenient
// for profiles than opentelemetry.proto.common.v1.KeyValue
-// Specifically, uses the string table for keys and allows optional unit information.
+// Specifically, uses the ProfilesDictionary.string_table for keys
+// and allows optional unit information.
+//
+// Status: [Alpha]
message KeyValueAndUnit {
// The index into the string table for the attribute's key.
int32 key_strindex = 1;
@@ -495,5 +532,6 @@
opentelemetry.proto.common.v1.AnyValue value = 2;
// 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.
int32 unit_strindex = 3;
}
pkwarren
approved these changes
Jul 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.