[BREAKING] Add ECS user namespace (open-telemetry#731)

Co-authored-by: Liudmila Molkova <[email protected]>
breedx-splk · May 28, 2024 · 7da6842 · 7da6842
1 parent cb771da
commit 7da6842
Show file tree

Hide file tree

Showing 12 changed files with 132 additions and 42 deletions.
diff --git a/.chloggen/user_ns.yaml b/.chloggen/user_ns.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: user
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: BREAKING - deprecate `enduser` in favor of a new `user` namespace. Add more `user` attributes.
+
+# 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: [731]
+
+# (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
@@ -34,7 +34,6 @@ body:
         - area:device
         - area:disk
         - area:dns
-        - area:enduser
         - area:error
         - area:event
         - area:exception
@@ -71,6 +70,7 @@ body:
         - area:tls
         - area:url
         - area:user-agent
+        - area:user
         - area:webengine
         # End semconv area list
   - type: textarea

diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -27,7 +27,6 @@ body:
         - area:device
         - area:disk
         - area:dns
-        - area:enduser
         - area:error
         - area:event
         - area:exception
@@ -64,6 +63,7 @@ body:
         - area:tls
         - area:url
         - area:user-agent
+        - area:user
         - area:webengine
         # End semconv area list
   - type: textarea

diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -36,7 +36,6 @@ body:
         - area:device
         - area:disk
         - area:dns
-        - area:enduser
         - area:error
         - area:event
         - area:exception
@@ -73,6 +72,7 @@ body:
         - area:tls
         - area:url
         - area:user-agent
+        - area:user
         - area:webengine
         # End semconv area list
   - type: textarea

diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
@@ -83,6 +83,7 @@ Currently, the following namespaces exist:
 - [Thread](thread.md)
 - [TLS](tls.md)
 - [URL](url.md)
+- [User](user.md)
 - [User Agent](user-agent.md)
 - [Webengine](webengine.md)
 

diff --git a/docs/attributes-registry/enduser.md b/docs/attributes-registry/enduser.md
@@ -6,12 +6,12 @@
 
 # Enduser
 
-## Enduser Attributes
+## Enduser Deprecated Attributes
 
-This document defines attributes for operations with an authenticated and/or authorized enduser.
+Describes deprecated enduser attributes. Complete enduser namespace has been deprecated
 
-| Attribute       | Type   | Description                                                                                                                                                                                                                                                                                                                                                                             | Examples                    | Stability                                                        |
-| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------- |
-| `enduser.id`    | string | Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) header in the inbound request from outside the system.                                                                                                                                                                                                        | `username`                  | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `enduser.role`  | string | Actual/assumed role the client is making the request under extracted from token or application security context.                                                                                                                                                                                                                                                                        | `admin`                     | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `enduser.scope` | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| Attribute       | Type   | Description                              | Examples                    | Stability                                                                                          |
+| --------------- | ------ | ---------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
+| `enduser.id`    | string | Deprecated, use `user.id` instead.       | `username`                  | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `user.id` attribute.    |
+| `enduser.role`  | string | Deprecated, use `user.roles` instead.    | `admin`                     | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `user.roles` attribute. |
+| `enduser.scope` | string | Deprecated, no replacement at this time. | `read:message, write:files` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Removed.                            |
diff --git a/docs/attributes-registry/user.md b/docs/attributes-registry/user.md
@@ -0,0 +1,22 @@
+<!--- 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 -->
+
+# User
+
+## User Attributes
+
+Describes information about the user.
+
+| Attribute        | Type     | Description                                                                  | Examples                                           | Stability                                                        |
+| ---------------- | -------- | ---------------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
+| `user.email`     | string   | User email address.                                                          | `[email protected]`                           | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `user.full_name` | string   | User's full name                                                             | `Albert Einstein`                                  | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `user.hash`      | string   | Unique user hash to correlate information for a user in anonymized form. [1] | `364fc68eaf4c8acec74a4e52d7d1feaa`                 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `user.id`        | string   | Unique identifier of the user.                                               | `S-1-5-21-202424912787-2692429404-2351956786-1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `user.name`      | string   | Short name or login/username of the user.                                    | `a.einstein`                                       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `user.roles`     | string[] | Array of user roles at the time of the event.                                | `admin`; `reporting_user`                          | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Useful if `user.id` or `user.name` contain confidential information and cannot be used.
diff --git a/docs/general/attributes.md b/docs/general/attributes.md
@@ -408,9 +408,9 @@ These attributes may be used for any operation with an authenticated and/or auth
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| [`enduser.id`](/docs/attributes-registry/enduser.md) | string | Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) header in the inbound request from outside the system. | `username` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| [`enduser.role`](/docs/attributes-registry/enduser.md) | string | Actual/assumed role the client is making the request under extracted from token or application security context. | `admin` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| [`enduser.scope`](/docs/attributes-registry/enduser.md) | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`enduser.id`](/docs/attributes-registry/enduser.md) | string | Deprecated, use `user.id` instead. | `username` | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `user.id` attribute. |
+| [`enduser.role`](/docs/attributes-registry/enduser.md) | string | Deprecated, use `user.roles` instead. | `admin` | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `user.roles` attribute. |
+| [`enduser.scope`](/docs/attributes-registry/enduser.md) | string | Deprecated, no replacement at this time. | `read:message, write:files` | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Removed. |
 
 
 <!-- markdownlint-restore -->

