Custom Python Tracing

Use the Python context managers when the application calls a model provider directly or when no framework adapter matches the workflow. Define the end-to-end trace boundary explicitly, then create child spans for model, retrieval, tool, and agent operations.

Install and initialize

pip install noveum-trace

import os

import noveum_trace

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

Initialize once before instrumented work begins.

Trace one complete request

This example keeps the application boundary, model input, model output, and usage in one connected trace:

from openai import OpenAI
from noveum_trace import trace_llm_call, trace_operation

client = OpenAI()
messages = [
    {"role": "system", "content": system_prompt},
    {"role": "user", "content": user_message},
]

with trace_operation("support-agent.request") as root_span:
    root_span.set_attributes({
        "request.id": request_id,
        "agent.task": user_message,
    })

    with trace_llm_call(
        model="gpt-4o-mini",
        provider="openai",
        operation="answer.generate",
    ) as llm_span:
        llm_span.set_input_attributes(messages=messages)
        response = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=messages,
        )
        llm_span.capture_response(response)
        llm_span.set_output_attributes(response=response)

    answer = response.choices[0].message.content or ""
    root_span.set_attributes({
        "agent.response": answer,
        "exit_status": "completed",
    })

capture_response() extracts supported provider metadata and usage. set_output_attributes() preserves the structured result for later ETL mapping.

For a short-lived process, flush after all work finishes:

noveum_trace.flush()

Add retrieval and tools

Create child trace_operation() spans for retrieval and tool execution. Preserve the exact query and ordered documents for retrieval. Preserve offered schemas, selected tool, arguments, result, and errors for tool use.

Follow the trace design guide for span boundaries and attribute names. The evaluation capture contract lists the evidence required by each workflow type.

Protect payloads

Verify the trace

Run one successful request and one controlled provider error, then confirm:

1. the root span covers the complete request
2. the model span is a child of the root
3. the input messages and output are present
4. model, provider, and token usage are present
5. the error request records exception details and error status
6. the trace has the expected project, environment, and service version

Use a framework adapter instead when the application runs LangChain, LangGraph, CrewAI, LiveKit, or Pipecat.