Bump to semantic-conventions v1.31.0

Author: jack-berg

build.gradle.kts

@@ -11,9 +11,10 @@ val snapshot = true
 // end
 
 // The release version of https://github.com/open-telemetry/semantic-conventions used to generate classes
-var semanticConventionsVersion = "1.30.0"
+var semanticConventionsVersion = "1.31.0"
 val schemaUrlVersions = listOf(
     semanticConventionsVersion,
+    "1.30.0",
     "1.29.0",
     "1.28.0",
     "1.27.0",

docs/apidiffs/current_vs_latest/opentelemetry-semconv.txt

@@ -1,4 +1,4 @@
-Comparing source compatibility of opentelemetry-semconv-1.30.0-SNAPSHOT.jar against 
+Comparing source compatibility of opentelemetry-semconv-1.31.0-SNAPSHOT.jar against 
 +++  NEW CLASS: PUBLIC(+) FINAL(+) io.opentelemetry.semconv.AttributeKeyTemplate  (not serializable)
 	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
 	GENERIC TEMPLATES: +++ T:java.lang.Object
@@ -118,6 +118,7 @@ Comparing source compatibility of opentelemetry-semconv-1.30.0-SNAPSHOT.jar agai
 	+++  NEW SUPERCLASS: java.lang.Object
 	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) java.lang.String V1_24_0
 	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) java.lang.String V1_30_0
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) java.lang.String V1_31_0
 	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) java.lang.String V1_29_0
 	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) java.lang.String V1_28_0
 	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) java.lang.String V1_27_0

semconv-incubating/src/main/java/io/opentelemetry/semconv/incubating/AndroidIncubatingAttributes.java

