diff --git a/CHANGELOG.md b/CHANGELOG.md index eb9a1fc2..6fc8a4d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ The full list of changes can be found in the compare view for the respective rel ### Changed +- profiles: clarify the original payload field comments. [#722](https://github.com/open-telemetry/opentelemetry-proto/pull/722) - profiles: add a note about cardinality implications for attribute values. [#713](https://github.com/open-telemetry/opentelemetry-proto/pull/713) - profiles: rename line -> lines and sample -> samples since they are repeated fields. [#712](https://github.com/open-telemetry/opentelemetry-proto/pull/712) diff --git a/opentelemetry/proto/profiles/v1development/profiles.proto b/opentelemetry/proto/profiles/v1development/profiles.proto index d782f67f..05481bdb 100644 --- a/opentelemetry/proto/profiles/v1development/profiles.proto +++ b/opentelemetry/proto/profiles/v1development/profiles.proto @@ -305,15 +305,28 @@ message Profile { // attributes. If this value is 0, then no attributes were dropped. uint32 dropped_attributes_count = 9; - // Specifies format of the original payload. Common values are defined in semantic conventions. [required if original_payload is present] + // The original payload format. See also original_payload. Optional, but the + // format and the bytes must be set or unset together. + // + // 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. string original_payload_format = 10; - - // Original payload can be stored in this field. This can be useful for users who want to get the original payload. - // Formats such as JFR are highly extensible and can contain more information than what is defined in this spec. - // Inclusion of original payload should be configurable by the user. Default behavior should be to not include the original payload. - // If the original payload is in pprof format, it SHOULD not be included in this field. - // The field is optional, however if it is present then equivalent converted data should be populated in other fields - // of this message as far as is practicable. + // The original payload bytes. See also original_payload_format. Optional, but + // format and the bytes must be set or unset together. bytes original_payload = 11; // References to attributes in attribute_table. [optional]