Merge pull request #557 from future-agi/fix/rewrite-tracing-enriching-spans

rewrite manual tracing enriching spans

Author: hadarishav

src/pages/docs/observe/features/manual-tracing/add-attributes-metadata-tags.mdx

@@ -3,17 +3,19 @@ title: "Enriching Spans with Attributes, Metadata, and Tags"
 description: "Capture additional context beyond what standard frameworks provide by enriching your traces with custom attributes, metadata, tags, session IDs, user IDs, and prompt templates."
 ---
 
-## What it is
+## About
 
-**Enriching Spans** lets you attach custom key/value pairs and structured context to your OpenTelemetry spans so they carry the full picture of what's happening in your application. You can add raw attributes with `set_attribute()`, use traceAI Semantic Convention constants for structured LLM data, or use context managers (`using_metadata`, `using_tags`, `using_session`, `using_user`, `using_prompt_template`) to propagate attributes automatically to all child spans — without modifying every instrumented function.
+A trace with only timing and status tells what happened, but not why. Without attributes like experiment IDs, feature flags, or prompt versions, filtering and debugging in the dashboard requires guesswork. Enriching spans attaches this application-specific context directly to traces so they become searchable, filterable, and meaningful. There are three ways to do it: add key/value pairs directly with `set_attribute()`, use traceAI Semantic Convention constants for structured LLM data, or use context managers (`using_metadata`, `using_tags`, `using_session`, `using_user`, `using_prompt_template`) to propagate attributes automatically to all child spans in a block.
 
-## Use cases
+---
+
+## When to use
 
-- **Custom attributes** — Add business-specific key/value pairs to spans for filtering and debugging in the Future AGI dashboard.
-- **Semantic conventions** — Use traceAI constants like `OUTPUT_VALUE` and `LLM_OUTPUT_MESSAGES` to capture LLM outputs in a structured, queryable schema.
-- **Metadata enrichment** — Attach experiment metadata, feature flags, or A/B test identifiers to all spans in a code block.
-- **Session and user tracking** — Associate spans with a session ID and user ID for session replay and per-user analytics.
-- **Prompt template tracking** — Record which prompt template, version, and variables were used in each LLM call.
+- **Custom attributes for filtering**: Attach business-specific key/value pairs to spans so they can be filtered and searched in the dashboard.
+- **Structured LLM outputs**: Use traceAI constants like `OUTPUT_VALUE` and `LLM_OUTPUT_MESSAGES` to capture LLM responses in a queryable schema.
+- **Experiment and A/B test tracking**: Attach metadata like experiment IDs or feature flags to all spans in a code block.
+- **Session and user grouping**: Associate spans with a session ID and user ID for session replay and per-user analytics.
+- **Prompt template versioning**: Record which prompt template, version, and variables were used in each LLM call.
 
 ---
 
@@ -35,7 +37,7 @@ description: "Capture additional context beyond what standard frameworks provide
     current_span.set_attribute("operation.other-stuff", [1, 2])
     ```
 
-    ```typescript JS/TS
+    ```javascript JS/TS
     import { trace, context } from "@opentelemetry/api";
 
     const currentSpan = trace.getSpan(context.active());
@@ -55,11 +57,11 @@ description: "Capture additional context beyond what standard frameworks provide
 
     <CodeGroup>
 
-    ```bash Python
+    ```python Python
     pip install fi-instrumentation-otel
     ```
 
-    ```bash JS/TS
+    ```javascript JS/TS
     npm install @traceai/fi-core @opentelemetry/api
     ```
 
@@ -80,16 +82,16 @@ description: "Capture additional context beyond what standard frameworks provide
 
         # This shows up under `output_messages` tab on the span page
         span.set_attribute(
-            f"{SpanAttributes.LLM_OUTPUT_MESSAGES}.0.{MessageAttributes.MESSAGE_ROLE}",
+            f"{SpanAttributes.GEN_AI_OUTPUT_MESSAGES}.0.{MessageAttributes.MESSAGE_ROLE}",
             "user",
         )
         span.set_attribute(
-            f"{SpanAttributes.LLM_OUTPUT_MESSAGES}.0.{MessageAttributes.MESSAGE_CONTENT}",
+            f"{SpanAttributes.GEN_AI_OUTPUT_MESSAGES}.0.{MessageAttributes.MESSAGE_CONTENT}",
             response,
         )
     ```
 
-    ```typescript JS/TS
+    ```javascript JS/TS
     import { trace, context } from "@opentelemetry/api";
 
     // Assume 'response' variable is defined, e.g.:
