Add authentication sub-namespace to user

.chloggen/add_authentication_user_subnamespace.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: enhancement
+
+# 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: introduce subnamespace `user.authentication` with a new attribute `user.authentication.id`
+
+# 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: [1104]
+
+# (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: Update `identity` attributes under general attribute doc.

docs/attributes-registry/user.md

@@ -10,13 +10,20 @@
 
 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.
+| Attribute                | Type     | Description                                                                                                                                             | Examples                                           | Stability                                                        |
+| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
+| `user.authentication.id` | string   | Unique identifier of an authenticated user in the system. [1]                                                                                           | `S-1-5-21-202424912787-2692429404-2351956786-1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `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. [2]                                                                            | `364fc68eaf4c8acec74a4e52d7d1feaa`                 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `user.id`                | string   | Identifies a user interacting with a system regardless of user authentication status. This identifier may be unique only through best-effort means. [3] | `QdH5CAWJgqVT4rOr0qtumf`                           | ![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]:** The `user.authentication.id` MAY be used to identify a user attempting to authenticate if it's known at this stage.
+
+**[2]:** Useful if `user.authentication.id` or `user.name` contain confidential information and cannot be used.
+
+**[3]:** The `user.id`, when populated, is expected to be generated before user is authenticated and SHOULD NOT change after the user logs in. In browser scenarios `user.id` is usually stored in cookies.
+It's NOT RECOMMENDED to populate this attribute when unauthenticated users are not tracked or identified by the system.
+It can be a random guid or a hash of the user's IP address. This is different from `user.hash` which is a hash of a known `user.id` or `user.name`.

docs/general/attributes.md

@@ -409,9 +409,19 @@ 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 | 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. |
+| [`user.id`](/docs/attributes-registry/user.md) | string | Identifies a user interacting with a system regardless of user authentication status. This identifier may be unique only through best-effort means. [1] | `QdH5CAWJgqVT4rOr0qtumf` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`user.authentication.id`](/docs/attributes-registry/user.md) | string | Unique identifier of an authenticated user in the system. [3] | `S-1-5-21-202424912787-2692429404-2351956786-1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`user.roles`](/docs/attributes-registry/user.md) | string[] | Array of user roles at the time of the event. | `["admin", "reporting_user"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** The `user.id`, when populated, is expected to be generated before user is authenticated and SHOULD NOT change after the user logs in. In browser scenarios `user.id` is usually stored in cookies.
+It's NOT RECOMMENDED to populate this attribute when unauthenticated users are not tracked or identified by the system.
+It can be a random guid or a hash of the user's IP address. This is different from `user.hash` which is a hash of a known `user.id` or `user.name`.
+
+**[2]:** If instrumentation supports tracking unauthenticated users and if `user.authentication.id` is set, recommended otherwise.
+
+**[3]:** The `user.authentication.id` MAY be used to identify a user attempting to authenticate if it's known at this stage.
+
+
 
 
 <!-- markdownlint-restore -->

model/general.yaml

@@ -34,15 +34,16 @@ groups:
       - ref: peer.service
         requirement_level: recommended
   - id: identity
-    type: span
+    type: attribute_group
     brief: >
-      These attributes may be used for any operation with an authenticated and/or authorized enduser.
+      These attributes may be used for any operation with an authenticated and/or authorized user.
     attributes:
-      - ref: enduser.id
-        requirement_level: recommended
-      - ref: enduser.role
+      - ref: user.id
+        requirement_level:
+          conditionally_required: If instrumentation supports tracking unauthenticated users and if `user.authentication.id` is set, recommended otherwise.
+      - ref: user.authentication.id
         requirement_level: recommended
-      - ref: enduser.scope
+      - ref: user.roles
         requirement_level: recommended
   - id: thread
     type: span

model/registry/user.yaml

@@ -22,14 +22,28 @@ groups:
         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.
+          Useful if `user.authentication.id` or `user.name` contain confidential information and cannot be used.
         examples: ['364fc68eaf4c8acec74a4e52d7d1feaa']
       - id: user.id
         type: string
         stability: experimental
         brief: >
-          Unique identifier of the user.
+          Identifies a user interacting with a system regardless of user authentication status. This identifier may be unique only through best-effort means.
+        note: >
+          The `user.id`, when populated, is expected to be generated before user is authenticated and SHOULD NOT change after the user logs in.
+          In browser scenarios `user.id` is usually stored in cookies.
+
+          It's NOT RECOMMENDED to populate this attribute when unauthenticated users are not tracked or identified by the system.
+
+          It can be a random guid or a hash of the user's IP address. This is different from `user.hash` which is a hash of a known `user.id` or `user.name`.
+        examples: ['QdH5CAWJgqVT4rOr0qtumf']
+      - id: user.authentication.id
+        type: string
+        brief: Unique identifier of an authenticated user in the system.
+        note: >
+          The `user.authentication.id` MAY be used to identify a user attempting to authenticate if it's known at this stage.
         examples: ['S-1-5-21-202424912787-2692429404-2351956786-1000']
+        stability: experimental
       - id: user.name
         type: string
         stability: experimental