Skip to content

Commit

Permalink
Address comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@heyams
heyams committed Aug 8, 2024
1 parent 81d6360 commit bf8e35e
Show file tree
Hide file tree
Showing 5 changed files with 45 additions and 23 deletions.
4 changes: 2 additions & 2 deletions .chloggen/add_authentication_user_subnamespace.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@
# your pull request title with [chore] or use the "Skip Changelog" label.

# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
change_type: 'enhancement'
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 a new subnamespace `authentication` under `user` with a new attribute `user.authentication.id`
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.
Expand Down
30 changes: 17 additions & 13 deletions docs/attributes-registry/user.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,16 +10,20 @@

Describes information about the user.

| Attribute | Type | Description | Examples | Stability |
| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
| `user.authentication.id` | string | Unique identifier of an authenticated user in the system. | `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. [1] | `364fc68eaf4c8acec74a4e52d7d1feaa` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `user.id` | string | Identifier of a user who interacts with a system. This identifier may be unique only through best-effort means and does not imply that the user is authenticated to the system. [2] | `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]:** Useful if `user.id` or `user.name` contain confidential information and cannot be used.

**[2]:** 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`.
| 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`.
13 changes: 12 additions & 1 deletion docs/general/attributes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -409,9 +409,20 @@ 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 |
|---|---|---|---|---|---|
| [`user.authentication.id`](/docs/attributes-registry/user.md) | string | Unique identifier of an authenticated user in the system. | `S-1-5-21-202424912787-2692429404-2351956786-1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`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 -->
<!-- prettier-ignore-end -->
Expand Down
7 changes: 4 additions & 3 deletions model/general.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,13 @@ 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 user.
note: >
`enduser` namespace has been deprecated. When `user.authentication.id` is present, it is strongly recommended to provide `user.id` as well.
attributes:
- 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: user.roles
Expand Down
14 changes: 10 additions & 4 deletions model/registry/user.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,19 +22,25 @@ 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: >
Identifier of a user who interacts with a system. This identifier may be unique only through best-effort means and does not imply that the user is authenticated to the system.
note: >
Identifies a user interacting with a system regardless of user authentication status. This identifier may be unique only through best-effort means.
note: >

Check failure on line 32 in model/registry/user.yaml

View workflow job for this annotation

GitHub Actions / yamllint 

[trailing-spaces] trailing spaces
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.

Check failure on line 33 in model/registry/user.yaml

View workflow job for this annotation

GitHub Actions / yamllint 

[line-length] line too long (204 > 200 characters)
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."
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
Expand Down

0 comments on commit bf8e35e

Please sign in to comment.