@@ -13,6 +13,17 @@
 // buildscripts/templates/registry/incubating_java/IncubatingSemanticAttributes.java.j2
 @SuppressWarnings("unused")
 public final class AndroidIncubatingAttributes {
+  /**
+   * This attribute represents the state of the application.
+   *
+   * <p>Notes:
+   *
+   * <p>The Android lifecycle states are defined in <a
+   * href="https://developer.android.com/guide/components/activities/activity-lifecycle#lc">Activity
+   * lifecycle callbacks</a>, and from which the {@code OS identifiers} are derived.
+   */
+  public static final AttributeKey<String> ANDROID_APP_STATE = stringKey("android.app.state");
+
   /**
    * Uniquely identifies the framework API revision offered by a version ({@code os.version}) of the
    * android operating system. More information can be found <a
@@ -21,24 +32,46 @@ public final class AndroidIncubatingAttributes {
   public static final AttributeKey<String> ANDROID_OS_API_LEVEL = stringKey("android.os.api_level");
 
   /**
-   * Deprecated use the {@code device.app.lifecycle} event definition including {@code
-   * android.state} as a payload field instead.
+   * Deprecated. Use {@code android.app.state} instead.
    *
    * <p>Notes:
    *
    * <p>The Android lifecycle states are defined in <a
    * href="https://developer.android.com/guide/components/activities/activity-lifecycle#lc">Activity
    * lifecycle callbacks</a>, and from which the {@code OS identifiers} are derived.
    *
-   * @deprecated Replaced by {@code device.app.lifecycle}.
+   * @deprecated Renamed to {@code android.app.state}
    */
   @Deprecated public static final AttributeKey<String> ANDROID_STATE = stringKey("android.state");
 
   // Enum definitions
+  /** Values for {@link #ANDROID_APP_STATE}. */
+  public static final class AndroidAppStateIncubatingValues {
+    /**
+     * Any time before Activity.onResume() or, if the app has no Activity, Context.startService()
+     * has been called in the app for the first time.
+     */
+    public static final String CREATED = "created";
+
+    /**
+     * Any time after Activity.onPause() or, if the app has no Activity, Context.stopService() has
+     * been called when the app was in the foreground state.
+     */
+    public static final String BACKGROUND = "background";
+
+    /**
+     * Any time after Activity.onResume() or, if the app has no Activity, Context.startService() has
+     * been called when the app was in either the created or background states.
+     */
+    public static final String FOREGROUND = "foreground";
+
+    private AndroidAppStateIncubatingValues() {}
+  }
+
   /**
    * Values for {@link #ANDROID_STATE}
    *
-   * @deprecated Replaced by {@code device.app.lifecycle}.
+   * @deprecated Renamed to {@code android.app.state}
    */
   @Deprecated
   public static final class AndroidStateIncubatingValues {

semconv-incubating/src/main/java/io/opentelemetry/semconv/incubating/CicdIncubatingAttributes.java

@@ -26,6 +26,13 @@ public final class CicdIncubatingAttributes {
   public static final AttributeKey<String> CICD_PIPELINE_RUN_STATE =
       stringKey("cicd.pipeline.run.state");
 
+  /**
+   * The <a href="https://wikipedia.org/wiki/URL">URL</a> of the pipeline run, providing the
+   * complete address in order to locate and identify the pipeline run.
+   */
+  public static final AttributeKey<String> CICD_PIPELINE_RUN_URL_FULL =
+      stringKey("cicd.pipeline.run.url.full");
+
   /**
    * The human readable name of a task within a pipeline. Task here most closely aligns with a <a
    * href="https://wikipedia.org/wiki/Pipeline_(computing)">computing process</a> in a pipeline.
@@ -39,8 +46,8 @@ public final class CicdIncubatingAttributes {
       stringKey("cicd.pipeline.task.run.id");
 
   /**
-   * The <a href="https://wikipedia.org/wiki/URL">URL</a> of the pipeline run providing the complete
-   * address in order to locate and identify the pipeline run.
+   * The <a href="https://wikipedia.org/wiki/URL">URL</a> of the pipeline task run, providing the
+   * complete address in order to locate and identify the pipeline task run.
    */
   public static final AttributeKey<String> CICD_PIPELINE_TASK_RUN_URL_FULL =
       stringKey("cicd.pipeline.task.run.url.full");

semconv-incubating/src/main/java/io/opentelemetry/semconv/incubating/CloudIncubatingAttributes.java

@@ -58,8 +58,7 @@ public final class CloudIncubatingAttributes {
    * href="https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html">ARN</a> on
    * AWS, a <a href="https://learn.microsoft.com/rest/api/resources/resources/get-by-id">fully
    * qualified resource ID</a> on Azure, a <a
-   * href="https://cloud.google.com/apis/design/resource_names#full_resource_name">full resource
-   * name</a> on GCP)
+   * href="https://google.aip.dev/122#full-resource-names">full resource name</a> on GCP)
    *
    * <p>Notes:
    *

semconv-incubating/src/main/java/io/opentelemetry/semconv/incubating/CodeIncubatingAttributes.java

@@ -33,8 +33,12 @@ public final class CodeIncubatingAttributes {
    */
   public static final AttributeKey<String> CODE_FILE_PATH = stringKey("code.file.path");
 
-  /** Deprecated, use {@code code.file.path} instead */
-  public static final AttributeKey<String> CODE_FILEPATH = stringKey("code.filepath");
+  /**
+   * Deprecated, use {@code code.file.path} instead
+   *
+   * @deprecated Replaced by {@code code.file.path}
+   */
+  @Deprecated public static final AttributeKey<String> CODE_FILEPATH = stringKey("code.filepath");
 
   /**
    * Deprecated, use {@code code.function.name} instead
@@ -44,7 +48,30 @@ public final class CodeIncubatingAttributes {
   @Deprecated public static final AttributeKey<String> CODE_FUNCTION = stringKey("code.function");
 
   /**
-   * The method or function name, or equivalent (usually rightmost part of the code unit's name).
+   * The method or function fully-qualified name without arguments. The value should fit the natural
+   * representation of the language runtime, which is also likely the same used within {@code
+   * code.stacktrace} attribute value.
+   *
+   * <p>Notes:
+   *
+   * <p>Values and format depends on each language runtime, thus it is impossible to provide an
+   * exhaustive list of examples. The values are usually the same (or prefixes of) the ones found in
+   * native stack trace representation stored in {@code code.stacktrace} without information on
+   * arguments.
+   *
+   * <p>Examples:
+   *
+   * <ul>
+   *   <li>Java method: {@code com.example.MyHttpService.serveRequest}
+   *   <li>Java anonymous class method: {@code com.mycompany.Main$1.myMethod}
+   *   <li>Java lambda method: {@code com.mycompany.Main$$Lambda/0x0000748ae4149c00.myMethod}
+   *   <li>PHP function: `GuzzleHttp\Client::transfer
+   *   <li>Go function: {@code github.com/my/repo/pkg.foo.func5}
+   *   <li>Elixir: {@code OpenTelemetry.Ctx.new}
+   *   <li>Erlang: {@code opentelemetry_ctx:new}
+   *   <li>Rust: {@code playground::my_module::my_cool_func}
+   *   <li>C function: {@code fopen}
+   * </ul>
    */
   public static final AttributeKey<String> CODE_FUNCTION_NAME = stringKey("code.function.name");
 
@@ -62,15 +89,18 @@ public final class CodeIncubatingAttributes {
   @Deprecated public static final AttributeKey<Long> CODE_LINENO = longKey("code.lineno");
 
   /**
-   * The "namespace" within which {@code code.function.name} is defined. Usually the qualified class
-   * or module name, such that {@code code.namespace} + some separator + {@code code.function.name}
-   * form a unique identifier for the code unit.
+   * Deprecated, namespace is now included into {@code code.function.name}
+   *
+   * @deprecated Value should be included in {@code code.function.name} which is expected to be a
+   *     fully-qualified name.
    */
-  public static final AttributeKey<String> CODE_NAMESPACE = stringKey("code.namespace");
+  @Deprecated public static final AttributeKey<String> CODE_NAMESPACE = stringKey("code.namespace");
 
   /**
    * A stacktrace as a string in the natural representation for the language runtime. The
-   * representation is to be determined and documented by each language SIG.
+   * representation is identical to <a
+   * href="/docs/exceptions/exceptions-spans.md#stacktrace-representation">{@code
+   * exception.stacktrace}</a>.
    */
   public static final AttributeKey<String> CODE_STACKTRACE = stringKey("code.stacktrace");
 

semconv-incubating/src/main/java/io/opentelemetry/semconv/incubating/CpuIncubatingAttributes.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.semconv.incubating;
 
+import static io.opentelemetry.api.common.AttributeKey.longKey;
 import static io.opentelemetry.api.common.AttributeKey.stringKey;
 
 import io.opentelemetry.api.common.AttributeKey;
@@ -13,6 +14,9 @@
 // buildscripts/templates/registry/incubating_java/IncubatingSemanticAttributes.java.j2
 @SuppressWarnings("unused")
 public final class CpuIncubatingAttributes {
+  /** The logical CPU number [0..n-1] */
+  public static final AttributeKey<Long> CPU_LOGICAL_NUMBER = longKey("cpu.logical_number");
+
   /** The mode of the CPU */
   public static final AttributeKey<String> CPU_MODE = stringKey("cpu.mode");
 

semconv-incubating/src/main/java/io/opentelemetry/semconv/incubating/DbIncubatingAttributes.java

@@ -122,8 +122,8 @@ public final class DbIncubatingAttributes {
    * <p>It is RECOMMENDED to capture the value as provided by the application without attempting to
    * do any case normalization.
    *
-   * <p>The collection name SHOULD NOT be extracted from {@code db.query.text}, unless the query
-   * format is known to only ever have a single collection name present.
+   * <p>The collection name SHOULD NOT be extracted from {@code db.query.text}, when the database
+   * system supports cross-table queries in non-batch operations.
    *
    * <p>For batch operations, if the individual operations are known to have the same collection
    * name then that collection name SHOULD be used.
@@ -339,8 +339,8 @@ public final class DbIncubatingAttributes {
    * <p>It is RECOMMENDED to capture the value as provided by the application without attempting to
    * do any case normalization.
    *
-   * <p>The operation name SHOULD NOT be extracted from {@code db.query.text}, unless the query
-   * format is known to only ever have a single operation name present.
+   * <p>The operation name SHOULD NOT be extracted from {@code db.query.text}, when the database
+   * system supports cross-table queries in non-batch operations.
    *
    * <p>For batch operations, if the individual operations are known to have the same operation name
    * then that operation name SHOULD be used prepended by {@code BATCH }, otherwise {@code
@@ -383,8 +383,8 @@ public final class DbIncubatingAttributes {
    * database calls involving complex queries. Summary may be available to the instrumentation
    * through instrumentation hooks or other means. If it is not available, instrumentations that
    * support query parsing SHOULD generate a summary following <a
-   * href="../../docs/database/database-spans.md#generating-a-summary-of-the-query-text">Generating
-   * query summary</a> section.
+   * href="../database/database-spans.md#generating-a-summary-of-the-query-text">Generating query
+   * summary</a> section.
    */
   public static final AttributeKey<String> DB_QUERY_SUMMARY = stringKey("db.query.summary");
 
@@ -394,7 +394,7 @@ public final class DbIncubatingAttributes {
    * <p>Notes:
    *
    * <p>For sanitization see <a
-   * href="../../docs/database/database-spans.md#sanitization-of-dbquerytext">Sanitization of {@code
+   * href="../database/database-spans.md#sanitization-of-dbquerytext">Sanitization of {@code
    * db.query.text}</a>. For batch operations, if the individual operations are known to have the
    * same query text then that query text SHOULD be used, otherwise all of the individual query
    * texts SHOULD be concatenated with separator {@code ; } or some other database system specific

semconv-incubating/src/main/java/io/opentelemetry/semconv/incubating/EnduserIncubatingAttributes.java

@@ -14,11 +14,36 @@
 @SuppressWarnings("unused")
 public final class EnduserIncubatingAttributes {
   /**
-   * Deprecated, use {@code user.id} instead.
+   * Unique identifier of an end user in the system. It maybe a username, email address, or other
+   * identifier.
    *
-   * @deprecated Replaced by {@code user.id} attribute.
+   * <p>Notes:
+   *
+   * <p>Unique identifier of an end user in the system.
+   *
+   * <blockquote>
+   *
+   * [!Warning] This field contains sensitive (PII) information.
+   *
+   * </blockquote>
+   */
+  public static final AttributeKey<String> ENDUSER_ID = stringKey("enduser.id");
+
+  /**
+   * 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.
+   *
+   * <p>Notes:
+   *
+   * <p>Pseudonymous identifier of an end user.
+   *
+   * <blockquote>
+   *
+   * [!Warning] This field contains sensitive (linkable PII) information.
+   *
+   * </blockquote>
    */
-  @Deprecated public static final AttributeKey<String> ENDUSER_ID = stringKey("enduser.id");
+  public static final AttributeKey<String> ENDUSER_PSEUDO_ID = stringKey("enduser.pseudo.id");
 
   /**
    * Deprecated, use {@code user.roles} instead.