diff --git a/.chloggen/add_authentication_user_subnamespace.yaml b/.chloggen/add_authentication_user_subnamespace.yaml new file mode 100644 index 0000000000..df80f22dfe --- /dev/null +++ b/.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. diff --git a/docs/attributes-registry/user.md b/docs/attributes-registry/user.md index 1268d2c848..4cc6cf05d1 100644 --- a/docs/attributes-registry/user.md +++ b/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.authentication.id` or `user.name`. diff --git a/docs/general/attributes.md b/docs/general/attributes.md index a1ce082ad6..bb0290c9c0 100644 --- a/docs/general/attributes.md +++ b/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)
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)
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)
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.authentication.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. + + diff --git a/model/general.yaml b/model/general.yaml index 85377316e1..8c8157469d 100644 --- a/model/general.yaml +++ b/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 diff --git a/model/registry/user.yaml b/model/registry/user.yaml index e7e518c20b..a3c0fe8011 100644 --- a/model/registry/user.yaml +++ b/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.authentication.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