diff --git a/.chloggen/add_enduser_pseudo_id.yaml b/.chloggen/add_enduser_pseudo_id.yaml new file mode 100644 index 0000000000..40881f1560 --- /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: Undeprecate 'enduser.id' and 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 a unique identifier of a pseudonymous enduser. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 4260363443..585224e32b 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -45,6 +45,7 @@ body: - area:dns - area:dotnet - area:elasticsearch + - area:enduser - area:error - area:exception - area:faas diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index df7f1023c5..a04b1977c2 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -37,6 +37,7 @@ body: - area:dns - area:dotnet - area:elasticsearch + - area:enduser - area:error - area:exception - area:faas diff --git a/docs/attributes-registry/enduser.md b/docs/attributes-registry/enduser.md index afdb4db386..32b23e62cc 100644 --- a/docs/attributes-registry/enduser.md +++ b/docs/attributes-registry/enduser.md @@ -3,12 +3,33 @@ # 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 end user in the system. It maybe a username, email address, or other identifier. [1] | `username` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `enduser.pseudo.id` | string | 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. [2] | `QdH5CAWJgqVT4rOr0qtumf` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `enduser.id`:** Unique identifier of an end user in the system. + +> [!Warning] +> This field contains sensitive (PII) information. + +**[2] `enduser.pseudo.id`:** Pseudonymous identifier of an end user. + +> [!Warning] +> This field contains sensitive (linkable PII) information. + ## 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.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 45b7d0004e..03d4b352b9 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -29,7 +29,6 @@ Particular operations may refer to or require some of these attributes. - [Client/server example with forward proxy](#clientserver-example-with-forward-proxy) - [Network connection and carrier attributes](#network-connection-and-carrier-attributes) - [General remote service attributes](#general-remote-service-attributes) -- [General identity attributes](#general-identity-attributes) - [General thread attributes](#general-thread-attributes) - [Source Code Attributes](#source-code-attributes) @@ -381,62 +380,6 @@ Examples of `peer.service` that users may specify: - A Redis cache of auth tokens as `peer.service="AuthTokenCache"`. - A gRPC service `rpc.service="io.opentelemetry.AuthService"` may be hosted in both a gateway, `peer.service="ExternalApiService"` and a backend, `peer.service="AuthService"`. -## General identity attributes - -These attributes may be used for any operation with an authenticated and/or authorized enduser. - - - - - - - - -| 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. | - - - - - - -These attributes describe the authenticated user driving the user agent making requests to the instrumented -system. It is expected this information would be propagated unchanged from node-to-node within the system -using the Baggage mechanism. These attributes should not be used to record system-to-system -authentication attributes. - -Examples of where the `enduser.id` value is extracted from: - -| Authentication protocol | Field or description | -| :---------------------- | :------------------------------ | -| [HTTP Basic/Digest Authentication] | `username` | -| [OAuth 2.0 Bearer Token] | [OAuth 2.0 Client Identifier] value from `client_id` for the [OAuth 2.0 Client Credentials Grant] flow and `subject` or `username` from get token info response for other flows using opaque tokens. | -| [OpenID Connect 1.0 IDToken] | `sub` | -| [SAML 2.0 Assertion] | `urn:oasis:names:tc:SAML:2.0:assertion:Subject` | -| [Kerberos] | `PrincipalName` | - -| Framework | Field or description | -| :---------------------- | :------------------------------ | -| [JavaEE/JakartaEE Servlet] | `javax.servlet.http.HttpServletRequest.getUserPrincipal()` | -| [Windows Communication Foundation] | `ServiceSecurityContext.Current.PrimaryIdentity` | - -[SAML 2.0 Assertion]: http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html -[HTTP Basic/Digest Authentication]: https://tools.ietf.org/html/rfc2617 -[OAuth 2.0 Bearer Token]: https://tools.ietf.org/html/rfc6750 -[OAuth 2.0 Client Identifier]: https://tools.ietf.org/html/rfc6749#section-2.2 -[OAuth 2.0 Client Credentials Grant]: https://tools.ietf.org/html/rfc6749#section-4.4 -[OpenID Connect 1.0 IDToken]: https://openid.net/specs/openid-connect-core-1_0.html#IDToken -[Kerberos]: https://tools.ietf.org/html/rfc4120 -[JavaEE/JakartaEE Servlet]: https://jakarta.ee/specifications/platform/8/apidocs/javax/servlet/http/HttpServletRequest.html -[Windows Communication Foundation]: https://docs.microsoft.com/dotnet/api/system.servicemodel.servicesecuritycontext?view=netframework-4.8 - -Given the sensitive nature of this information, SDKs and exporters SHOULD drop these attributes by -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. - ## General thread attributes These attributes may be used for any operation to store information about 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..7ea649fe65 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: "Replaced by `user.roles` attribute." stability: experimental - deprecated: Replaced by `user.roles` attribute. brief: "Deprecated, use `user.roles` instead." 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..84b038e962 --- /dev/null +++ b/model/enduser/registry.yaml @@ -0,0 +1,28 @@ +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 end user in the system. It maybe a username, email address, or other identifier." + note: | + Unique identifier of an end user in the system. + + > [!Warning] + > This field contains sensitive (PII) information. + 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. + note: | + Pseudonymous identifier of an end user. + + > [!Warning] + > This field contains sensitive (linkable PII) information. + examples: ['QdH5CAWJgqVT4rOr0qtumf']