diff --git a/.chloggen/add_enduser_pseudo_id.yaml b/.chloggen/add_enduser_pseudo_id.yaml new file mode 100644 index 0000000000..bb73caaa9c --- /dev/null +++ b/.chloggen/add_enduser_pseudo_id.yaml @@ -0,0 +1,23 @@ +# 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: enduser + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: introduce new attribute `enduser.pseudo.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: | + The new attribute `enduser.pseudo.id` is intended to provide an unique identifier of a pseudonymous enduser. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 4260363443..c0a8e29d2e 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -44,6 +44,7 @@ body: - area:disk - area:dns - area:dotnet + - area:enduser - area:elasticsearch - area:error - area:exception diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index df7f1023c5..84f6302cd7 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -36,6 +36,7 @@ body: - area:disk - area:dns - area:dotnet + - area:enduser - area:elasticsearch - area:error - area:exception diff --git a/docs/attributes-registry/enduser.md b/docs/attributes-registry/enduser.md index a8df586a66..2a140adf29 100644 --- a/docs/attributes-registry/enduser.md +++ b/docs/attributes-registry/enduser.md @@ -6,12 +6,23 @@ # Enduser +- [End User Attributes](#end-user-attributes) +- [Deprecated End User Attributes](#deprecated-end-user-attributes) + +## End User Attributes + +Describes the end user. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `enduser.id` | string | Unique identifier of an authenticated user in the system. | `username` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `enduser.pseudo.id` | string | Pseudonymous identifier of an end user. This identifier is unique to the user but does not reveal their actual identity. | `QdH5CAWJgqVT4rOr0qtumf` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + ## Deprecated End User Attributes -Describes deprecated enduser attributes. Complete enduser namespace has been deprecated +Describes deprecated enduser attributes. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `enduser.id` | string | Deprecated, use `user.id` instead. | `username` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `user.id` attribute. | -| `enduser.role` | string | Deprecated, use `user.roles` instead. | `admin` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `user.roles` attribute. | +| `enduser.role` | string | Actual/assumed role the client is making the request under extracted from token or application security context. | `admin` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | | `enduser.scope` | string | Deprecated, no replacement at this time. | `read:message, write:files` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | diff --git a/docs/general/attributes.md b/docs/general/attributes.md index 7366d37865..4a38a7a9e6 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -396,9 +396,8 @@ 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. | +| [`enduser.id`](/docs/attributes-registry/enduser.md) | string | Unique identifier of an authenticated user in the system. | `username` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`enduser.pseudo.id`](/docs/attributes-registry/enduser.md) | string | Pseudonymous identifier of an end user. This identifier is unique to the user but does not reveal their actual identity. | `QdH5CAWJgqVT4rOr0qtumf` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -439,6 +438,19 @@ Given the sensitive nature of this information, SDKs and exporters SHOULD drop t default and then provide a configuration parameter to turn on retention for use cases where the information is required and would not violate any policies or regulations. +Enduser attributes capture end user identity. They are likely to contain PII and should be populated, processed, and stored with caution. +Information about the end user is usually available on the client side (in a mobile or browser application). +Enduser attributes are populated by the user application in coordination with OpenTelemetry SDK. +Some OpenTelemetry distributions auto-collect this information from HTTP cookies. +When user information is available, it's RECOMMENDED to add it to all spans and events emitted in the scope +of operation initiated by this user. + +Application in coordination with OpenTelemetry SDK and Distro MAY propagate user information from the client application +to the front end and across different backend services using custom HTTP cookies and/or [Baggage]. + +Enduser information is collected and populated manually by user application or specialized components, +other instrumentations such as HTTP or RPC are not expected to populate these attributes by default. + ## General thread attributes These attributes may be used for any operation to store information about diff --git a/model/enduser/common.yaml b/model/enduser/common.yaml new file mode 100644 index 0000000000..053dc7da87 --- /dev/null +++ b/model/enduser/common.yaml @@ -0,0 +1,10 @@ +groups: + - id: identity + type: attribute_group + brief: > + Describes end user identity. + attributes: + - ref: enduser.id + requirement_level: recommended + - ref: enduser.pseudo.id + requirement_level: recommended diff --git a/model/enduser/deprecated/common.yaml b/model/enduser/deprecated/common.yaml deleted file mode 100644 index e17dde1bec..0000000000 --- a/model/enduser/deprecated/common.yaml +++ /dev/null @@ -1,12 +0,0 @@ -groups: - - id: identity - type: attribute_group - brief: > - These attributes may be used for any operation with an authenticated and/or authorized enduser. - attributes: - - ref: enduser.id - requirement_level: recommended - - ref: enduser.role - requirement_level: recommended - - ref: enduser.scope - requirement_level: recommended diff --git a/model/enduser/deprecated/registry-deprecated.yaml b/model/enduser/deprecated/registry-deprecated.yaml index 0f5723e19a..81cdd87ee9 100644 --- a/model/enduser/deprecated/registry-deprecated.yaml +++ b/model/enduser/deprecated/registry-deprecated.yaml @@ -2,23 +2,17 @@ groups: - id: registry.enduser.deprecated type: attribute_group display_name: Deprecated End User Attributes - brief: Describes deprecated enduser attributes. Complete enduser namespace has been deprecated + brief: "Describes deprecated enduser attributes." attributes: - - id: enduser.id - type: string - stability: experimental - deprecated: Replaced by `user.id` attribute. - brief: "Deprecated, use `user.id` instead." - examples: 'username' - id: enduser.role type: string + deprecated: "Removed." stability: experimental - deprecated: Replaced by `user.roles` attribute. - brief: "Deprecated, use `user.roles` instead." + brief: 'Deprecated, no replacement at this time.' examples: 'admin' - id: enduser.scope type: string + deprecated: "Removed." stability: experimental - deprecated: Removed. brief: "Deprecated, no replacement at this time." examples: 'read:message, write:files' diff --git a/model/enduser/registry.yaml b/model/enduser/registry.yaml new file mode 100644 index 0000000000..dc070fa5e4 --- /dev/null +++ b/model/enduser/registry.yaml @@ -0,0 +1,18 @@ +groups: + - id: registry.enduser + type: attribute_group + display_name: End User Attributes + brief: > + Describes the end user. + attributes: + - id: enduser.id + type: string + brief: "Unique identifier of an authenticated user in the system." + examples: [ 'username' ] + stability: development + - id: enduser.pseudo.id + type: string + stability: development + brief: > + Pseudonymous identifier of an end user. This identifier should be a random value that is not directly linked or associated with the end user's actual identity. + examples: ['QdH5CAWJgqVT4rOr0qtumf']