@@ -133,7 +135,7 @@ description: "Capture additional context beyond what standard frameworks provide
                 pass # Your code here
             ```
 
-            ```typescript JS/TS
+            ```javascript JS/TS
             import { context, propagation } from "@opentelemetry/api";
 
             // Assuming value_1, value_2 are defined
@@ -189,7 +191,7 @@ description: "Capture additional context beyond what standard frameworks provide
                 pass # Your code here
             ```
 
-            ```typescript JS/TS
+            ```javascript JS/TS
             import { context, propagation } from "@opentelemetry/api";
 
             // Assuming tags list is defined, e.g.:
@@ -241,7 +243,7 @@ description: "Capture additional context beyond what standard frameworks provide
                 pass # Your code here
             ```
 
-            ```typescript JS/TS
+            ```javascript JS/TS
             import { context, propagation } from "@opentelemetry/api";
 
             // Assuming session_id is defined, e.g.:
@@ -293,7 +295,7 @@ description: "Capture additional context beyond what standard frameworks provide
                 pass # Your code here
             ```
 
-            ```typescript JS/TS
+            ```javascript JS/TS
             import { context, propagation } from "@opentelemetry/api";
 
             // Assuming user_id is defined, e.g.:
@@ -353,7 +355,7 @@ description: "Capture additional context beyond what standard frameworks provide
                 pass # Your code here
             ```
 
-            ```typescript JS/TS
+            ```javascript JS/TS
             import { context, propagation } from "@opentelemetry/api";
 
             // Assuming template, version, and variables are defined, e.g.:
@@ -425,7 +427,7 @@ description: "Capture additional context beyond what standard frameworks provide
         pass # Your code here
     ```
 
-    ```typescript JS/TS
+    ```javascript JS/TS
     import { context, propagation } from "@opentelemetry/api";
 
     const metadata = {"experiment": "A/B test", "version": "2.1"};
@@ -460,18 +462,18 @@ description: "Capture additional context beyond what standard frameworks provide
 
 ## Key concepts
 
-- **`set_attribute()`** — Attaches a key/value pair directly to the active span. Supports strings, numbers, and booleans. Prefix custom attributes with your company name to avoid naming conflicts.
-- **Semantic Conventions** — Structured attribute names defined by traceAI for common LLM data (messages, prompt templates, token counts). Use `SpanAttributes` and `MessageAttributes` constants from `fi_instrumentation.fi_types`.
-- **Context attributes (Baggage)** — Set at the OpenTelemetry context level so they propagate automatically to all child spans within the block, without modifying instrumented functions.
-- **`using_metadata`** — Attaches a JSON-serialized metadata dictionary to all spans in the context as the `metadata` attribute.
-- **`using_tags`** — Attaches a JSON-serialized list of tag strings to all spans as `tag.tags`.
-- **`using_session`** — Sets `session.id` on all spans in the context for session grouping.
-- **`using_user`** — Sets `user.id` on all spans in the context for per-user tracking.
-- **`using_prompt_template`** — Sets `llm.prompt_template.template`, `llm.prompt_template.version`, and `llm.prompt_template.variables` on all spans in the context.
+- **`set_attribute()`**:Attaches a key/value pair directly to the active span. Supports strings, numbers, and booleans. Prefix custom attributes with your company name to avoid naming conflicts.
+- **Semantic Conventions**:Structured attribute names defined by traceAI for common LLM data (messages, prompt templates, token counts). Use `SpanAttributes` and `MessageAttributes` constants from `fi_instrumentation.fi_types`.
+- **Context attributes (Baggage)**:Set at the OpenTelemetry context level so they propagate automatically to all child spans within the block, without modifying instrumented functions.
+- **`using_metadata`**:Attaches a JSON-serialized metadata dictionary to all spans in the context as the `metadata` attribute.
+- **`using_tags`**:Attaches a JSON-serialized list of tag strings to all spans as `tag.tags`.
+- **`using_session`**:Sets `session.id` on all spans in the context for session grouping.
+- **`using_user`**:Sets `user.id` on all spans in the context for per-user tracking.
+- **`using_prompt_template`**:Sets `llm.prompt_template.template`, `llm.prompt_template.version`, and `llm.prompt_template.variables` on all spans in the context.
 
 ---
 
-## What you can do next
+## Next Steps
 
 <CardGroup cols={2}>
   <Card title="Set Up Tracing" icon="gear" href="/docs/observe/features/manual-tracing/set-up-tracing">