Add Metadata to Traces

Adding metadata to your traces for additional information

Overview

With Confident AI, you can attach additional metadata to traces, spans, and threads. This information can be used for filtering, grouping, and analyzing your traces in the observatory — for example, to compare traces by app version, model, or the knowledge base a retriever hit.

Add Metadata to Traces

Open a trace context around the work and provide a metadata object whose keys are strings and whose values are any JSON-serializable type:

main.py

from langchain_openai import ChatOpenAI
from confident_trace import init, trace_context

init()
model = ChatOpenAI(model="gpt-4o")

def llm_app(query: str):
    with trace_context(
        metadata={
            "app_version": "1.2.3",
            "knowledge_base": "support-v2",
        }
    ):
        return model.invoke(query)

src/index.ts

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { init, traceContext } from "confident-trace";

init();

const llmApp = (query: string) =>
    traceContext(
        {
            metadata: {
                app_version: "1.2.3",
                knowledge_base: "support-v2",
            },
        },
        () => generateText({ model: openai("gpt-4o"), prompt: query }),
    );

Run your entry point with the Node preload so the Vercel AI SDK call is instrumented.

Metadata objects are not merged. A trace context supplies the complete object as a default, and it won't overwrite metadata already set on the trace. Gather all the trace metadata you need into one object.

See Update Trace Properties for the full trace-context behavior.

Add Metadata to Spans

For a span you create yourself, update its metadata while that span is active:

main.py

from langchain_openai import ChatOpenAI
from confident_trace import init, span, update_span

init()
model = ChatOpenAI(model="gpt-4o")

@span(type="agent", name="Support Request")
def llm_app(query: str):
    response = model.invoke(query)
    update_span(metadata={"app_version": "1.2.3"})
    return response

src/index.ts

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { init, span, updateSpan } from "confident-trace";

init();

const llmApp = span(
  { name: "Support Request", type: "agent" },
  async (query: string) => {
    const response = await generateText({
      model: openai("gpt-4o"),
      prompt: query,
    });
    updateSpan({ metadata: { app_version: "1.2.3" } });
    return response;
  },
);

The span update helper requires an active span and replaces the entire metadata object when called again. It is only needed for span-level metadata; use a trace context for trace-level metadata.

Thread-Level Metadata

You can also attach metadata to threads — useful for tagging production conversations with attributes like DVA version, client, or agent ID. See Set Thread Fields for how to pass a thread object to update_trace.

Overview

Add Metadata to Traces

Add Metadata to Spans

Thread-Level Metadata

Next Steps