Rename enduser attributes for v3 preview (#18795)

Author: trask

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/config/internal/CommonConfig.java

@@ -25,7 +25,7 @@ public final class CommonConfig {
   private final List<String> serverRequestHeaders;
   private final List<String> serverResponseHeaders;
   private final Set<String> knownHttpRequestMethods;
-  private final EnduserConfig enduserConfig;
+  private final UserConfig userConfig;
   private final boolean emitExperimentalHttpClientTelemetry;
   private final boolean emitExperimentalHttpServerTelemetry;
   private final Set<String> sensitiveQueryParameters;
@@ -87,14 +87,14 @@ public CommonConfig(OpenTelemetry openTelemetry) {
             .get("http")
             .get("server")
             .getBoolean("emit_experimental_telemetry/development", false);
-    enduserConfig = new EnduserConfig(commonConfig);
+    v3Preview = commonConfig.getBoolean("v3_preview", false);
+    userConfig = new UserConfig(commonConfig, v3Preview);
     loggingTraceIdKey =
         commonConfig.get("logging").getString("trace_id", LoggingContextConstants.TRACE_ID);
     loggingSpanIdKey =
         commonConfig.get("logging").getString("span_id", LoggingContextConstants.SPAN_ID);
     loggingTraceFlagsKey =
         commonConfig.get("logging").getString("trace_flags", LoggingContextConstants.TRACE_FLAGS);
-    v3Preview = commonConfig.getBoolean("v3_preview", false);
   }
 
   public List<String> getClientRequestHeaders() {
@@ -117,8 +117,8 @@ public Set<String> getKnownHttpRequestMethods() {
     return knownHttpRequestMethods;
   }
 
-  public EnduserConfig getEnduserConfig() {
-    return enduserConfig;
+  public UserConfig getUserConfig() {
+    return userConfig;
   }
 
   public boolean shouldEmitExperimentalHttpClientTelemetry() {

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/config/internal/EnduserConfig.java

@@ -0,0 +1,118 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.config.internal;
+
+import static java.util.Objects.requireNonNull;
+
+import io.opentelemetry.api.incubator.config.DeclarativeConfigProperties;
+
+/**
+ * Configuration that controls capturing the {@code enduser.*} or {@code user.*} semantic
+ * attributes.
+ *
+ * <p>When the v3 preview is enabled, this configuration reads the corresponding {@code user.*}
+ * properties instead. Legacy {@code enduser.*} properties and their associated attributes are not
+ * supported when v3 preview is enabled.
+ *
+ * <p>The {@code enduser.*} semantic attributes are not captured by default, due to this text in the
+ * specification:
+ *
+ * <blockquote>
+ *
+ * <p>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.
+ *
+ * </blockquote>
+ *
+ * <p>Capturing of the {@code enduser.*} semantic attributes can be individually enabled by
+ * configuring the following properties:
+ *
+ * <pre>
+ * otel.instrumentation.common.enduser.id.enabled=true
+ * otel.instrumentation.common.enduser.role.enabled=true
+ * otel.instrumentation.common.enduser.scope.enabled=true
+ * </pre>
+ *
+ * <p>When v3 preview is enabled, capturing of the {@code user.*} semantic attributes can be
+ * individually enabled by configuring the following properties:
+ *
+ * <pre>
+ * otel.instrumentation.common.user.name.enabled=true
+ * otel.instrumentation.common.user.roles.enabled=true
+ * </pre>
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
+ */
+public class UserConfig {
+
+  private final boolean nameEnabled;
+  private final boolean rolesEnabled;
+  private final boolean scopeEnabled;
+
+  UserConfig(DeclarativeConfigProperties commonConfig, boolean v3Preview) {
+    requireNonNull(commonConfig, "commonConfig must not be null");
+
+    /*
+     * Capturing enduser.* attributes is disabled by default, because of this requirement in the specification:
+     *
+     * 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.
+     *
+     * https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#general-identity-attributes
+     */
+    if (v3Preview) {
+      this.nameEnabled = commonConfig.get("user").get("name").getBoolean("enabled", false);
+      this.rolesEnabled = commonConfig.get("user").get("roles").getBoolean("enabled", false);
+      this.scopeEnabled = false;
+    } else {
+      this.nameEnabled = commonConfig.get("enduser").get("id").getBoolean("enabled", false);
+      this.rolesEnabled = commonConfig.get("enduser").get("role").getBoolean("enabled", false);
+      this.scopeEnabled = commonConfig.get("enduser").get("scope").getBoolean("enabled", false);
+    }
+  }
+
+  /**
+   * Returns true if capturing of any identity semantic attribute is enabled.
+   *
+   * <p>This flag can be used by capturing instrumentations to bypass all identity attribute
+   * capturing. In v3 preview mode, this corresponds to the {@code user.*} attributes; otherwise it
+   * corresponds to the {@code enduser.*} attributes.
+   */
+  public boolean isAnyEnabled() {
+    return this.nameEnabled || this.rolesEnabled || this.scopeEnabled;
+  }
+
+  /**
+   * Returns true if capturing the id semantic attribute is enabled.
+   *
+   * <p>In v3 preview mode, this controls the {@code user.name} attribute; otherwise it controls the
+   * {@code enduser.id} attribute.
+   */
+  public boolean isNameEnabled() {
+    return this.nameEnabled;
+  }
+
+  /**
+   * Returns true if capturing the role(s) semantic attribute is enabled.
+   *
+   * <p>In v3 preview mode, this controls the {@code user.roles} attribute; otherwise it controls
+   * the {@code enduser.role} attribute.
+   */
+  public boolean isRolesEnabled() {
+    return this.rolesEnabled;
+  }
+
+  /**
+   * Returns true if capturing the {@code enduser.scope} semantic attribute is enabled.
+   *
+   * <p>This is always disabled in v3 preview mode, since {@code enduser.scope} has no {@code
+   * user.*} equivalent.
+   */
+  public boolean isScopeEnabled() {
+    return this.scopeEnabled;
+  }
+}

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/config/internal/UserConfig.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.config.internal;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.RETURNS_DEEP_STUBS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import io.opentelemetry.api.incubator.config.DeclarativeConfigProperties;
+import org.junit.jupiter.api.Test;
+
+class UserConfigTest {
+
+  @Test
+  void readsEnduserConfigWhenV3PreviewIsDisabled() {
+    DeclarativeConfigProperties commonConfig =
+        mock(DeclarativeConfigProperties.class, RETURNS_DEEP_STUBS);
+    when(commonConfig.get("enduser").get("id").getBoolean("enabled", false)).thenReturn(false);
+    when(commonConfig.get("enduser").get("role").getBoolean("enabled", false)).thenReturn(true);
+    when(commonConfig.get("enduser").get("scope").getBoolean("enabled", false)).thenReturn(true);
+    when(commonConfig.get("user").get("name").getBoolean("enabled", false)).thenReturn(true);
+    when(commonConfig.get("user").get("roles").getBoolean("enabled", false)).thenReturn(false);
+
+    UserConfig userConfig = new UserConfig(commonConfig, false);
+
+    assertThat(userConfig.isNameEnabled()).isFalse();
+    assertThat(userConfig.isRolesEnabled()).isTrue();
+    assertThat(userConfig.isScopeEnabled()).isTrue();
+  }
+
+  @Test
+  void readsUserConfigWhenV3PreviewIsEnabled() {
+    DeclarativeConfigProperties commonConfig =
+        mock(DeclarativeConfigProperties.class, RETURNS_DEEP_STUBS);
+    when(commonConfig.get("enduser").get("id").getBoolean("enabled", false)).thenReturn(true);
+    when(commonConfig.get("enduser").get("role").getBoolean("enabled", false)).thenReturn(true);
+    when(commonConfig.get("enduser").get("scope").getBoolean("enabled", false)).thenReturn(true);
+    when(commonConfig.get("user").get("name").getBoolean("enabled", false)).thenReturn(false);
+    when(commonConfig.get("user").get("roles").getBoolean("enabled", false)).thenReturn(true);
+
+    UserConfig userConfig = new UserConfig(commonConfig, true);
+
+    assertThat(userConfig.isNameEnabled()).isFalse();
+    assertThat(userConfig.isRolesEnabled()).isTrue();
+    assertThat(userConfig.isScopeEnabled()).isFalse();
+  }
+}

instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/config/internal/UserConfigTest.java

@@ -70,7 +70,7 @@ private static boolean resolveV3Preview(OpenTelemetry openTelemetry) {
     if (value != null) {
       return value;
     }
-    return ConfigPropertiesUtil.getBoolean("otel.semconv-stability.v3-preview", false);
+    return ConfigPropertiesUtil.getBoolean("otel.instrumentation.common.v3-preview", false);
   }
 
   @SuppressWarnings("deprecation") // using deprecated config property fallback

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/SemconvStability.java

@@ -68,7 +68,7 @@ public Instrumenter<ServletRequestContext<REQUEST>, ServletResponseContext<RESPO
                 instrumentationName, GlobalOpenTelemetry.get(), httpAttributesGetter, accessor)
             .setCaptureRequestParameters(CAPTURE_REQUEST_PARAMETERS)
             .setCaptureExperimentalAttributes(CAPTURE_EXPERIMENTAL_ATTRIBUTES)
-            .setCaptureEnduserId(AgentCommonConfig.get().getEnduserConfig().isIdEnabled());
+            .setCaptureEnduserId(AgentCommonConfig.get().getUserConfig().isNameEnabled());
     for (ContextCustomizer<? super ServletRequestContext<REQUEST>> contextCustomizer :
         contextCustomizers) {
       builder.addContextCustomizer(contextCustomizer);

instrumentation/servlet/servlet-common/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/servlet/common/AgentServletInstrumenterBuilder.java

@@ -5,9 +5,11 @@
 
 package io.opentelemetry.javaagent.instrumentation.servlet.common;
 
+import static io.opentelemetry.instrumentation.api.internal.SemconvStability.v3Preview;
 import static io.opentelemetry.instrumentation.api.semconv.http.HttpServerRouteSource.SERVER;
 import static io.opentelemetry.instrumentation.api.semconv.http.HttpServerRouteSource.SERVER_FILTER;
 import static io.opentelemetry.semconv.incubating.EnduserIncubatingAttributes.ENDUSER_ID;
+import static io.opentelemetry.semconv.incubating.UserIncubatingAttributes.USER_NAME;
 import static java.util.Collections.emptyList;
 
 import io.opentelemetry.api.GlobalOpenTelemetry;
@@ -29,6 +31,7 @@
 import io.opentelemetry.javaagent.bootstrap.servlet.ServletAsyncContext;
 import io.opentelemetry.javaagent.bootstrap.servlet.ServletContextPath;
 import io.opentelemetry.semconv.incubating.EnduserIncubatingAttributes;
+import io.opentelemetry.semconv.incubating.UserIncubatingAttributes;
 import java.security.Principal;
 import java.util.List;
 import java.util.function.Function;
@@ -166,21 +169,22 @@ private void captureRequestParameters(Span serverSpan, REQUEST request) {
   }
 
   /**
-   * Capture {@link EnduserIncubatingAttributes#ENDUSER_ID} as span attributes when SERVER span is
-   * not created by servlet instrumentation.
+   * Capture {@link EnduserIncubatingAttributes#ENDUSER_ID}, or {@link
+   * UserIncubatingAttributes#USER_NAME} when v3 preview is enabled, as a span attribute when SERVER
+   * span is not created by servlet instrumentation.
    *
    * <p>When SERVER span is created by servlet instrumentation we register {@link
    * ServletAdditionalAttributesExtractor} as an attribute extractor. When SERVER span is not
    * created by servlet instrumentation we call this method on exit from the last servlet or filter.
    */
   private void captureEnduserId(Span serverSpan, REQUEST request) {
-    if (!AgentCommonConfig.get().getEnduserConfig().isIdEnabled()) {
+    if (!AgentCommonConfig.get().getUserConfig().isNameEnabled()) {
       return;
     }
 
     Principal principal = accessor.getRequestUserPrincipal(request);
     if (principal != null) {
-      serverSpan.setAttribute(ENDUSER_ID, principal.getName());
+      serverSpan.setAttribute(v3Preview() ? USER_NAME : ENDUSER_ID, principal.getName());
     }
   }
 

instrumentation/servlet/servlet-common/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/servlet/common/BaseServletHelper.java

@@ -11,6 +11,7 @@
 import io.opentelemetry.api.common.AttributesBuilder;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
+import io.opentelemetry.instrumentation.api.internal.SemconvStability;
 import java.security.Principal;
 import javax.annotation.Nullable;
 
@@ -24,6 +25,8 @@ public class ServletAdditionalAttributesExtractor<REQUEST, RESPONSE>
 
   // copied from EnduserIncubatingAttributes
   private static final AttributeKey<String> ENDUSER_ID = AttributeKey.stringKey("enduser.id");
+  // copied from UserIncubatingAttributes
+  private static final AttributeKey<String> USER_NAME = AttributeKey.stringKey("user.name");
   private static final AttributeKey<Long> SERVLET_TIMEOUT = longKey("servlet.timeout");
 
   private final ServletAccessor<REQUEST, RESPONSE> accessor;
@@ -55,7 +58,7 @@ public void onEnd(
     if (captureEnduserId) {
       Principal principal = accessor.getRequestUserPrincipal(requestContext.request());
       if (principal != null) {
-        attributes.put(ENDUSER_ID, principal.getName());
+        attributes.put(SemconvStability.v3Preview() ? USER_NAME : ENDUSER_ID, principal.getName());
       }
     }
     if (!captureExperimentalAttributes) {