Set Trace Environments

Set your environments during tracing for better debugging

Included on the Enterprise plan. Book a demo, opens in a new tab. Included on the Team plan. Included on the Starter plan. Not included on the Free plan.

Overview

The environment feature allows you to specify which environment your traces are coming from. This is useful for separating traces from different environments in "development", "staging", "production", or "testing", so you can filter the observatory and scope evaluations to the deployment you care about.

Configure Environment

Most applications run in exactly one environment per process, so the easiest option is to set it once with the CONFIDENT_ENVIRONMENT environment variable — every trace from that process will carry it:

export CONFIDENT_ENVIRONMENT="staging"

Alternatively, you can set the environment directly in code when you call init():

main.py

from openai import OpenAI
from confident_trace import init, shutdown

init(environment="production")
client = OpenAI()

def llm_app(query: str):
    return client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": query}]
    ).choices[0].message.content

try:
    llm_app("Write me a poem.")
finally:
    shutdown()

src/index.ts

import OpenAI from "openai";
import { init } from "confident-trace";

const runtime = init({ environment: "production" });
const openai = new OpenAI();

const llmApp = async (query: string) => {
    const result = await openai.chat.completions.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: query }],
    });
    return result.choices[0].message.content;
};

try {
    await llmApp("Write me a poem.");
} finally {
    await runtime.shutdown();
}

Run your entry point with the Node preload so the OpenAI call is instrumented.

The environment is typically "production", "staging", or "development", and helps you identify where your traces are coming from. An explicit init() argument wins over the environment variable — see configure init() for the full precedence order.

Override Environment Per Trace

Occasionally a single process serves more than one environment — a canary that handles a slice of production traffic, or a shared worker that runs staging and production jobs. Keep the startup default, then choose between two per-request options:

Explicitly change the environment on an active trace.
Supply an environment default to traces started inside a scope.

Change an Active Trace

If your request already has an active span, use the trace update helper to explicitly change that trace's environment:

main.py

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

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

@span(type="agent", name="LLM App")
def llm_app(query: str, is_canary: bool):
    if is_canary:
        update_trace(environment="staging")
    return model.invoke(query)

src/index.ts

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

init({ environment: "production" });

const llmApp = span(
    { name: "LLM App", type: "agent" },
    async (query: string, isCanary: boolean) => {
        if (isCanary) updateTrace({ environment: "staging" });
        return generateText({
            model: openai("gpt-4o"),
            prompt: query,
        });
    },
);

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

The explicit value replaces the startup default for that active trace only. Every other trace keeps the environment from init() / CONFIDENT_ENVIRONMENT.

Supply Defaults for Work in a Scope

For traces started inside the scope, the trace-context value overrides the environment passed to init(), which in turn overrides CONFIDENT_ENVIRONMENT. The scope doesn't change either global setting; it only changes the environment applied to work inside it.

main.py

from langchain_openai import ChatOpenAI
from confident_trace import init, trace_context

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

def llm_app(query: str, is_canary: bool):
    env = "staging" if is_canary else "production"
    with trace_context(environment=env):
        return model.invoke(query)

src/index.ts

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

init({ environment: "production" });

const llmApp = async (query: string, isCanary: boolean) => {
    const environment = isCanary ? "staging" : "production";
    return traceContext({ environment }, () =>
        generateText({ model: openai("gpt-4o"), prompt: query }),
    );
};

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

Next Steps

Configure init()

See every setting init() accepts — API key, endpoint, sample rate, and environment — and how env vars and arguments interact.

Sampling

Export only a fraction of production traces while keeping staging at 100%.

Ready to monitor AI in production?Connect traces, alerts, dashboards, and evals in one production workflowBook a demo

Last updated on September 10, 2026