Initialization

The Netra.init() function configures the SDK and starts the tracing system. Call it once at the start of your application, before making any LLM or database calls.

Quick Start

from netra import Netra

Netra.init(
    app_name="my-ai-app",
    environment="production",
)

import { Netra } from "netra-sdk";

await Netra.init({
  appName: "my-ai-app",
  environment: "production",
});

Configuration Parameters

Parameter	Type	Default	Description
`app_name` / `appName`	string	Required	Application name for identifying traces in the dashboard
`environment`	string	`"default"` (Py) / `"local"` (TS)	Deployment environment (e.g., `production`, `staging`, `development`)
`headers`	string	`""`	Authentication headers, typically `x-api-key=YOUR_KEY`
`trace_content` / `traceContent`	boolean	`true`	Capture prompt/completion content from LLM calls. Disable for privacy.
`debug_mode` / `debugMode`	boolean	`false`	Enable verbose logging for troubleshooting
`disable_batch` / `disableBatch`	boolean	`false`	Send spans immediately instead of batching
`enable_root_span` / `enableRootSpan`	boolean	`false`	Create a root span for the entire process (useful for workers)
`resource_attributes` / `resourceAttributes`	dict/object	`{}`	Custom attributes added to every span
`blocked_spans` / `blockedSpans`	list/array	`[]`	Span name patterns to exclude (supports `*` wildcards)
`enable_scrubbing`	boolean	`false`	Auto-redact detected PII (Python only)
`instruments`	Set/list	All	Specific instrumentations to enable
`block_instruments` / `blockInstruments`	Set/list	`[]`	Instrumentations to disable

For instrumentation control details, see Instrumentation Selection.

Complete Example

import os
from netra import Netra
from netra.instrumentation.instruments import InstrumentSet

Netra.init(
    # Core settings
    app_name="production-ai-service",
    environment="production",
    headers=f"x-api-key={os.getenv('NETRA_API_KEY')}",

    # Content and privacy
    trace_content=True,
    enable_scrubbing=False,

    # Performance
    disable_batch=False,

    # Debugging
    debug_mode=False,

    # Long-running processes
    enable_root_span=False,

    # Custom metadata added to all spans
    resource_attributes={
        "service.version": os.getenv("APP_VERSION"),
        "deployment.region": os.getenv("AWS_REGION"),
        "team": "ml-platform",
    },

    # Span filtering (supports wildcards)
    blocked_spans=[
        "health-check",   # Exact match
        "internal.*",     # Prefix match
        "*.debug",        # Suffix match
    ],

    # Instrumentation control
    block_instruments={
        InstrumentSet.HTTPX,
        InstrumentSet.REQUESTS,
    },
)

import { Netra, NetraInstruments } from "netra-sdk";

await Netra.init({
  // Core settings
  appName: "production-ai-service",
  environment: "production",
  headers: `x-api-key=${process.env.NETRA_API_KEY}`,

  // Content and privacy
  traceContent: true,

  // Performance
  disableBatch: false,

  // Debugging
  debugMode: false,

  // Long-running processes
  enableRootSpan: false,

  // Custom metadata added to all spans
  resourceAttributes: {
    "service.version": process.env.APP_VERSION,
    "deployment.region": process.env.AWS_REGION,
    "team": "ml-platform",
  },

  // Span filtering (supports wildcards)
  blockedSpans: [
    "health-check",   // Exact match
    "internal.*",     // Prefix match
    "*.debug",        // Suffix match
  ],

  // Instrumentation control
  blockInstruments: new Set([
    NetraInstruments.HTTP,
    NetraInstruments.FETCH,
  ]),
});

PII scrubbing (enable_scrubbing) adds processing overhead. Only enable when handling sensitive data.

Configuration Precedence

Configuration values are resolved in order of priority:

Code parameters - Values passed to Netra.init()
Netra environment variables - NETRA_* variables
OpenTelemetry environment variables - OTEL_* variables
Default values - SDK defaults

Async Initialization (TypeScript)

The Netra.init() method in TypeScript is async and waits for all instrumentations to be ready before returning. Always await the call to ensure proper instrumentation:

TypeScript

async function main() {
  // init() is async and waits for instrumentations to be ready
  await Netra.init({
    appName: "my-ai-app",
    environment: "production",
  });
  // SDK is fully initialized, all instrumentations are patched
}

Always await Netra.init() to ensure libraries like OpenAI, Anthropic, and LangGraph are properly instrumented before use. This is especially important in frameworks like NestJS where modules are loaded after initialization.

Shutdown

Ensure all pending spans are exported before application exit:

Netra.shutdown()

await Netra.shutdown();

Always call shutdown() before exit, especially for short-lived processes like serverless functions.

Next Steps

Environment Variables - Configure via environment
Instrumentation Selection - Control which libraries are traced
Custom Exporters - Send traces to custom backends

Get Started

Observability

Insights

Evaluation

Simulation

Red Teaming

Prompt Management

Monitoring & Dashboard

Account settings

Migrations

Quick Start

Configuration Parameters

Complete Example

Configuration Precedence

Async Initialization (TypeScript)

Shutdown

Next Steps

​Quick Start

​Configuration Parameters

​Complete Example

​Configuration Precedence

​Async Initialization (TypeScript)

​Shutdown

​Next Steps

Quick Start

Configuration Parameters

Complete Example

Configuration Precedence

Async Initialization (TypeScript)

Shutdown

Next Steps