[BREAKING] Add ECS user namespace (#731)

Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
2024-05-28 22:32:45 +02:00 · 2024-05-28 22:32:45 +02:00 · 7da6842f9d
parent cb771da926
commit 7da6842f9d
12 changed files with 132 additions and 42 deletions
--- 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:
--- 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
--- 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
--- 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
--- 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)

--- 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) |
+| --------------- | ------ | ---------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
+| `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.                            |
--- 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.                                                          | `a.einstein@example.com`                           | ![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.
--- 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 -->
--- 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'
--- a/model/registry/enduser.yaml
+++ b/model/registry/enduser.yaml
@ -1,29 +0,0 @@
-groups:
-  - id: registry.enduser
-    prefix: enduser
-    type: attribute_group
-    brief: >
-      This document defines attributes for operations with an authenticated and/or authorized enduser.
-    attributes:
-      - id: id
-        type: string
-        stability: experimental
-        brief: >
-          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.
-        examples: 'username'
-      - id: role
-        type: string
-        stability: experimental
-        brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.'
-        examples: 'admin'
-      - id: scope
-        type: string
-        stability: experimental
-        brief: >
-          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).
-        examples: 'read:message, write:files'
--- 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: ['a.einstein@example.com']
+      - 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"]
--- 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: