diff --git a/.github/workflows/fi-core-typescript-tests.yml b/.github/workflows/fi-core-typescript-tests.yml
index 83aa36a67..f342b1d55 100644
--- a/.github/workflows/fi-core-typescript-tests.yml
+++ b/.github/workflows/fi-core-typescript-tests.yml
@@ -6,6 +6,7 @@ on:
paths:
- 'typescript/packages/fi-core/**'
- 'typescript/packages/fi-semantic-conventions/**'
+ - 'python/fi_instrumentation/fi_types.py'
- 'typescript/pnpm-lock.yaml'
- 'typescript/tsconfig*'
- '.github/workflows/fi-core-typescript-tests.yml'
@@ -14,6 +15,7 @@ on:
paths:
- 'typescript/packages/fi-core/**'
- 'typescript/packages/fi-semantic-conventions/**'
+ - 'python/fi_instrumentation/fi_types.py'
- 'typescript/pnpm-lock.yaml'
- 'typescript/tsconfig*'
- '.github/workflows/fi-core-typescript-tests.yml'
@@ -62,5 +64,6 @@ jobs:
ip link set lo up
export FI_CORE_PACKAGE_JSON="$1/node_modules/@traceai/fi-core/package.json"
"$2" --test "$3/typescript/packages/fi-core/test/provider-lifecycle.test.cjs" &&
+ "$2" "$3/typescript/node_modules/jest/bin/jest.js" --config "$3/typescript/packages/fi-semantic-conventions/jest.config.js" --runInBand --no-cache &&
"$2" "$3/typescript/node_modules/jest/bin/jest.js" --config "$3/typescript/packages/fi-core/jest.config.js" --runInBand
' sh "$RUNNER_TEMP/sdk-fixture" "$NODE" "$GITHUB_WORKSPACE"
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index 45258062b..bf1f1d012 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -71,7 +71,7 @@
"python/frameworks/xai": "0.1.1",
"python/traceai": "0.1.0",
"typescript/packages/fi-core": "1.2.3",
- "typescript/packages/fi-semantic-conventions": "1.1.0",
+ "typescript/packages/fi-semantic-conventions": "1.2.0",
"typescript/packages/traceai_anthropic": "0.1.5",
"typescript/packages/traceai_auto": "0.1.3",
"typescript/packages/traceai_bedrock": "0.1.3",
@@ -119,7 +119,7 @@
"typescript/packages/traceai_voltagent": "0.1.0",
"typescript/packages/traceai_weaviate": "0.1.3",
"typescript/packages/traceai_xai": "0.1.1",
- "java": "1.0.3",
+ "java": "1.1.0",
"go/a2a": "0.1.1",
"go/anthropic": "0.1.0",
"go/eino": "0.1.0",
diff --git a/java/CHANGELOG.md b/java/CHANGELOG.md
index 9b5c0e9fe..aea484eff 100644
--- a/java/CHANGELOG.md
+++ b/java/CHANGELOG.md
@@ -1,5 +1,11 @@
# Changelog
+## [1.1.0](https://github.com/future-agi/traceAI/compare/java-v1.0.3...java-v1.1.0) (2026-11-10)
+
+### Features
+
+* **java-core:** add Python-aligned `GEN_AI_*` names for every GenAI attribute in `SemanticConventions`. The 16 legacy `LLM_*` names stay as deprecated compile-time aliases with identical values, so existing source and binaries keep working; `LLM_SYSTEM` maps to `GEN_AI_PROVIDER_NAME` (`gen_ai.provider.name`) ([#654](https://github.com/future-agi/traceAI/pull/654), TH-3776).
+
## [1.0.3](https://github.com/future-agi/traceAI/compare/java-v1.0.2...java-v1.0.3) (2026-11-10)
### Features
diff --git a/java/README.md b/java/README.md
index c3f5fa3de..41ecf25b6 100644
--- a/java/README.md
+++ b/java/README.md
@@ -6,7 +6,7 @@ OpenTelemetry instrumentation for Java AI applications. Trace LLM calls, embeddi
Release coordinates use **`com.futureagi`**. Artifact names are unchanged, and **Java package names remain `ai.traceai.*`**; existing imports do not change.
-The install examples track Java SDK `1.0.3`, matching [`pom.xml`](pom.xml); release-please updates them together. All SDK modules inherit that version, and the BOM aligns them.
+The install examples track Java SDK `1.1.0`, matching [`pom.xml`](pom.xml); release-please updates them together. All SDK modules inherit that version, and the BOM aligns them.
> **Unreleased API:** the [provider ownership and shutdown](#provider-ownership-and-shutdown) behavior below, including `TraceAI.init(TraceConfig, OpenTelemetry)`, is not in the immutable Central releases `1.0.0` or `1.0.1`. Until a new release containing it is published and passes the [external-consumer check](#validate-readme-coordinates), that section requires a verified source build of this checkout. Installing an older Central release or the historical JitPack commit below is not sufficient. The basic OpenAI quickstart remains available from Central.
@@ -20,7 +20,7 @@ Import the BOM once, then add the instrumentation you need:
com.futureagi
traceai-bom
- 1.0.3
+ 1.1.0
pom
import
@@ -42,7 +42,7 @@ Import the BOM once, then add the instrumentation you need:
```
-Without the BOM, specify `1.0.3` on each traceAI dependency.
+Without the BOM, specify `1.1.0` on each traceAI dependency.
For Spring Boot auto-configuration, **add** `traceai-spring-boot-starter` alongside `traceai-java-openai` and the OpenAI SDK shown above:
@@ -63,7 +63,7 @@ repositories {
}
dependencies {
- implementation platform('com.futureagi:traceai-bom:1.0.3') // x-release-please-version
+ implementation platform('com.futureagi:traceai-bom:1.1.0') // x-release-please-version
implementation 'com.futureagi:traceai-java-openai'
implementation 'com.openai:openai-java:0.8.0'
// For Spring Boot auto-configuration, add this as well (do not replace OpenAI):
@@ -190,7 +190,7 @@ Add `com.futureagi:traceai-java-core` to your application using the BOM above, o
com.futureagi
traceai-java-core
- 1.0.3
+ 1.1.0
```
diff --git a/java/compatibility/spring-ai/pom.xml b/java/compatibility/spring-ai/pom.xml
index 81032d7f3..2dea1af77 100644
--- a/java/compatibility/spring-ai/pom.xml
+++ b/java/compatibility/spring-ai/pom.xml
@@ -4,7 +4,7 @@
17UTF-8
- 1.0.3
+ 1.1.0
1.1.83.5.15
src/spring1/java
diff --git a/java/examples/azure-openai-example/pom.xml b/java/examples/azure-openai-example/pom.xml
index 824e72089..e730bc812 100644
--- a/java/examples/azure-openai-example/pom.xml
+++ b/java/examples/azure-openai-example/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
../../pom.xml
diff --git a/java/examples/azure-search-example/pom.xml b/java/examples/azure-search-example/pom.xml
index 919e1e487..2a2bc01e7 100644
--- a/java/examples/azure-search-example/pom.xml
+++ b/java/examples/azure-search-example/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
../../pom.xml
diff --git a/java/examples/elasticsearch-example/pom.xml b/java/examples/elasticsearch-example/pom.xml
index 1af0198f6..4f0c93a21 100644
--- a/java/examples/elasticsearch-example/pom.xml
+++ b/java/examples/elasticsearch-example/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
../../pom.xml
diff --git a/java/examples/langchain4j-example/pom.xml b/java/examples/langchain4j-example/pom.xml
index 286779b48..1218c725d 100644
--- a/java/examples/langchain4j-example/pom.xml
+++ b/java/examples/langchain4j-example/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
../../pom.xml
diff --git a/java/examples/openai-example/pom.xml b/java/examples/openai-example/pom.xml
index 93c8f8b0f..6c88f1a7a 100644
--- a/java/examples/openai-example/pom.xml
+++ b/java/examples/openai-example/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
../../pom.xml
diff --git a/java/examples/pgvector-example/pom.xml b/java/examples/pgvector-example/pom.xml
index eb14d5619..47778ff4c 100644
--- a/java/examples/pgvector-example/pom.xml
+++ b/java/examples/pgvector-example/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
../../pom.xml
diff --git a/java/examples/rag-example/pom.xml b/java/examples/rag-example/pom.xml
index 8f4a504ef..9672c8628 100644
--- a/java/examples/rag-example/pom.xml
+++ b/java/examples/rag-example/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
../../pom.xml
diff --git a/java/examples/semantic-kernel-example/pom.xml b/java/examples/semantic-kernel-example/pom.xml
index 64070bc2f..e33e80058 100644
--- a/java/examples/semantic-kernel-example/pom.xml
+++ b/java/examples/semantic-kernel-example/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
../../pom.xml
diff --git a/java/examples/watsonx-example/pom.xml b/java/examples/watsonx-example/pom.xml
index 15b4e9804..8e30a9a86 100644
--- a/java/examples/watsonx-example/pom.xml
+++ b/java/examples/watsonx-example/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
../../pom.xml
diff --git a/java/pom.xml b/java/pom.xml
index d87ef75ea..6560f63e5 100644
--- a/java/pom.xml
+++ b/java/pom.xml
@@ -4,7 +4,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
pom
TraceAI Java SDK
diff --git a/java/traceai-bom/pom.xml b/java/traceai-bom/pom.xml
index 64620a08d..b2aa9f20f 100644
--- a/java/traceai-bom/pom.xml
+++ b/java/traceai-bom/pom.xml
@@ -4,7 +4,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-bom
pom
diff --git a/java/traceai-java-anthropic/pom.xml b/java/traceai-java-anthropic/pom.xml
index 7763ababa..c93b0b326 100644
--- a/java/traceai-java-anthropic/pom.xml
+++ b/java/traceai-java-anthropic/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-anthropic
diff --git a/java/traceai-java-azure-openai/pom.xml b/java/traceai-java-azure-openai/pom.xml
index 894f4278b..f9889afb3 100644
--- a/java/traceai-java-azure-openai/pom.xml
+++ b/java/traceai-java-azure-openai/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-azure-openai
diff --git a/java/traceai-java-azure-search-v12/pom.xml b/java/traceai-java-azure-search-v12/pom.xml
index c11b908c3..68e844ec9 100644
--- a/java/traceai-java-azure-search-v12/pom.xml
+++ b/java/traceai-java-azure-search-v12/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-azure-search-v12
diff --git a/java/traceai-java-azure-search/pom.xml b/java/traceai-java-azure-search/pom.xml
index d5c99f53f..46c2e505c 100644
--- a/java/traceai-java-azure-search/pom.xml
+++ b/java/traceai-java-azure-search/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-azure-search
diff --git a/java/traceai-java-bedrock/pom.xml b/java/traceai-java-bedrock/pom.xml
index 9971a86cc..9d4744e8e 100644
--- a/java/traceai-java-bedrock/pom.xml
+++ b/java/traceai-java-bedrock/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-bedrock
diff --git a/java/traceai-java-chromadb/pom.xml b/java/traceai-java-chromadb/pom.xml
index c27527d77..6b57101ea 100644
--- a/java/traceai-java-chromadb/pom.xml
+++ b/java/traceai-java-chromadb/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-chromadb
diff --git a/java/traceai-java-cohere/pom.xml b/java/traceai-java-cohere/pom.xml
index cb21cd2bf..e681c890e 100644
--- a/java/traceai-java-cohere/pom.xml
+++ b/java/traceai-java-cohere/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-cohere
diff --git a/java/traceai-java-core/pom.xml b/java/traceai-java-core/pom.xml
index bb91baba6..806cfbe8a 100644
--- a/java/traceai-java-core/pom.xml
+++ b/java/traceai-java-core/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-core
diff --git a/java/traceai-java-core/src/main/java/ai/traceai/SemanticConventions.java b/java/traceai-java-core/src/main/java/ai/traceai/SemanticConventions.java
index d7796e6c8..25c058bac 100644
--- a/java/traceai-java-core/src/main/java/ai/traceai/SemanticConventions.java
+++ b/java/traceai-java-core/src/main/java/ai/traceai/SemanticConventions.java
@@ -97,33 +97,82 @@ public final class SemanticConventions {
public static final String GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
public static final String GEN_AI_SYSTEM = "gen_ai.system";
- // LLM System/Provider — both resolve to gen_ai.provider.name
- public static final String LLM_SYSTEM = "gen_ai.provider.name";
- public static final String LLM_PROVIDER = "gen_ai.provider.name";
+ public static final String GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
+
+ /** @deprecated Use {@link #GEN_AI_PROVIDER_NAME}. */
+ @Deprecated
+ public static final String LLM_SYSTEM = GEN_AI_PROVIDER_NAME;
+ /** @deprecated Use {@link #GEN_AI_PROVIDER_NAME}. */
+ @Deprecated
+ public static final String LLM_PROVIDER = GEN_AI_PROVIDER_NAME;
// ── GenAI Request ────────────────────────────────────────────────
- public static final String LLM_MODEL_NAME = "gen_ai.request.model";
- public static final String LLM_REQUEST_MODEL = "gen_ai.request.model";
- public static final String LLM_REQUEST_TEMPERATURE = "gen_ai.request.temperature";
- public static final String LLM_REQUEST_TOP_P = "gen_ai.request.top_p";
+ public static final String GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
+ public static final String GEN_AI_REQUEST_TEMPERATURE = "gen_ai.request.temperature";
+ public static final String GEN_AI_REQUEST_TOP_P = "gen_ai.request.top_p";
+
+ /** @deprecated Use {@link #GEN_AI_REQUEST_MODEL}. */
+ @Deprecated
+ public static final String LLM_MODEL_NAME = GEN_AI_REQUEST_MODEL;
+ /** @deprecated Use {@link #GEN_AI_REQUEST_MODEL}. */
+ @Deprecated
+ public static final String LLM_REQUEST_MODEL = GEN_AI_REQUEST_MODEL;
+ /** @deprecated Use {@link #GEN_AI_REQUEST_TEMPERATURE}. */
+ @Deprecated
+ public static final String LLM_REQUEST_TEMPERATURE = GEN_AI_REQUEST_TEMPERATURE;
+ /** @deprecated Use {@link #GEN_AI_REQUEST_TOP_P}. */
+ @Deprecated
+ public static final String LLM_REQUEST_TOP_P = GEN_AI_REQUEST_TOP_P;
public static final String GEN_AI_REQUEST_TOP_K = "gen_ai.request.top_k";
- public static final String LLM_REQUEST_MAX_TOKENS = "gen_ai.request.max_tokens";
+ public static final String GEN_AI_REQUEST_MAX_TOKENS = "gen_ai.request.max_tokens";
+
+ /** @deprecated Use {@link #GEN_AI_REQUEST_MAX_TOKENS}. */
+ @Deprecated
+ public static final String LLM_REQUEST_MAX_TOKENS = GEN_AI_REQUEST_MAX_TOKENS;
public static final String GEN_AI_REQUEST_FREQUENCY_PENALTY = "gen_ai.request.frequency_penalty";
public static final String GEN_AI_REQUEST_PRESENCE_PENALTY = "gen_ai.request.presence_penalty";
- public static final String LLM_REQUEST_STOP_SEQUENCES = "gen_ai.request.stop_sequences";
+ public static final String GEN_AI_REQUEST_STOP_SEQUENCES = "gen_ai.request.stop_sequences";
+
+ /** @deprecated Use {@link #GEN_AI_REQUEST_STOP_SEQUENCES}. */
+ @Deprecated
+ public static final String LLM_REQUEST_STOP_SEQUENCES = GEN_AI_REQUEST_STOP_SEQUENCES;
public static final String GEN_AI_REQUEST_SEED = "gen_ai.request.seed";
public static final String GEN_AI_REQUEST_PARAMETERS = "gen_ai.request.parameters";
// ── GenAI Response ───────────────────────────────────────────────
- public static final String LLM_RESPONSE_MODEL = "gen_ai.response.model";
- public static final String LLM_RESPONSE_ID = "gen_ai.response.id";
- public static final String LLM_RESPONSE_FINISH_REASON = "gen_ai.response.finish_reasons";
+ public static final String GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
+
+ /** @deprecated Use {@link #GEN_AI_RESPONSE_MODEL}. */
+ @Deprecated
+ public static final String LLM_RESPONSE_MODEL = GEN_AI_RESPONSE_MODEL;
+ public static final String GEN_AI_RESPONSE_ID = "gen_ai.response.id";
+
+ /** @deprecated Use {@link #GEN_AI_RESPONSE_ID}. */
+ @Deprecated
+ public static final String LLM_RESPONSE_ID = GEN_AI_RESPONSE_ID;
+ public static final String GEN_AI_RESPONSE_FINISH_REASONS = "gen_ai.response.finish_reasons";
+
+ /** @deprecated Use {@link #GEN_AI_RESPONSE_FINISH_REASONS}. */
+ @Deprecated
+ public static final String LLM_RESPONSE_FINISH_REASON = GEN_AI_RESPONSE_FINISH_REASONS;
public static final String GEN_AI_OUTPUT_TYPE = "gen_ai.output.type";
// ── GenAI Usage / Tokens ─────────────────────────────────────────
- public static final String LLM_TOKEN_COUNT_PROMPT = "gen_ai.usage.input_tokens";
- public static final String LLM_TOKEN_COUNT_COMPLETION = "gen_ai.usage.output_tokens";
- public static final String LLM_TOKEN_COUNT_TOTAL = "gen_ai.usage.total_tokens";
+ public static final String GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens";
+
+ /** @deprecated Use {@link #GEN_AI_USAGE_INPUT_TOKENS}. */
+ @Deprecated
+ public static final String LLM_TOKEN_COUNT_PROMPT = GEN_AI_USAGE_INPUT_TOKENS;
+ public static final String GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens";
+
+ /** @deprecated Use {@link #GEN_AI_USAGE_OUTPUT_TOKENS}. */
+ @Deprecated
+ public static final String LLM_TOKEN_COUNT_COMPLETION = GEN_AI_USAGE_OUTPUT_TOKENS;
+ public static final String GEN_AI_USAGE_TOTAL_TOKENS = "gen_ai.usage.total_tokens";
+
+ /** @deprecated Use {@link #GEN_AI_USAGE_TOTAL_TOKENS}. */
+ @Deprecated
+ public static final String LLM_TOKEN_COUNT_TOTAL = GEN_AI_USAGE_TOTAL_TOKENS;
public static final String GEN_AI_USAGE_CACHE_READ_TOKENS = "gen_ai.usage.cache_read_tokens";
public static final String GEN_AI_USAGE_CACHE_WRITE_TOKENS = "gen_ai.usage.cache_write_tokens";
@@ -137,8 +186,16 @@ public final class SemanticConventions {
public static final String GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE = "gen_ai.usage.input_tokens.cache_write";
// ── GenAI Messages ───────────────────────────────────────────────
- public static final String LLM_INPUT_MESSAGES = "gen_ai.input.messages";
- public static final String LLM_OUTPUT_MESSAGES = "gen_ai.output.messages";
+ public static final String GEN_AI_INPUT_MESSAGES = "gen_ai.input.messages";
+
+ /** @deprecated Use {@link #GEN_AI_INPUT_MESSAGES}. */
+ @Deprecated
+ public static final String LLM_INPUT_MESSAGES = GEN_AI_INPUT_MESSAGES;
+ public static final String GEN_AI_OUTPUT_MESSAGES = "gen_ai.output.messages";
+
+ /** @deprecated Use {@link #GEN_AI_OUTPUT_MESSAGES}. */
+ @Deprecated
+ public static final String LLM_OUTPUT_MESSAGES = GEN_AI_OUTPUT_MESSAGES;
public static final String GEN_AI_SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions";
// ── GenAI Tools ──────────────────────────────────────────────────
diff --git a/java/traceai-java-core/src/test/java/ai/traceai/SemanticConventionsTest.java b/java/traceai-java-core/src/test/java/ai/traceai/SemanticConventionsTest.java
new file mode 100644
index 000000000..eb04b8f6d
--- /dev/null
+++ b/java/traceai-java-core/src/test/java/ai/traceai/SemanticConventionsTest.java
@@ -0,0 +1,110 @@
+package ai.traceai;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+
+import java.io.IOException;
+import java.lang.reflect.Field;
+import java.lang.reflect.Modifier;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.HashMap;
+import java.util.Locale;
+import java.util.Map;
+import java.util.regex.Pattern;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class SemanticConventionsTest {
+
+ @ParameterizedTest(name = "{0} remains an alias of {1}")
+ @CsvSource({
+ "LLM_SYSTEM, GEN_AI_PROVIDER_NAME, gen_ai.provider.name",
+ "LLM_PROVIDER, GEN_AI_PROVIDER_NAME, gen_ai.provider.name",
+ "LLM_MODEL_NAME, GEN_AI_REQUEST_MODEL, gen_ai.request.model",
+ "LLM_REQUEST_MODEL, GEN_AI_REQUEST_MODEL, gen_ai.request.model",
+ "LLM_REQUEST_TEMPERATURE, GEN_AI_REQUEST_TEMPERATURE, gen_ai.request.temperature",
+ "LLM_REQUEST_TOP_P, GEN_AI_REQUEST_TOP_P, gen_ai.request.top_p",
+ "LLM_REQUEST_MAX_TOKENS, GEN_AI_REQUEST_MAX_TOKENS, gen_ai.request.max_tokens",
+ "LLM_REQUEST_STOP_SEQUENCES, GEN_AI_REQUEST_STOP_SEQUENCES, gen_ai.request.stop_sequences",
+ "LLM_RESPONSE_MODEL, GEN_AI_RESPONSE_MODEL, gen_ai.response.model",
+ "LLM_RESPONSE_ID, GEN_AI_RESPONSE_ID, gen_ai.response.id",
+ "LLM_RESPONSE_FINISH_REASON, GEN_AI_RESPONSE_FINISH_REASONS, gen_ai.response.finish_reasons",
+ "LLM_TOKEN_COUNT_PROMPT, GEN_AI_USAGE_INPUT_TOKENS, gen_ai.usage.input_tokens",
+ "LLM_TOKEN_COUNT_COMPLETION, GEN_AI_USAGE_OUTPUT_TOKENS, gen_ai.usage.output_tokens",
+ "LLM_TOKEN_COUNT_TOTAL, GEN_AI_USAGE_TOTAL_TOKENS, gen_ai.usage.total_tokens",
+ "LLM_INPUT_MESSAGES, GEN_AI_INPUT_MESSAGES, gen_ai.input.messages",
+ "LLM_OUTPUT_MESSAGES, GEN_AI_OUTPUT_MESSAGES, gen_ai.output.messages"
+ })
+ void legacyAliasesKeepTheirValuesAndAreDeprecated(String aliasName, String canonicalName,
+ String literal) throws ReflectiveOperationException {
+ Field alias = SemanticConventions.class.getField(aliasName);
+ Field canonical = SemanticConventions.class.getField(canonicalName);
+ assertTrue(Modifier.isStatic(alias.getModifiers()));
+ assertTrue(Modifier.isFinal(alias.getModifiers()));
+ assertEquals(String.class, alias.getType());
+ assertTrue(alias.isAnnotationPresent(Deprecated.class), aliasName);
+ assertFalse(canonical.isAnnotationPresent(Deprecated.class), canonicalName);
+ assertEquals(literal, alias.get(null), aliasName);
+ assertEquals(literal, canonical.get(null), canonicalName);
+ }
+
+ @Test
+ void everyExportedGenAiValueHasThePythonCanonicalName() throws Exception {
+ Map pythonNames = pythonNamesByValue();
+ assertEquals("GEN_AI_PROVIDER_NAME", pythonNames.get("gen_ai.provider.name"));
+ assertEquals("GEN_AI_RESPONSE_FINISH_REASONS", pythonNames.get("gen_ai.response.finish_reasons"));
+
+ for (Field field : SemanticConventions.class.getFields()) {
+ if (field.getType() != String.class || !Modifier.isStatic(field.getModifiers())) {
+ continue;
+ }
+ String value = (String) field.get(null);
+ if (!value.startsWith("gen_ai.")) {
+ continue;
+ }
+ // Java-only attributes use the same dotted-path-to-upper-snake-case rule.
+ String name = pythonNames.getOrDefault(value, value.toUpperCase(Locale.ROOT).replace('.', '_'));
+ Field canonical = SemanticConventions.class.getField(name);
+ assertTrue(Modifier.isStatic(canonical.getModifiers()), name);
+ assertTrue(Modifier.isFinal(canonical.getModifiers()), name);
+ assertEquals(String.class, canonical.getType(), name);
+ assertEquals(value, canonical.get(null), field.getName());
+ if (!field.getName().equals(name)) {
+ assertTrue(field.isAnnotationPresent(Deprecated.class), field.getName());
+ }
+ }
+
+ // Check the reverse direction too: an existing canonical name must not drift
+ // to a Java-only value and thereby evade the lookup above. Python-only values
+ // are not added to Java by this naming-only change.
+ for (Map.Entry entry : pythonNames.entrySet()) {
+ try {
+ Field field = SemanticConventions.class.getField(entry.getValue());
+ assertEquals(entry.getKey(), field.get(null), entry.getValue());
+ } catch (NoSuchFieldException ignored) {
+ // This SDK does not yet export this Python attribute value.
+ }
+ }
+ }
+
+ private static Map pythonNamesByValue() throws IOException {
+ // Locate the checked-out reference instead of maintaining a stale fixture.
+ // Supports both `cd java && mvn verify` and `mvn -f java/pom.xml verify`.
+ Path root = Path.of("").toAbsolutePath();
+ Path relative = Path.of("python", "fi_instrumentation", "fi_types.py");
+ while (root != null && !Files.isRegularFile(root.resolve(relative))) {
+ root = root.getParent();
+ }
+ assertNotNull(root, "Run this test from the traceAI checkout containing python/fi_instrumentation/fi_types.py");
+ Pattern assignment = Pattern.compile("^ (GEN_AI_\\w+) = \"(gen_ai\\.[^\"]+)\"", Pattern.MULTILINE);
+ var matcher = assignment.matcher(Files.readString(root.resolve(relative)));
+ Map names = new HashMap<>();
+ while (matcher.find()) {
+ assertNull(names.put(matcher.group(2), matcher.group(1)), "Duplicate Python gen_ai value");
+ }
+ assertFalse(names.isEmpty(), "Python reference must contain GEN_AI_* constants");
+ return names;
+ }
+}
diff --git a/java/traceai-java-elasticsearch/pom.xml b/java/traceai-java-elasticsearch/pom.xml
index 0170e4974..c960b773c 100644
--- a/java/traceai-java-elasticsearch/pom.xml
+++ b/java/traceai-java-elasticsearch/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-elasticsearch
diff --git a/java/traceai-java-google-genai/pom.xml b/java/traceai-java-google-genai/pom.xml
index e58e72bc6..ab5325bca 100644
--- a/java/traceai-java-google-genai/pom.xml
+++ b/java/traceai-java-google-genai/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-google-genai
diff --git a/java/traceai-java-milvus/pom.xml b/java/traceai-java-milvus/pom.xml
index acd28fff9..85a45dc0b 100644
--- a/java/traceai-java-milvus/pom.xml
+++ b/java/traceai-java-milvus/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-milvus
diff --git a/java/traceai-java-mongodb/pom.xml b/java/traceai-java-mongodb/pom.xml
index 5eaf97346..6e2138ab1 100644
--- a/java/traceai-java-mongodb/pom.xml
+++ b/java/traceai-java-mongodb/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-mongodb
diff --git a/java/traceai-java-ollama/pom.xml b/java/traceai-java-ollama/pom.xml
index 46d05c9b8..242706676 100644
--- a/java/traceai-java-ollama/pom.xml
+++ b/java/traceai-java-ollama/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-ollama
diff --git a/java/traceai-java-openai/pom.xml b/java/traceai-java-openai/pom.xml
index e327a3063..c13688711 100644
--- a/java/traceai-java-openai/pom.xml
+++ b/java/traceai-java-openai/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-openai
diff --git a/java/traceai-java-pgvector/pom.xml b/java/traceai-java-pgvector/pom.xml
index e544dc982..11feae4dd 100644
--- a/java/traceai-java-pgvector/pom.xml
+++ b/java/traceai-java-pgvector/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-pgvector
diff --git a/java/traceai-java-pinecone/pom.xml b/java/traceai-java-pinecone/pom.xml
index 59f02b8e1..61b875862 100644
--- a/java/traceai-java-pinecone/pom.xml
+++ b/java/traceai-java-pinecone/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-pinecone
diff --git a/java/traceai-java-qdrant/pom.xml b/java/traceai-java-qdrant/pom.xml
index 3785e2b75..23195a51a 100644
--- a/java/traceai-java-qdrant/pom.xml
+++ b/java/traceai-java-qdrant/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-qdrant
diff --git a/java/traceai-java-quarkus-langchain4j/pom.xml b/java/traceai-java-quarkus-langchain4j/pom.xml
index 01c1a8c2c..41e55ac1f 100644
--- a/java/traceai-java-quarkus-langchain4j/pom.xml
+++ b/java/traceai-java-quarkus-langchain4j/pom.xml
@@ -4,7 +4,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-quarkus-langchain4j
TraceAI Quarkus LangChain4j
diff --git a/java/traceai-java-redis/pom.xml b/java/traceai-java-redis/pom.xml
index 8d59e6641..479262d13 100644
--- a/java/traceai-java-redis/pom.xml
+++ b/java/traceai-java-redis/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-redis
diff --git a/java/traceai-java-semantic-kernel/pom.xml b/java/traceai-java-semantic-kernel/pom.xml
index 4b10d14f7..3095a32d7 100644
--- a/java/traceai-java-semantic-kernel/pom.xml
+++ b/java/traceai-java-semantic-kernel/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-semantic-kernel
diff --git a/java/traceai-java-vertexai/pom.xml b/java/traceai-java-vertexai/pom.xml
index f1cd6d2fe..10baa16ad 100644
--- a/java/traceai-java-vertexai/pom.xml
+++ b/java/traceai-java-vertexai/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-vertexai
diff --git a/java/traceai-java-watsonx/pom.xml b/java/traceai-java-watsonx/pom.xml
index 58ebe3bde..cba3e76e5 100644
--- a/java/traceai-java-watsonx/pom.xml
+++ b/java/traceai-java-watsonx/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-watsonx
diff --git a/java/traceai-java-weaviate/README.md b/java/traceai-java-weaviate/README.md
index 0bc5171d6..c7ce6725e 100644
--- a/java/traceai-java-weaviate/README.md
+++ b/java/traceai-java-weaviate/README.md
@@ -17,7 +17,7 @@ After building and installing this checkout locally, add these dependencies. For
com.futureagi
traceai-java-weaviate
- 1.0.3
+ 1.1.0
io.weaviate
diff --git a/java/traceai-java-weaviate/pom.xml b/java/traceai-java-weaviate/pom.xml
index 697a7fa74..4d9d1ddfc 100644
--- a/java/traceai-java-weaviate/pom.xml
+++ b/java/traceai-java-weaviate/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-java-weaviate
diff --git a/java/traceai-langchain4j/pom.xml b/java/traceai-langchain4j/pom.xml
index 04c2b7b87..d18967451 100644
--- a/java/traceai-langchain4j/pom.xml
+++ b/java/traceai-langchain4j/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-langchain4j
diff --git a/java/traceai-spring-ai/pom.xml b/java/traceai-spring-ai/pom.xml
index 2b7b4f92f..eec33dd54 100644
--- a/java/traceai-spring-ai/pom.xml
+++ b/java/traceai-spring-ai/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-spring-ai
diff --git a/java/traceai-spring-boot-starter/pom.xml b/java/traceai-spring-boot-starter/pom.xml
index c0b2cac84..a984ef3cf 100644
--- a/java/traceai-spring-boot-starter/pom.xml
+++ b/java/traceai-spring-boot-starter/pom.xml
@@ -5,7 +5,7 @@
com.futureagi
traceai-java-parent
- 1.0.3
+ 1.1.0
traceai-spring-boot-starter
diff --git a/typescript/packages/fi-semantic-conventions/CHANGELOG.md b/typescript/packages/fi-semantic-conventions/CHANGELOG.md
index 051ad843d..ea8ee718b 100644
--- a/typescript/packages/fi-semantic-conventions/CHANGELOG.md
+++ b/typescript/packages/fi-semantic-conventions/CHANGELOG.md
@@ -1,3 +1,10 @@
+## [1.2.0] - 2026-11-10
+### Added
+- Align GenAI constant names with Python's `SpanAttributes`: expose `GEN_AI_*` names as named exports and on `SemanticConventions`.
+- Preserve existing `LLM_*` exports as deprecated aliases without changing attribute keys or literal types.
+- Document canonical names and replace legacy `llm.*` keys in the usage example.
+- Check every exported `gen_ai.*` value against Python's canonical names in CI, including changes to the Python reference.
+
## [0.1.8] - 2025-06-10
### Feature
- Dependencies Updated
diff --git a/typescript/packages/fi-semantic-conventions/README.md b/typescript/packages/fi-semantic-conventions/README.md
index e9318f4eb..e2daeb604 100644
--- a/typescript/packages/fi-semantic-conventions/README.md
+++ b/typescript/packages/fi-semantic-conventions/README.md
@@ -67,35 +67,67 @@ import { SemanticAttributePrefixes } from '@traceai/fi-semantic-conventions';
| `audio` | Audio attributes |
| `prompt` | Prompt attributes |
-## LLM Attributes
+## GenAI Attributes
+
+Use the `GEN_AI_*` constants for GenAI attributes. Their names and values match
+Python's `SpanAttributes`, and they are available as both named exports and
+properties of `SemanticConventions`.
```typescript
-import { LLMAttributePostfixes } from '@traceai/fi-semantic-conventions';
+import {
+ GEN_AI_INPUT_MESSAGES,
+ SemanticConventions,
+} from '@traceai/fi-semantic-conventions';
+
+// Both are "gen_ai.input.messages".
+GEN_AI_INPUT_MESSAGES;
+SemanticConventions.GEN_AI_INPUT_MESSAGES;
```
-| Postfix | Full Attribute | Description |
-|---------|----------------|-------------|
-| `provider` | `llm.provider` | LLM provider (aws, azure, google) |
-| `system` | `llm.system` | LLM system (openai, anthropic) |
-| `model_name` | `llm.model_name` | Model identifier |
-| `token_count` | `llm.token_count.*` | Token usage |
-| `input_messages` | `llm.input_messages` | Input message array |
-| `output_messages` | `llm.output_messages` | Output message array |
-| `invocation_parameters` | `llm.invocation_parameters` | Model parameters |
-| `prompts` | `llm.prompts` | Prompt strings |
-| `prompt_template` | `llm.prompt_template.*` | Template tracking |
-| `function_call` | `llm.function_call` | Function call details |
-| `tools` | `llm.tools` | Available tools |
-
-### Token Count Attributes
+### Migrate existing imports
-| Attribute | Description |
-|-----------|-------------|
-| `llm.token_count.prompt` | Input/prompt tokens |
-| `llm.token_count.completion` | Output/completion tokens |
-| `llm.token_count.total` | Total tokens |
-| `llm.token_count.cache_read` | Cached tokens read |
-| `llm.token_count.cache_creation` | Cached tokens created |
+The 17 `LLM_*` constants listed below remain available as deprecated aliases with
+the same literal types and wire values. Existing instrumentation does not need to
+change. To adopt the canonical API, replace an import or property name using the
+table below; do not rewrite the emitted attribute keys or stored traces.
+
+```typescript
+import { GEN_AI_INPUT_MESSAGES } from '@traceai/fi-semantic-conventions';
+
+// Replaces LLM_INPUT_MESSAGES without changing the attribute key or its type.
+const inputKey: 'gen_ai.input.messages' = GEN_AI_INPUT_MESSAGES;
+```
+
+In particular, both `LLM_PROVIDER` and `LLM_SYSTEM` alias `GEN_AI_PROVIDER_NAME`;
+`LLM_SYSTEM` is not an alias for Python's distinct `GEN_AI_SYSTEM` (`gen_ai.system`).
+
+| Canonical constant | Deprecated alias | Attribute key |
+|--------------------|------------------|---------------|
+| `GEN_AI_INPUT_MESSAGES` | `LLM_INPUT_MESSAGES` | `gen_ai.input.messages` |
+| `GEN_AI_PROMPTS` | `LLM_PROMPTS` | `gen_ai.prompts` |
+| `GEN_AI_REQUEST_PARAMETERS` | `LLM_INVOCATION_PARAMETERS` | `gen_ai.request.parameters` |
+| `GEN_AI_OUTPUT_MESSAGES` | `LLM_OUTPUT_MESSAGES` | `gen_ai.output.messages` |
+| `GEN_AI_REQUEST_MODEL` | `LLM_MODEL_NAME` | `gen_ai.request.model` |
+| `GEN_AI_PROVIDER_NAME` | `LLM_PROVIDER` | `gen_ai.provider.name` |
+| `GEN_AI_PROVIDER_NAME` | `LLM_SYSTEM` | `gen_ai.provider.name` |
+| `GEN_AI_USAGE_OUTPUT_TOKENS` | `LLM_TOKEN_COUNT_COMPLETION` | `gen_ai.usage.output_tokens` |
+| `GEN_AI_USAGE_OUTPUT_TOKENS_REASONING` | `LLM_TOKEN_COUNT_COMPLETION_DETAILS_REASONING` | `gen_ai.usage.output_tokens.reasoning` |
+| `GEN_AI_USAGE_OUTPUT_TOKENS_AUDIO` | `LLM_TOKEN_COUNT_COMPLETION_DETAILS_AUDIO` | `gen_ai.usage.output_tokens.audio` |
+| `GEN_AI_USAGE_INPUT_TOKENS` | `LLM_TOKEN_COUNT_PROMPT` | `gen_ai.usage.input_tokens` |
+| `GEN_AI_USAGE_CACHE_WRITE_TOKENS` | `LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE` | `gen_ai.usage.cache_write_tokens` |
+| `GEN_AI_USAGE_CACHE_READ_TOKENS` | `LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ` | `gen_ai.usage.cache_read_tokens` |
+| `GEN_AI_USAGE_INPUT_TOKENS_AUDIO` | `LLM_TOKEN_COUNT_PROMPT_DETAILS_AUDIO` | `gen_ai.usage.input_tokens.audio` |
+| `GEN_AI_USAGE_TOTAL_TOKENS` | `LLM_TOKEN_COUNT_TOTAL` | `gen_ai.usage.total_tokens` |
+| `GEN_AI_TOOL_CALL` | `LLM_FUNCTION_CALL` | `gen_ai.tool.call` |
+| `GEN_AI_TOOL_DEFINITIONS` | `LLM_TOOLS` | `gen_ai.tool.definitions` |
+
+These names include traceAI extensions such as prompts, request parameters,
+aggregated tool calls, and detailed token usage; they are not all upstream OTEL
+standard attributes.
+
+`SemanticAttributePrefixes.llm` and `LLMAttributePostfixes` are retained for
+compatibility with legacy `llm.*` keys. Do not compose new GenAI keys from them;
+use the complete constants above. Prompt template attributes below are unchanged.
### Prompt Template Attributes
@@ -162,10 +194,7 @@ import { ToolAttributePostfixes } from '@traceai/fi-semantic-conventions';
```typescript
import { trace } from '@opentelemetry/api';
-import {
- SemanticAttributePrefixes,
- LLMAttributePostfixes,
-} from '@traceai/fi-semantic-conventions';
+import { SemanticConventions } from '@traceai/fi-semantic-conventions';
const tracer = trace.getTracer('my-app');
@@ -174,12 +203,12 @@ const span = tracer.startSpan('llm.chat');
// Set attributes using conventions
span.setAttributes({
- [`${SemanticAttributePrefixes.llm}.${LLMAttributePostfixes.system}`]: 'openai',
- [`${SemanticAttributePrefixes.llm}.${LLMAttributePostfixes.model_name}`]: 'gpt-4',
- [`${SemanticAttributePrefixes.llm}.${LLMAttributePostfixes.token_count}.prompt`]: 100,
- [`${SemanticAttributePrefixes.llm}.${LLMAttributePostfixes.token_count}.completion`]: 50,
- [`${SemanticAttributePrefixes.input}.value`]: 'User input text',
- [`${SemanticAttributePrefixes.output}.value`]: 'Model response',
+ [SemanticConventions.GEN_AI_PROVIDER_NAME]: 'openai',
+ [SemanticConventions.GEN_AI_REQUEST_MODEL]: 'gpt-4',
+ [SemanticConventions.GEN_AI_USAGE_INPUT_TOKENS]: 100,
+ [SemanticConventions.GEN_AI_USAGE_OUTPUT_TOKENS]: 50,
+ [SemanticConventions.INPUT_VALUE]: 'User input text',
+ [SemanticConventions.OUTPUT_VALUE]: 'Model response',
});
span.end();
diff --git a/typescript/packages/fi-semantic-conventions/package.json b/typescript/packages/fi-semantic-conventions/package.json
index e4039385d..63c0dcfc8 100644
--- a/typescript/packages/fi-semantic-conventions/package.json
+++ b/typescript/packages/fi-semantic-conventions/package.json
@@ -1,6 +1,6 @@
{
"name": "@traceai/fi-semantic-conventions",
- "version": "1.1.0",
+ "version": "1.2.0",
"description": "Semantic conventions and span attributes for traceAI OpenTelemetry instrumentation.",
"main": "./dist/src/index.js",
"module": "./dist/esm/index.js",
diff --git a/typescript/packages/fi-semantic-conventions/src/__tests__/gen-ai-naming.test.ts b/typescript/packages/fi-semantic-conventions/src/__tests__/gen-ai-naming.test.ts
new file mode 100644
index 000000000..8d0ba3321
--- /dev/null
+++ b/typescript/packages/fi-semantic-conventions/src/__tests__/gen-ai-naming.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it } from '@jest/globals';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import * as conventions from '../index';
+
+// These canonical names and wire values match Python's SpanAttributes.
+const aliases: Array<[string, string, string]> = [
+ ["LLM_INPUT_MESSAGES", "GEN_AI_INPUT_MESSAGES", "gen_ai.input.messages"],
+ ["LLM_PROMPTS", "GEN_AI_PROMPTS", "gen_ai.prompts"],
+ ["LLM_INVOCATION_PARAMETERS", "GEN_AI_REQUEST_PARAMETERS", "gen_ai.request.parameters"],
+ ["LLM_OUTPUT_MESSAGES", "GEN_AI_OUTPUT_MESSAGES", "gen_ai.output.messages"],
+ ["LLM_MODEL_NAME", "GEN_AI_REQUEST_MODEL", "gen_ai.request.model"],
+ ["LLM_PROVIDER", "GEN_AI_PROVIDER_NAME", "gen_ai.provider.name"],
+ ["LLM_SYSTEM", "GEN_AI_PROVIDER_NAME", "gen_ai.provider.name"],
+ ["LLM_TOKEN_COUNT_COMPLETION", "GEN_AI_USAGE_OUTPUT_TOKENS", "gen_ai.usage.output_tokens"],
+ ["LLM_TOKEN_COUNT_COMPLETION_DETAILS_REASONING", "GEN_AI_USAGE_OUTPUT_TOKENS_REASONING", "gen_ai.usage.output_tokens.reasoning"],
+ ["LLM_TOKEN_COUNT_COMPLETION_DETAILS_AUDIO", "GEN_AI_USAGE_OUTPUT_TOKENS_AUDIO", "gen_ai.usage.output_tokens.audio"],
+ ["LLM_TOKEN_COUNT_PROMPT", "GEN_AI_USAGE_INPUT_TOKENS", "gen_ai.usage.input_tokens"],
+ ["LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE", "GEN_AI_USAGE_CACHE_WRITE_TOKENS", "gen_ai.usage.cache_write_tokens"],
+ ["LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ", "GEN_AI_USAGE_CACHE_READ_TOKENS", "gen_ai.usage.cache_read_tokens"],
+ ["LLM_TOKEN_COUNT_PROMPT_DETAILS_AUDIO", "GEN_AI_USAGE_INPUT_TOKENS_AUDIO", "gen_ai.usage.input_tokens.audio"],
+ ["LLM_TOKEN_COUNT_TOTAL", "GEN_AI_USAGE_TOTAL_TOKENS", "gen_ai.usage.total_tokens"],
+ ["LLM_FUNCTION_CALL", "GEN_AI_TOOL_CALL", "gen_ai.tool.call"],
+ ["LLM_TOOLS", "GEN_AI_TOOL_DEFINITIONS", "gen_ai.tool.definitions"],
+];
+
+// Read the reference at test time so Python renames cannot silently drift.
+const pythonSource = readFileSync(
+ resolve(__dirname, '../../../../../python/fi_instrumentation/fi_types.py'),
+ 'utf8',
+);
+const pythonNames = new Map(
+ [...pythonSource.matchAll(/^\s+(GEN_AI_[A-Z0-9_]+)\s*=\s*["'](gen_ai\.[^"']+)["']/gm)]
+ .map(([, name, value]) => [value, name]),
+);
+const publicSurfaces: Array<[string, Record]> = [
+ ['named exports', conventions],
+ ['SemanticConventions', conventions.SemanticConventions],
+];
+
+describe('GenAI constant naming', () => {
+ it('loads Python canonical attributes rather than passing with an empty reference', () => {
+ expect(pythonNames.size).toBeGreaterThan(0);
+ expect(pythonNames.get('gen_ai.input.messages')).toBe('GEN_AI_INPUT_MESSAGES');
+ });
+
+ it.each(publicSurfaces)('matches Python for every GenAI value on %s', (_label, surface) => {
+ const attributes = Object.entries(surface).filter(
+ (entry): entry is [string, string] =>
+ typeof entry[1] === 'string' && entry[1].startsWith('gen_ai.'),
+ );
+ expect(attributes.length).toBeGreaterThan(0);
+ for (const [name, value] of attributes) {
+ // All current TS values have a Python counterpart. A new TS-only key must
+ // get an explicitly documented canonical name, not a silent fallback.
+ const canonical = pythonNames.get(value);
+ expect({ name, value, canonical }).toEqual({ name, value, canonical: expect.any(String) });
+ expect(surface[canonical!]).toBe(value);
+ if (name.startsWith('GEN_AI_')) {
+ expect(name).toBe(canonical);
+ } else {
+ expect(aliases).toContainEqual([name, canonical, value]);
+ }
+ }
+ });
+ it.each(aliases)('%s has the canonical %s export for %s', (legacy, canonical, value) => {
+ // Look up exports at runtime so missing names fail assertions, not compilation.
+ const exports: Record = conventions;
+ const attributes: Record = conventions.SemanticConventions;
+ expect(exports[canonical]).toBe(value);
+ expect(attributes[canonical]).toBe(value);
+ expect(exports[legacy]).toBe(value);
+ expect(attributes[legacy]).toBe(value);
+ });
+});
diff --git a/typescript/packages/fi-semantic-conventions/src/__tests__/gen-ai-types.test.ts b/typescript/packages/fi-semantic-conventions/src/__tests__/gen-ai-types.test.ts
new file mode 100644
index 000000000..4feaf9a1b
--- /dev/null
+++ b/typescript/packages/fi-semantic-conventions/src/__tests__/gen-ai-types.test.ts
@@ -0,0 +1,46 @@
+import { expect, it } from '@jest/globals';
+import * as conventions from '../index';
+
+// Assignment to these literal types must fail if an export widens to string.
+// Keep this separate from runtime coverage, which also runs on pre-fix code.
+type GenAIAttributeTypes = {
+ LLM_INPUT_MESSAGES: "gen_ai.input.messages";
+ GEN_AI_INPUT_MESSAGES: "gen_ai.input.messages";
+ LLM_PROMPTS: "gen_ai.prompts";
+ GEN_AI_PROMPTS: "gen_ai.prompts";
+ LLM_INVOCATION_PARAMETERS: "gen_ai.request.parameters";
+ GEN_AI_REQUEST_PARAMETERS: "gen_ai.request.parameters";
+ LLM_OUTPUT_MESSAGES: "gen_ai.output.messages";
+ GEN_AI_OUTPUT_MESSAGES: "gen_ai.output.messages";
+ LLM_MODEL_NAME: "gen_ai.request.model";
+ GEN_AI_REQUEST_MODEL: "gen_ai.request.model";
+ LLM_PROVIDER: "gen_ai.provider.name";
+ GEN_AI_PROVIDER_NAME: "gen_ai.provider.name";
+ LLM_SYSTEM: "gen_ai.provider.name";
+ LLM_TOKEN_COUNT_COMPLETION: "gen_ai.usage.output_tokens";
+ GEN_AI_USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+ LLM_TOKEN_COUNT_COMPLETION_DETAILS_REASONING: "gen_ai.usage.output_tokens.reasoning";
+ GEN_AI_USAGE_OUTPUT_TOKENS_REASONING: "gen_ai.usage.output_tokens.reasoning";
+ LLM_TOKEN_COUNT_COMPLETION_DETAILS_AUDIO: "gen_ai.usage.output_tokens.audio";
+ GEN_AI_USAGE_OUTPUT_TOKENS_AUDIO: "gen_ai.usage.output_tokens.audio";
+ LLM_TOKEN_COUNT_PROMPT: "gen_ai.usage.input_tokens";
+ GEN_AI_USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens";
+ LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE: "gen_ai.usage.cache_write_tokens";
+ GEN_AI_USAGE_CACHE_WRITE_TOKENS: "gen_ai.usage.cache_write_tokens";
+ LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ: "gen_ai.usage.cache_read_tokens";
+ GEN_AI_USAGE_CACHE_READ_TOKENS: "gen_ai.usage.cache_read_tokens";
+ LLM_TOKEN_COUNT_PROMPT_DETAILS_AUDIO: "gen_ai.usage.input_tokens.audio";
+ GEN_AI_USAGE_INPUT_TOKENS_AUDIO: "gen_ai.usage.input_tokens.audio";
+ LLM_TOKEN_COUNT_TOTAL: "gen_ai.usage.total_tokens";
+ GEN_AI_USAGE_TOTAL_TOKENS: "gen_ai.usage.total_tokens";
+ LLM_FUNCTION_CALL: "gen_ai.tool.call";
+ GEN_AI_TOOL_CALL: "gen_ai.tool.call";
+ LLM_TOOLS: "gen_ai.tool.definitions";
+ GEN_AI_TOOL_DEFINITIONS: "gen_ai.tool.definitions";
+};
+
+it('preserves canonical and legacy literal types on both public surfaces', () => {
+ const named: GenAIAttributeTypes = conventions;
+ const attributes: GenAIAttributeTypes = conventions.SemanticConventions;
+ expect(named.GEN_AI_INPUT_MESSAGES).toBe(attributes.LLM_INPUT_MESSAGES);
+});
diff --git a/typescript/packages/fi-semantic-conventions/src/trace/SemanticConventions.ts b/typescript/packages/fi-semantic-conventions/src/trace/SemanticConventions.ts
index 98b078ab3..a6033a372 100644
--- a/typescript/packages/fi-semantic-conventions/src/trace/SemanticConventions.ts
+++ b/typescript/packages/fi-semantic-conventions/src/trace/SemanticConventions.ts
@@ -146,62 +146,105 @@ export const SemanticAttributePrefixes = {
* The messages sent to the LLM for completions (JSON blob)
* OTEL GenAI semantic convention: gen_ai.input.messages
*/
- export const LLM_INPUT_MESSAGES = "gen_ai.input.messages" as const;
+ export const GEN_AI_INPUT_MESSAGES = "gen_ai.input.messages" as const;
+
+ /** @deprecated Use GEN_AI_INPUT_MESSAGES instead. */
+ export const LLM_INPUT_MESSAGES = GEN_AI_INPUT_MESSAGES;
/**
* The prompts sent to the LLM for completions
*/
- export const LLM_PROMPTS = "gen_ai.prompts" as const;
+ export const GEN_AI_PROMPTS = "gen_ai.prompts" as const;
+
+ /** @deprecated Use GEN_AI_PROMPTS instead. */
+ export const LLM_PROMPTS = GEN_AI_PROMPTS;
/**
* The JSON representation of the parameters passed to the LLM
*/
- export const LLM_INVOCATION_PARAMETERS = "gen_ai.request.parameters" as const;
+ export const GEN_AI_REQUEST_PARAMETERS = "gen_ai.request.parameters" as const;
+
+ /** @deprecated Use GEN_AI_REQUEST_PARAMETERS instead. */
+ export const LLM_INVOCATION_PARAMETERS = GEN_AI_REQUEST_PARAMETERS;
/**
* The messages received from the LLM for completions (JSON blob)
* OTEL GenAI semantic convention: gen_ai.output.messages
*/
- export const LLM_OUTPUT_MESSAGES = "gen_ai.output.messages" as const;
+ export const GEN_AI_OUTPUT_MESSAGES = "gen_ai.output.messages" as const;
+
+ /** @deprecated Use GEN_AI_OUTPUT_MESSAGES instead. */
+ export const LLM_OUTPUT_MESSAGES = GEN_AI_OUTPUT_MESSAGES;
/**
* The name of the LLM model (request)
*/
- export const LLM_MODEL_NAME = "gen_ai.request.model" as const;
+ export const GEN_AI_REQUEST_MODEL = "gen_ai.request.model" as const;
+
+ /** @deprecated Use GEN_AI_REQUEST_MODEL instead. */
+ export const LLM_MODEL_NAME = GEN_AI_REQUEST_MODEL;
/**
* The provider of the inferences. E.g. the cloud provider
*/
- export const LLM_PROVIDER = "gen_ai.provider.name" as const;
+ export const GEN_AI_PROVIDER_NAME = "gen_ai.provider.name" as const;
+
+ /** @deprecated Use GEN_AI_PROVIDER_NAME instead. */
+ export const LLM_PROVIDER = GEN_AI_PROVIDER_NAME;
/**
- * The AI product as identified by the client or server
+ * The AI product as identified by the client or server.
+ * @deprecated Use GEN_AI_PROVIDER_NAME instead.
*/
- export const LLM_SYSTEM = "gen_ai.provider.name" as const;
+ export const LLM_SYSTEM = GEN_AI_PROVIDER_NAME;
/** Token count for the completion by the llm */
- export const LLM_TOKEN_COUNT_COMPLETION = "gen_ai.usage.output_tokens" as const;
+ export const GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens" as const;
+
+ /** @deprecated Use GEN_AI_USAGE_OUTPUT_TOKENS instead. */
+ export const LLM_TOKEN_COUNT_COMPLETION = GEN_AI_USAGE_OUTPUT_TOKENS;
/** Token count for the reasoning steps in the completion */
- export const LLM_TOKEN_COUNT_COMPLETION_DETAILS_REASONING = "gen_ai.usage.output_tokens.reasoning" as const;
+ export const GEN_AI_USAGE_OUTPUT_TOKENS_REASONING = "gen_ai.usage.output_tokens.reasoning" as const;
+
+ /** @deprecated Use GEN_AI_USAGE_OUTPUT_TOKENS_REASONING instead. */
+ export const LLM_TOKEN_COUNT_COMPLETION_DETAILS_REASONING = GEN_AI_USAGE_OUTPUT_TOKENS_REASONING;
/** Token count for audio output generated by the model */
- export const LLM_TOKEN_COUNT_COMPLETION_DETAILS_AUDIO = "gen_ai.usage.output_tokens.audio" as const;
+ export const GEN_AI_USAGE_OUTPUT_TOKENS_AUDIO = "gen_ai.usage.output_tokens.audio" as const;
+
+ /** @deprecated Use GEN_AI_USAGE_OUTPUT_TOKENS_AUDIO instead. */
+ export const LLM_TOKEN_COUNT_COMPLETION_DETAILS_AUDIO = GEN_AI_USAGE_OUTPUT_TOKENS_AUDIO;
/** Token count for the prompt to the llm */
- export const LLM_TOKEN_COUNT_PROMPT = "gen_ai.usage.input_tokens" as const;
+ export const GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens" as const;
+
+ /** @deprecated Use GEN_AI_USAGE_INPUT_TOKENS instead. */
+ export const LLM_TOKEN_COUNT_PROMPT = GEN_AI_USAGE_INPUT_TOKENS;
/** Token count for the tokens written to the cache */
- export const LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE = "gen_ai.usage.cache_write_tokens" as const;
+ export const GEN_AI_USAGE_CACHE_WRITE_TOKENS = "gen_ai.usage.cache_write_tokens" as const;
+
+ /** @deprecated Use GEN_AI_USAGE_CACHE_WRITE_TOKENS instead. */
+ export const LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE = GEN_AI_USAGE_CACHE_WRITE_TOKENS;
/** Token count for the tokens retrieved from the cache */
- export const LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ = "gen_ai.usage.cache_read_tokens" as const;
+ export const GEN_AI_USAGE_CACHE_READ_TOKENS = "gen_ai.usage.cache_read_tokens" as const;
+
+ /** @deprecated Use GEN_AI_USAGE_CACHE_READ_TOKENS instead. */
+ export const LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ = GEN_AI_USAGE_CACHE_READ_TOKENS;
/** Token count for audio input presented in the prompt */
- export const LLM_TOKEN_COUNT_PROMPT_DETAILS_AUDIO = "gen_ai.usage.input_tokens.audio" as const;
+ export const GEN_AI_USAGE_INPUT_TOKENS_AUDIO = "gen_ai.usage.input_tokens.audio" as const;
+
+ /** @deprecated Use GEN_AI_USAGE_INPUT_TOKENS_AUDIO instead. */
+ export const LLM_TOKEN_COUNT_PROMPT_DETAILS_AUDIO = GEN_AI_USAGE_INPUT_TOKENS_AUDIO;
/** Token count for the entire transaction with the llm */
- export const LLM_TOKEN_COUNT_TOTAL = "gen_ai.usage.total_tokens" as const;
+ export const GEN_AI_USAGE_TOTAL_TOKENS = "gen_ai.usage.total_tokens" as const;
+
+ /** @deprecated Use GEN_AI_USAGE_TOTAL_TOKENS instead. */
+ export const LLM_TOKEN_COUNT_TOTAL = GEN_AI_USAGE_TOTAL_TOKENS;
/**
* The role that the LLM assumes the message is from
* during the LLM invocation
@@ -350,12 +393,18 @@ export const SemanticAttributePrefixes = {
/**
* The JSON representation of a function call of an LLM
*/
- export const LLM_FUNCTION_CALL = "gen_ai.tool.call" as const;
+ export const GEN_AI_TOOL_CALL = "gen_ai.tool.call" as const;
+
+ /** @deprecated Use GEN_AI_TOOL_CALL instead. */
+ export const LLM_FUNCTION_CALL = GEN_AI_TOOL_CALL;
/**
* List of tools that are advertised to the LLM to be able to call
*/
- export const LLM_TOOLS = "gen_ai.tool.definitions" as const;
+ export const GEN_AI_TOOL_DEFINITIONS = "gen_ai.tool.definitions" as const;
+
+ /** @deprecated Use GEN_AI_TOOL_DEFINITIONS instead. */
+ export const LLM_TOOLS = GEN_AI_TOOL_DEFINITIONS;
/**
* The name of a tool
@@ -633,21 +682,53 @@ export const SemanticAttributePrefixes = {
INPUT_MIME_TYPE,
OUTPUT_VALUE,
OUTPUT_MIME_TYPE,
+ GEN_AI_INPUT_MESSAGES,
+ GEN_AI_PROMPTS,
+ GEN_AI_REQUEST_PARAMETERS,
+ GEN_AI_OUTPUT_MESSAGES,
+ GEN_AI_REQUEST_MODEL,
+ GEN_AI_PROVIDER_NAME,
+ GEN_AI_USAGE_OUTPUT_TOKENS,
+ GEN_AI_USAGE_OUTPUT_TOKENS_REASONING,
+ GEN_AI_USAGE_OUTPUT_TOKENS_AUDIO,
+ GEN_AI_USAGE_INPUT_TOKENS,
+ GEN_AI_USAGE_CACHE_WRITE_TOKENS,
+ GEN_AI_USAGE_CACHE_READ_TOKENS,
+ GEN_AI_USAGE_INPUT_TOKENS_AUDIO,
+ GEN_AI_USAGE_TOTAL_TOKENS,
+ GEN_AI_TOOL_CALL,
+ GEN_AI_TOOL_DEFINITIONS,
+ /** @deprecated Use GEN_AI_INPUT_MESSAGES instead. */
LLM_INPUT_MESSAGES,
+ /** @deprecated Use GEN_AI_OUTPUT_MESSAGES instead. */
LLM_OUTPUT_MESSAGES,
+ /** @deprecated Use GEN_AI_REQUEST_MODEL instead. */
LLM_MODEL_NAME,
+ /** @deprecated Use GEN_AI_PROMPTS instead. */
LLM_PROMPTS,
+ /** @deprecated Use GEN_AI_REQUEST_PARAMETERS instead. */
LLM_INVOCATION_PARAMETERS,
+ /** @deprecated Use GEN_AI_USAGE_OUTPUT_TOKENS instead. */
LLM_TOKEN_COUNT_COMPLETION,
+ /** @deprecated Use GEN_AI_USAGE_OUTPUT_TOKENS_REASONING instead. */
LLM_TOKEN_COUNT_COMPLETION_DETAILS_REASONING,
+ /** @deprecated Use GEN_AI_USAGE_OUTPUT_TOKENS_AUDIO instead. */
LLM_TOKEN_COUNT_COMPLETION_DETAILS_AUDIO,
+ /** @deprecated Use GEN_AI_USAGE_INPUT_TOKENS instead. */
LLM_TOKEN_COUNT_PROMPT,
+ /** @deprecated Use GEN_AI_USAGE_CACHE_WRITE_TOKENS instead. */
LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE,
+ /** @deprecated Use GEN_AI_USAGE_CACHE_READ_TOKENS instead. */
LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ,
+ /** @deprecated Use GEN_AI_USAGE_INPUT_TOKENS_AUDIO instead. */
LLM_TOKEN_COUNT_PROMPT_DETAILS_AUDIO,
+ /** @deprecated Use GEN_AI_USAGE_TOTAL_TOKENS instead. */
LLM_TOKEN_COUNT_TOTAL,
+ /** @deprecated Use GEN_AI_PROVIDER_NAME instead. */
LLM_SYSTEM,
+ /** @deprecated Use GEN_AI_PROVIDER_NAME instead. */
LLM_PROVIDER,
+ /** @deprecated Use GEN_AI_TOOL_DEFINITIONS instead. */
LLM_TOOLS,
MESSAGE_ROLE,
MESSAGE_NAME,
@@ -683,6 +764,7 @@ export const SemanticAttributePrefixes = {
RERANKER_QUERY,
RERANKER_MODEL_NAME,
RERANKER_TOP_K,
+ /** @deprecated Use GEN_AI_TOOL_CALL instead. */
LLM_FUNCTION_CALL,
RETRIEVAL_DOCUMENTS,
SESSION_ID,