Update the semantic conventions version to 1.40.0

.github/scripts/update-semconv-version.sh

@@ -15,7 +15,7 @@ sed -Ei "s/(    semanticConventionsVersion,)/\1\n    \"$old_version\",/" build.g
 
 # Add new version constant to SchemaUrls.java
 version_underscore=${version//./_}
-sed -Ei "s/(public final class SchemaUrls \{)/\1\n\n  public static final String V${version_underscore} = \"https:\/\/opentelemetry.io\/schemas\/${version}\";/" \
+sed -Ei "s/(public final class SchemaUrls \{)/\1\n  public static final String V${version_underscore} = \"https:\/\/opentelemetry.io\/schemas\/${version}\";/" \
   semconv/src/main/java/io/opentelemetry/semconv/SchemaUrls.java
 
 # Add changelog entry

.github/workflows/auto-update-semconv.yml

@@ -82,6 +82,9 @@ jobs:
       - name: Apply formatting
         run: ./gradlew spotlessApply
 
+      - name: Generate API diffs
+        run: ./gradlew jApiCmp
+
       - name: Use CLA approved bot
         run: .github/scripts/use-cla-approved-bot.sh
 
@@ -99,6 +102,7 @@ jobs:
           git checkout -b $branch
           git add -u
           git add semconv**/src/main/java
+          git add docs/apidiffs/
           git commit -m "$message"
           git push --set-upstream origin $branch
           pr_url=$(gh pr create --title "$message" \

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+* Bump to semconv v1.40.0
+  ([#418](https://github.com/open-telemetry/semantic-conventions-java/pull/418))
+
 ## Version 1.39.0 (2026-01-28)
 
 * Bump to semconv v1.39.0

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.39.0"
+var semanticConventionsVersion = "1.40.0"
 val schemaUrlVersions = listOf(
     semanticConventionsVersion,
+    "1.39.0",
     "1.38.0",
     "1.37.0",
     "1.36.0",

buildscripts/templates/registry/incubating_java/IncubatingSemanticAttributes.java.j2

@@ -23,11 +23,14 @@
  */
 package io.opentelemetry.semconv.incubating;
 
+import static io.opentelemetry.api.common.AttributeKey.booleanArrayKey;
 import static io.opentelemetry.api.common.AttributeKey.booleanKey;
+import static io.opentelemetry.api.common.AttributeKey.doubleArrayKey;
 import static io.opentelemetry.api.common.AttributeKey.doubleKey;
+import static io.opentelemetry.api.common.AttributeKey.longArrayKey;
 import static io.opentelemetry.api.common.AttributeKey.longKey;
-import static io.opentelemetry.api.common.AttributeKey.stringKey;
 import static io.opentelemetry.api.common.AttributeKey.stringArrayKey;
+import static io.opentelemetry.api.common.AttributeKey.stringKey;
 
 import static io.opentelemetry.semconv.AttributeKeyTemplate.stringArrayKeyTemplate;
 import static io.opentelemetry.semconv.AttributeKeyTemplate.stringKeyTemplate;

buildscripts/templates/registry/java/SemanticAttributes.java.j2

@@ -22,11 +22,14 @@
  */
 package io.opentelemetry.semconv;
 
+import static io.opentelemetry.api.common.AttributeKey.booleanArrayKey;
 import static io.opentelemetry.api.common.AttributeKey.booleanKey;
+import static io.opentelemetry.api.common.AttributeKey.doubleArrayKey;
 import static io.opentelemetry.api.common.AttributeKey.doubleKey;
+import static io.opentelemetry.api.common.AttributeKey.longArrayKey;
 import static io.opentelemetry.api.common.AttributeKey.longKey;
-import static io.opentelemetry.api.common.AttributeKey.stringKey;
 import static io.opentelemetry.api.common.AttributeKey.stringArrayKey;
+import static io.opentelemetry.api.common.AttributeKey.stringKey;
 
 import static io.opentelemetry.semconv.AttributeKeyTemplate.stringArrayKeyTemplate;
 import static io.opentelemetry.semconv.AttributeKeyTemplate.stringKeyTemplate;

docs/apidiffs/current_vs_latest/opentelemetry-semconv.txt

@@ -1,2 +1,8 @@
-Comparing source compatibility of opentelemetry-semconv-1.39.0-SNAPSHOT.jar against opentelemetry-semconv-1.39.0.jar
-No changes.
+Comparing source compatibility of opentelemetry-semconv-1.40.0-SNAPSHOT.jar against opentelemetry-semconv-1.39.0.jar
+***  MODIFIED CLASS: PUBLIC FINAL io.opentelemetry.semconv.SchemaUrls  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) java.lang.String V1_40_0
+***  MODIFIED CLASS: PUBLIC FINAL io.opentelemetry.semconv.ServiceAttributes  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.common.AttributeKey<java.lang.String> SERVICE_INSTANCE_ID
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.api.common.AttributeKey<java.lang.String> SERVICE_NAMESPACE

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

@@ -425,6 +425,11 @@ public final class DbIncubatingAttributes {
    * href="/docs/db/database-spans.md#generating-a-summary-of-the-query">Generating query
    * summary</a> section.
    *
+   * <p>For batch operations, if the individual operations are known to have the same query summary
+   * then that query summary SHOULD be used prepended by {@code BATCH }, otherwise {@code
+   * db.query.summary} SHOULD be {@code BATCH} or some other database system specific term if more
+   * applicable.
+   *
    * @deprecated deprecated in favor of stable {@link
    *     io.opentelemetry.semconv.DbAttributes#DB_QUERY_SUMMARY} attribute.
    */

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

@@ -24,8 +24,11 @@ public final class ErrorIncubatingAttributes {
    *
    * <p>{@code error.message} is NOT RECOMMENDED for metrics or spans due to its unbounded
    * cardinality and overlap with span status.
+   *
+   * @deprecated Use domain-specific error message attribute. For example, use {@code
+   *     feature_flag.error.message} for feature flag errors.
    */
-  public static final AttributeKey<String> ERROR_MESSAGE = stringKey("error.message");
+  @Deprecated public static final AttributeKey<String> ERROR_MESSAGE = stringKey("error.message");
 
   /**
    * Describes a class of error the operation ended with.

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

@@ -16,6 +16,16 @@ public final class ExceptionIncubatingAttributes {
   /**
    * The exception message.
    *
+   * <p>Notes:
+   *
+   * <blockquote>
+   *
+   * [!WARNING]
+   *
+   * <p>This attribute may contain sensitive information.
+   *
+   * </blockquote>
+   *
    * @deprecated deprecated in favor of stable {@link
    *     io.opentelemetry.semconv.ExceptionAttributes#EXCEPTION_MESSAGE} attribute.
    */

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

@@ -18,9 +18,16 @@ public final class FeatureFlagIncubatingAttributes {
       stringKey("feature_flag.context.id");
 
   /**
-   * Deprecated, use {@code error.message} instead.
+   * A message providing more detail about an error that occurred during feature flag evaluation in
+   * human-readable form.
+   */
+  public static final AttributeKey<String> FEATURE_FLAG_ERROR_MESSAGE =
+      stringKey("feature_flag.error.message");
+
+  /**
+   * Deprecated, use {@code feature_flag.error.message} instead.
    *
-   * @deprecated Replaced by {@code error.message}.
+   * @deprecated Replaced by {@code feature_flag.error.message}.
    */
   @Deprecated
   public static final AttributeKey<String> FEATURE_FLAG_EVALUATION_ERROR_MESSAGE =

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

@@ -176,6 +176,24 @@ public final class GcpIncubatingAttributes {
   public static final AttributeKey<String> GCP_GCE_INSTANCE_NAME =
       stringKey("gcp.gce.instance.name");
 
+  /** The name of the Instance Group Manager (IGM) that manages this VM, if any. */
+  public static final AttributeKey<String> GCP_GCE_INSTANCE_GROUP_MANAGER_NAME =
+      stringKey("gcp.gce.instance_group_manager.name");
+
+  /**
+   * The region of a <strong>regional</strong> Instance Group Manager (e.g., {@code us-central1}).
+   * Set this <strong>only</strong> when the IGM is regional.
+   */
+  public static final AttributeKey<String> GCP_GCE_INSTANCE_GROUP_MANAGER_REGION =
+      stringKey("gcp.gce.instance_group_manager.region");
+
+  /**
+   * The zone of a <strong>zonal</strong> Instance Group Manager (e.g., {@code us-central1-a}). Set
+   * this <strong>only</strong> when the IGM is zonal.
+   */
+  public static final AttributeKey<String> GCP_GCE_INSTANCE_GROUP_MANAGER_ZONE =
+      stringKey("gcp.gce.instance_group_manager.zone");
+
   // Enum definitions
 
   /** Values for {@link #GCP_APPHUB_SERVICE_CRITICALITY_TYPE}. */

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

@@ -27,6 +27,9 @@ public final class GenAiIncubatingAttributes {
   /** Human-readable name of the GenAI agent provided by the application. */
   public static final AttributeKey<String> GEN_AI_AGENT_NAME = stringKey("gen_ai.agent.name");
 
+  /** The version of the GenAI agent. */
+  public static final AttributeKey<String> GEN_AI_AGENT_VERSION = stringKey("gen_ai.agent.version");
+
   /**
    * Deprecated, use Event API to report completions contents.
    *
@@ -254,6 +257,20 @@ public final class GenAiIncubatingAttributes {
   public static final AttributeKey<String> GEN_AI_RESPONSE_MODEL =
       stringKey("gen_ai.response.model");
 
+  /**
+   * The query text used for retrieval.
+   *
+   * <p>Notes:
+   *
+   * <blockquote>
+   *
+   * [!Warning] This attribute may contain sensitive information.
+   *
+   * </blockquote>
+   */
+  public static final AttributeKey<String> GEN_AI_RETRIEVAL_QUERY_TEXT =
+      stringKey("gen_ai.retrieval.query.text");
+
   /**
    * Deprecated, use {@code gen_ai.provider.name} instead.
    *
@@ -290,6 +307,26 @@ public final class GenAiIncubatingAttributes {
    */
   public static final AttributeKey<String> GEN_AI_TOOL_TYPE = stringKey("gen_ai.tool.type");
 
+  /**
+   * The number of input tokens written to a provider-managed cache.
+   *
+   * <p>Notes:
+   *
+   * <p>The value SHOULD be included in {@code gen_ai.usage.input_tokens}.
+   */
+  public static final AttributeKey<Long> GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS =
+      longKey("gen_ai.usage.cache_creation.input_tokens");
+
+  /**
+   * The number of input tokens served from a provider-managed cache.
+   *
+   * <p>Notes:
+   *
+   * <p>The value SHOULD be included in {@code gen_ai.usage.input_tokens}.
+   */
+  public static final AttributeKey<Long> GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS =
+      longKey("gen_ai.usage.cache_read.input_tokens");
+
   /**
    * Deprecated, use {@code gen_ai.usage.output_tokens} instead.
    *
@@ -299,7 +336,16 @@ public final class GenAiIncubatingAttributes {
   public static final AttributeKey<Long> GEN_AI_USAGE_COMPLETION_TOKENS =
       longKey("gen_ai.usage.completion_tokens");
 
-  /** The number of tokens used in the GenAI input (prompt). */
+  /**
+   * The number of tokens used in the GenAI input (prompt).
+   *
+   * <p>Notes:
+   *
+   * <p>This value SHOULD include all types of input tokens, including cached tokens.
+   * Instrumentations SHOULD make a best effort to populate this value, using a total provided by
+   * the provider when available or, depending on the provider API, by summing different token types
+   * parsed from the provider output.
+   */
   public static final AttributeKey<Long> GEN_AI_USAGE_INPUT_TOKENS =
       longKey("gen_ai.usage.input_tokens");
 
@@ -381,6 +427,13 @@ public static final class GenAiOperationNameIncubatingValues {
      */
     public static final String EMBEDDINGS = "embeddings";
 
+    /**
+     * Retrieval operation such as <a
+     * href="https://platform.openai.com/docs/api-reference/vector-stores/search">OpenAI Search
+     * Vector Store API</a>
+     */
+    public static final String RETRIEVAL = "retrieval";
+
     /** Create GenAI agent */
     public static final String CREATE_AGENT = "create_agent";
 

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

@@ -113,8 +113,15 @@ public final class HttpIncubatingAttributes {
    * _OTHER}, then it MUST provide a way to override the list of known HTTP methods. If this
    * override is done via environment variable, then the environment variable MUST be named
    * OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive
-   * known HTTP methods (this list MUST be a full override of the default known method, it is not a
-   * list of known methods in addition to the defaults).
+   * known HTTP methods.
+   *
+   * <p>If this override is done via declarative configuration, then the list MUST be configurable
+   * via the {@code known_methods} property (an array of case-sensitive strings with minimum items
+   * 0) under {@code .instrumentation/development.general.http.client} and/or {@code
+   * .instrumentation/development.general.http.server}.
+   *
+   * <p>In either case, this list MUST be a full override of the default known methods, it is not a
+   * list of known methods in addition to the defaults.
    *
    * <p>HTTP method names are case-sensitive and {@code http.request.method} attribute value MUST
    * match a known HTTP method name exactly. Instrumentations for specific web frameworks that