> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnetra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Initialization

> Configure the Netra SDK with Netra.init() in Python and TypeScript. Set your API key, environment, trace content, and instrument selection at startup.

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

<CodeGroup>
  ```python Python theme={null}
  from netra import Netra

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

  ```typescript TypeScript theme={null}
  import { Netra } from "netra-sdk";

  await Netra.init({
    appName: "my-ai-app",
    environment: "production",
  });
  ```
</CodeGroup>

## 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                                            |

<Note>
  For instrumentation control details, see [Instrumentation Selection](/Observability/Traces/configuration/instrumentation-selection).
</Note>

## Complete Example

<CodeGroup>
  ```python Python theme={null}
  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,
      },
  )
  ```

  ```typescript TypeScript theme={null}
  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,
    ]),
  });
  ```
</CodeGroup>

<Warning>
  PII scrubbing (`enable_scrubbing`) adds processing overhead. Only enable when handling sensitive data.
</Warning>

## Configuration Precedence

Configuration values are resolved in order of priority:

1. **Code parameters** - Values passed to `Netra.init()`
2. **Netra environment variables** - `NETRA_*` variables
3. **OpenTelemetry environment variables** - `OTEL_*` variables
4. **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 TypeScript theme={null}
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
}
```

<Note>
  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.
</Note>

## Shutdown

Ensure all pending spans are exported before application exit:

<CodeGroup>
  ```python Python theme={null}
  Netra.shutdown()
  ```

  ```typescript TypeScript theme={null}
  await Netra.shutdown();
  ```
</CodeGroup>

<Note>
  Always call `shutdown()` before exit, especially for short-lived processes like serverless functions.
</Note>

## Next Steps

* [Environment Variables](/Observability/Traces/configuration/environment-variables) - Configure via environment
* [Instrumentation Selection](/Observability/Traces/configuration/instrumentation-selection) - Control which libraries are traced
* [Custom Exporters](/Observability/Traces/configuration/custom-exporters) - Send traces to custom backends