Skip to main content

Configuration

Configure Observra once per process, before creating provider clients:

import os

import observra

config = observra.configure(
    gateway_key=os.environ["OBSERVRA_GATEWAY_KEY"],
)

gateway_key is your Observra gateway API key. It authenticates your application to the Observra Gateway and determines where gateway observations are recorded. configure() returns an immutable ObservraConfig and installs provider routing automatically.

Gateway API key​

Set your Observra gateway API key in OBSERVRA_GATEWAY_KEY:

export OBSERVRA_GATEWAY_KEY="obs_live_xxx"

Or pass it explicitly:

observra.configure(gateway_key="obs_live_xxx")

The gateway API key is required. configure() raises ObservraConfigError when it is missing.

Provider API keys stay separate​

Your gateway API key is not an OpenAI, Anthropic, Gemini, or other provider API key. Continue configuring each provider with its own credential:

from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

For supported provider hosts, Observra sends OBSERVRA_GATEWAY_KEY as the gateway credential and forwards the provider's bearer credential separately. Do not use the gateway API key as a provider-client api_key.

Environment variable​

VariablePurpose
OBSERVRA_GATEWAY_KEYRequired Observra gateway API key

An explicit gateway_key argument takes precedence over the environment variable. The SDK uses Observra's hosted gateway by default.

instrument()​

observra.instrument()

instrument() adds installed framework integrations for LangChain, LangGraph, LlamaIndex, CrewAI, and Semantic Kernel. It is idempotent. Provider routing comes from configure(); framework instrumentation is optional.

Security and behaviour​

  • ObservraConfig.__repr__ and str() mask most gateway API-key characters.
  • Provider API keys are not written into trace attributes.
  • Requests to unknown hosts remain untouched.
  • The SDK uses a private OpenTelemetry tracer provider. It does not overwrite your process-wide provider.
  • Telemetry failures do not block provider requests.

Next​