diff --git a/model/registry/deprecated/enduser.yaml b/model/registry/deprecated/enduser.yaml
@@ -0,0 +1,24 @@
+groups:
+  - id: registry.enduser.deprecated
+    prefix: enduser
+    type: attribute_group
+    brief: Describes deprecated enduser attributes. Complete enduser namespace has been deprecated
+    attributes:
+      - id: id
+        type: string
+        stability: experimental
+        deprecated: Replaced by `user.id` attribute.
+        brief: "Deprecated, use `user.id` instead."
+        examples: 'username'
+      - id: role
+        type: string
+        stability: experimental
+        deprecated: Replaced by `user.roles` attribute.
+        brief: "Deprecated, use `user.roles` instead."
+        examples: 'admin'
+      - id: scope
+        type: string
+        stability: experimental
+        deprecated: Removed.
+        brief: "Deprecated, no replacement at this time."
+        examples: 'read:message, write:files'
diff --git a/model/registry/enduser.yaml b/model/registry/enduser.yaml
diff --git a/model/registry/user.yaml b/model/registry/user.yaml
@@ -0,0 +1,44 @@
+groups:
+  - id: registry.user
+    prefix: user
+    type: attribute_group
+    brief: "Describes information about the user."
+    attributes:
+      - id: email
+        type: string
+        stability: experimental
+        brief: >
+          User email address.
+        examples: ['[email protected]']
+      - id: full_name
+        type: string
+        stability: experimental
+        brief: >
+          User's full name
+        examples: ['Albert Einstein']
+      - id: hash
+        type: string
+        stability: experimental
+        brief: >
+          Unique user hash to correlate information for a user in anonymized form.
+        note: >
+          Useful if `user.id` or `user.name` contain confidential information and cannot be used.
+        examples: ['364fc68eaf4c8acec74a4e52d7d1feaa']
+      - id: id
+        type: string
+        stability: experimental
+        brief: >
+          Unique identifier of the user.
+        examples: ['S-1-5-21-202424912787-2692429404-2351956786-1000']
+      - id: name
+        type: string
+        stability: experimental
+        brief: >
+          Short name or login/username of the user.
+        examples: ['a.einstein']
+      - id: roles
+        type: string[]
+        stability: experimental
+        brief: >
+          Array of user roles at the time of the event.
+        examples: ["admin", "reporting_user"]
diff --git a/schema-next.yaml b/schema-next.yaml
@@ -36,6 +36,12 @@ versions:
               - db.client.connections.create_time
               - db.client.connections.wait_time
               - db.client.connections.use_time
+    all:
+      changes:
+        # https://github.com/open-telemetry/semantic-conventions/pull/731/
+        - rename_attributes:
+            attribute_map:
+              enduser.id: user.id
 
   1.25.0:
     spans: