Quick Setup: Send Your First Trace

Install noveum-trace, capture one complete model call, and verify it in Noveum.

This guide adds noveum-trace to an existing Python application. It assumes your model provider client is already installed and working.

Prerequisites

Python 3.9 or later
a Noveum account and API key
an existing model call you can run locally

Create an API key from your organization's Settings > API Keys page. Store it in the environment rather than in source code.

Install `noveum-trace`

pip install noveum-trace

Do not reinstall LangChain, LangGraph, LiveKit, Pipecat, CrewAI, or your model provider when adding tracing to an application that already uses them.

Configure the application

export NOVEUM_API_KEY="your-api-key"
export NOVEUM_PROJECT="support-agent"
export NOVEUM_ENVIRONMENT="development"
export NOVEUM_SERVICE_VERSION="support-agent-v1"

NOVEUM_SERVICE_VERSION identifies the agent behavior that produced a trace. Change it when a prompt, model, tool, retrieval strategy, or agent workflow changes. Do not increment it only because infrastructure was redeployed.

Initialize noveum-trace once when the application starts:

import os

import noveum_trace

noveum_trace.init(
    api_key=os.environ["NOVEUM_API_KEY"],
    project=os.environ["NOVEUM_PROJECT"],
    environment=os.environ["NOVEUM_ENVIRONMENT"],
    service_version=os.environ["NOVEUM_SERVICE_VERSION"],
)

Capture one complete model call

The trace must include the evidence a later ETL mapper and scorer will consume. This example records the system prompt, input, output, model identity, and token usage.

from openai import OpenAI
from noveum_trace import trace_llm_call

client = OpenAI()
system_prompt = "Answer clearly and state when information is unavailable."

def answer(question: str) -> str:
    messages = [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": question},
    ]

    with trace_llm_call(model="gpt-4o-mini", provider="openai") as span:
        span.set_attributes({
            "function.type": "llm_call",
            "llm.system_prompt": system_prompt,
            "llm.input.messages": messages,
            "llm.prompt": question,
        })

        response = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=messages,
        )
        output = response.choices[0].message.content or ""

        span.set_attributes({
            "llm.output.response": output,
            "llm.completion": output,
            "llm.usage.input_tokens": response.usage.prompt_tokens,
            "llm.usage.output_tokens": response.usage.completion_tokens,
            "llm.usage.total_tokens": response.usage.total_tokens,
        })
        return output

print(answer("What can this agent help me with?"))
noveum_trace.flush()

Call flush() before a short-lived process exits. Long-running services send buffered spans in the background.

Verify the trace

Open Project Traces, select the project and environment from the configuration, and inspect the new trace.

Confirm that it contains:

the expected service_version
one model span with the system prompt, input, and output
model and provider identity
input, output, and total token counts
a successful or error status and realistic duration

Do not continue to ETL until representative successful and failed traces contain the evidence you need. Tool-calling and RAG agents require additional fields described in the SDK integration guide.

Troubleshoot delivery

Symptom	Check
Authentication error	Verify `NOVEUM_API_KEY` is set in the running process and has trace write access.
No trace appears	Call `flush()` in short scripts, confirm outbound HTTPS access, and inspect the application log level for transport errors.
Trace appears in the wrong place	Compare `NOVEUM_PROJECT` and `NOVEUM_ENVIRONMENT` with the active filters.
Trace is too large	Avoid raw audio or binary payloads in attributes, retain references instead, and bound retrieved context to what evaluation needs.
Version comparison is empty	Keep one stable `NOVEUM_SERVICE_VERSION` per agent behavior and send traffic for both versions.

Continue to evaluation

Choose the next guide for your application: