Address comments

Author: heyams

docs/attributes-registry/enduser.md

@@ -11,18 +11,18 @@
 
 ## End User Attributes
 
-Describes information about the end user, which can be used as a subdomain of browser, client, or user domains.
+Describes the end user.
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
-| <a id="enduser-id" href="#enduser-id">`enduser.id`</a> | string | Unique identifier of an authenticated user in the system. | `<authenticated_user_id>` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="enduser-id" href="#enduser-id">`enduser.id`</a> | string | Unique identifier of an authenticated user in the system. | `username` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="enduser-pseudo-id" href="#enduser-pseudo-id">`enduser.pseudo.id`</a> | 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 end user attributes.
+Describes deprecated enduser attributes.
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
 | <a id="enduser-role" href="#enduser-role">`enduser.role`</a> | 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)<br>Removed. |
-| <a id="enduser-scope" href="#enduser-scope">`enduser.scope`</a> | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Removed. |
+| <a id="enduser-scope" href="#enduser-scope">`enduser.scope`</a> | string | Deprecated, no replacement at this time. | `read:message, write:files` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Removed. |

docs/general/attributes.md

@@ -396,7 +396,7 @@ 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 | Unique identifier of an authenticated user in the system. | `<authenticated_user_id>` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`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) |
 
 <!-- markdownlint-restore -->
@@ -409,7 +409,47 @@ system. It is expected this information would be propagated unchanged from node-
 using the Baggage mechanism. These attributes should not be used to record system-to-system
 authentication attributes.
 
-`enduser.pseudo.id` attribute can be set by a specific client component, e.g. through a cookie out of the Span's HTTP request headers. Client side application should be able to stamp this attribute on any telemetry item emitted by the application whenever this cookie is available.
+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.
+
+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]<https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/baggage/api.md>.
+
+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
 

model/enduser/common.yaml

@@ -2,7 +2,7 @@ groups:
   - id: identity
     type: attribute_group
     brief: >
-      These attributes may be used for any operation with an authenticated and/or authorized enduser.
+      Describes end user identity.
     attributes:
       - ref: enduser.id
         requirement_level: recommended

model/enduser/deprecated/registry-deprecated.yaml

@@ -2,7 +2,7 @@ groups:
   - id: registry.enduser.deprecated
     type: attribute_group
     display_name: Deprecated End User Attributes
-    brief: "Describes deprecated end user attributes."
+    brief: "Describes deprecated enduser attributes."
     attributes:
       - id: enduser.role
         type: string
@@ -14,9 +14,5 @@ groups:
         type: string
         deprecated: "Removed."
         stability: experimental
-        brief: >
-          Scopes or granted authorities the client currently possesses extracted from token
-          or application security context. The value would come from the scope associated
-          with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3)
-          or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html).
+        brief: "Deprecated, no replacement at this time."
         examples: 'read:message, write:files'

model/enduser/registry.yaml

@@ -3,16 +3,16 @@ groups:
     type: attribute_group
     display_name: End User Attributes
     brief: >
-      Describes information about the end user, which can be used as a subdomain of browser, client, or user domains.
+      Describes the end user.
     attributes:
       - id: enduser.id
         type: string
         brief: "Unique identifier of an authenticated user in the system."
-        examples: [ '<authenticated_user_id>' ]
-        stability: experimental
+        examples: [ 'username' ]
+        stability: development
       - id: enduser.pseudo.id
         type: string
-        stability: experimental
+        stability: development
         brief: >
           Pseudonymous identifier of an end user. This identifier is unique to the user but does not reveal their actual identity.
         examples: ['QdH5CAWJgqVT4rOr0qtumf']