search

open-telemetry / opentelemetry-proto

OpenTelemetry protocol (OTLP) specification and Protobuf definitions
https://opentelemetry.io/docs/specs/otlp/
Apache License 2.0
545 stars 242 forks source link

profiling spec - definition of common string values #555

Open jhalliday opened 1 month ago

jhalliday commented 1 month ago

The profiles.proto and pprofextended.proto formats use string values in various places, including 'location' (e.g. kernel, native, python, hotspot, php, ...), ValueType.unit (e.g. ["cpu","nanoseconds"], ["allocations","count"]", AttributeUnit.key and original_payload_format.

To ensure consistency and assist SDK developers in providing user-friendly interfaces, some definition of commonly used values for these would be beneficial. For example, original_payload_format could specify a http content-type like convention, 'major/minor' as in 'text/html', plus some values likely to be used for common formats, e.g. "javaflightrecorder/2.0".

For fields inherited from the pprof format, defined string values should where applicable be consistent with existing usage conventions. These may be 'well known' within the golang community, but not necessarily to users of other languages.

This issue can be used as a gathering place for suggestions of possible values, pending creation of a formal profiling semantic conventions effort that may subsume them.

jhalliday commented 1 month ago

proposal for original_payload_format field:

The string SHOULD use the format "major/minor", with major being a company, open source project or other owning organization and minor being a version number or other differentiating value within that scope.

The value "javaflightrecorder/2.0" SHOULD be used to represent OpenJDK Java Flight Recorder files (.jfr) of file format version 2.0. Note for the avoidance of doubt that this is the file format version as reported in 'jfr summary ', NOT the jfr tool version as reported by 'jfr version'. By extension, future revisions of the format SHOULD be expected to follow the same pattern, e.g. "javaflightrecorder/2.1".

tigrannajaryan commented 1 month ago

These may be 'well known' within the golang community, but not necessarily to users of other languages.

Are these 'well known` values officially written down anywhere in golang repo? If yes we could link to existing definitions.

... pending creation of a formal profiling semantic conventions effort that may subsume them.

Yes, if you plan adding a number of new conventions then https://github.com/open-telemetry/semantic-conventions is likely the best place for it.