[profiles] introduce semantic convention (#1188)

Signed-off-by: Florian Lehner <[email protected]> Co-authored-by: Joao Grassi <[email protected]>
open-telemetry · Sep 3, 2024 · 5654b20 · 5654b20
1 parent e2284b8
commit 5654b20
Show file tree

Hide file tree

Showing 9 changed files with 181 additions and 0 deletions.
diff --git a/.chloggen/profiles-convention.yaml b/.chloggen/profiles-convention.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: new_component
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: profile
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Introduce semantic convention for OTel Profiles.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1188]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -67,6 +67,7 @@ body:
         - area:otel
         - area:peer
         - area:process
+        - area:profile
         - area:rpc
         - area:server
         - area:service

diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -59,6 +59,7 @@ body:
         - area:otel
         - area:peer
         - area:process
+        - area:profile
         - area:rpc
         - area:server
         - area:service

diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -68,6 +68,7 @@ body:
         - area:otel
         - area:peer
         - area:process
+        - area:profile
         - area:rpc
         - area:server
         - area:service

diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
@@ -80,6 +80,7 @@ Currently, the following namespaces exist:
 - [OTel](otel.md)
 - [Peer](peer.md)
 - [Process](process.md)
+- [Profile](profile.md)
 - [RPC](rpc.md)
 - [Server](server.md)
 - [Service](service.md)

diff --git a/docs/attributes-registry/profile.md b/docs/attributes-registry/profile.md
@@ -0,0 +1,29 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Profile
+
+## Profile Frame Attributes
+
+Describes the origin of a single frame in a Profile.
+
+| Attribute            | Type   | Description                                              | Examples  | Stability                                                        |
+| -------------------- | ------ | -------------------------------------------------------- | --------- | ---------------------------------------------------------------- |
+| `profile.frame.type` | string | Describes the interpreter or compiler of a single frame. | `cpython` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+`profile.frame.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value     | Description                                                                                                                                                                                                                           | Stability                                                        |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `cpython` | [Python](<https://wikipedia.org/wiki/Python_(programming_language)>)                                                                                                                                                                  | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `dotnet`  | [.NET](https://wikipedia.org/wiki/.NET)                                                                                                                                                                                               | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `jvm`     | [JVM](https://wikipedia.org/wiki/Java_virtual_machine)                                                                                                                                                                                | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `kernel`  | [Kernel](<https://wikipedia.org/wiki/Kernel_(operating_system)>)                                                                                                                                                                      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `native`  | [C](<https://wikipedia.org/wiki/C_(programming_language)>), [C++](https://wikipedia.org/wiki/C%2B%2B), [Go](<https://wikipedia.org/wiki/Go_(programming_language)>), [Rust](<https://wikipedia.org/wiki/Rust_(programming_language)>) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `perl`    | [Perl](https://wikipedia.org/wiki/Perl)                                                                                                                                                                                               | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `php`     | [PHP](https://wikipedia.org/wiki/PHP)                                                                                                                                                                                                 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `ruby`    | [Ruby](<https://wikipedia.org/wiki/Ruby_(programming_language)>)                                                                                                                                                                      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `v8js`    | [V8JS](<https://wikipedia.org/wiki/V8_(JavaScript_engine)>)                                                                                                                                                                           | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
diff --git a/docs/general/profiles.md b/docs/general/profiles.md
@@ -0,0 +1,55 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Logs
+aliases: [docs/specs/semconv/general/profiles-general]
+--->
+
+# General Profiles Attributes
+
+**Status**: [Experimental][DocumentStatus]
+
+<!-- toc -->
+
+- [Frame types](#frame-types)
+
+<!-- tocstop -->
+
+The attributes described in this section are rather generic.
+They may be used in any Profiles record they apply to.
+
+## Frame types
+
+**Description:** Describes the origin of a single frame in a Profile.
+
+<!-- semconv profile.frame(full) -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`profile.frame.type`](/docs/attributes-registry/profile.md) | string | Describes the interpreter or compiler of a single frame. | `cpython` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+`profile.frame.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value  | Description | Stability |
+|---|---|---|
+| `cpython` | [Python](https://wikipedia.org/wiki/Python_(programming_language)) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `dotnet` | [.NET](https://wikipedia.org/wiki/.NET) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `jvm` | [JVM](https://wikipedia.org/wiki/Java_virtual_machine) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `kernel` | [Kernel](https://wikipedia.org/wiki/Kernel_(operating_system)) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `native` | [C](https://wikipedia.org/wiki/C_(programming_language)), [C++](https://wikipedia.org/wiki/C%2B%2B), [Go](https://wikipedia.org/wiki/Go_(programming_language)), [Rust](https://wikipedia.org/wiki/Rust_(programming_language)) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `perl` | [Perl](https://wikipedia.org/wiki/Perl) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `php` | [PHP](https://wikipedia.org/wiki/PHP) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `ruby` | [Ruby](https://wikipedia.org/wiki/Ruby_(programming_language)) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `v8js` | [V8JS](https://wikipedia.org/wiki/V8_(JavaScript_engine)) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/model/profiles/frame.yaml b/model/profiles/frame.yaml
@@ -0,0 +1,8 @@
+groups:
+  - id: profile.frame
+    type: attribute_group
+    brief: >
+      Describes the origin of a single frame in a Profile.
+    attributes:
+      - ref: profile.frame.type
+        requirement_level: recommended
diff --git a/model/registry/profile.yaml b/model/registry/profile.yaml
@@ -0,0 +1,63 @@
+groups:
+
+  - id: registry.profile.frame
+    type: attribute_group
+    brief: >
+      Describes the origin of a single frame in a Profile.
+    attributes:
+      - id: profile.frame.type
+        stability: experimental
+        brief: >
+          Describes the interpreter or compiler of a single frame.
+        examples: ['cpython']
+        type:
+          allow_custom_values: true
+          members:
+            - id: dotnet
+              brief: >
+                [.NET](https://wikipedia.org/wiki/.NET)
+              value: "dotnet"
+              stability: experimental
+            - id: jvm
+              brief: >
+                [JVM](https://wikipedia.org/wiki/Java_virtual_machine)
+              value: "jvm"
+              stability: experimental
+            - id: kernel
+              brief: >
+                [Kernel](https://wikipedia.org/wiki/Kernel_(operating_system))
+              value: "kernel"
+              stability: experimental
+            - id: native
+              brief: >
+                [C](https://wikipedia.org/wiki/C_(programming_language)),
+                [C++](https://wikipedia.org/wiki/C%2B%2B),
+                [Go](https://wikipedia.org/wiki/Go_(programming_language)),
+                [Rust](https://wikipedia.org/wiki/Rust_(programming_language))
+              value: "native"
+              stability: experimental
+            - id: perl
+              brief: >
+                [Perl](https://wikipedia.org/wiki/Perl)
+              value: "perl"
+              stability: experimental
+            - id: php
+              brief: >
+                [PHP](https://wikipedia.org/wiki/PHP)
+              value: "php"
+              stability: experimental
+            - id: cpython
+              brief: >
+                [Python](https://wikipedia.org/wiki/Python_(programming_language))
+              value: "cpython"
+              stability: experimental
+            - id: ruby
+              brief: >
+                [Ruby](https://wikipedia.org/wiki/Ruby_(programming_language))
+              value: "ruby"
+              stability: experimental
+            - id: v8js
+              brief: >
+                [V8JS](https://wikipedia.org/wiki/V8_(JavaScript_engine))
+              value: "v8js"
+              stability: experimental