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

# Instrumentation Selection

> Selectively enable or disable Netra instrumentations per provider or framework. Control which LLM providers and databases are traced in your app.

By default, Netra instruments a **curated set** of AI-relevant libraries detected in your application. You can customize this behavior to enable only specific instrumentations, block certain ones, or opt into instrumenting all available libraries.

## How It Works

Netra provides three parameters for controlling instrumentations:

| Parameter           | Behavior                                                                                                                       | Default                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
| `instruments`       | Set of libraries to instruments. When provided, **only** these instrumentations are enabled.                                   | `DEFAULT_INSTRUMENTS`          |
| `root_instruments`  | Set of libraries allowed to produce **root-level spans**. (see [Controlling Root-Level Spans](#controlling-root-level-spans)). | `DEFAULT_INSTRUMENTS_FOR_ROOT` |
| `block_instruments` | These instrumentations are **excluded** from both `instruments` and `root_instruments` independently.                          | `None`                         |

<Note>
  Use `instruments` when you want a minimal setup with only specific libraries traced. Use `block_instruments` when you want the curated defaults but need to exclude a few. Use `root_instruments` to control which libraries can start new top-level traces.
</Note>

### The `ALL` Sentinel

Pass `NetraInstruments.ALL` to restore the legacy behavior of instrumenting every supported library found in your environment:

```python Python theme={null}
from netra import Netra, NetraInstruments

Netra.init(
    app_name="my-ai-app",
    instruments={NetraInstruments.ALL},
    root_instruments={NetraInstruments.ALL},
)
```

`ALL` can be used in `instruments`, `root_instruments`, and `block_instruments`. When present in `block_instruments`, it blocks all instrumentations.

## Enabling Specific Instrumentations

Use the `instruments` parameter to enable only the instrumentations you need:

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

  Netra.init(
      app_name="my-ai-app",
      instruments={
          NetraInstruments.OPENAI,
          NetraInstruments.PINECONE,
          NetraInstruments.LANGCHAIN,
      },
  )
  ```

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

  await Netra.init({
    appName: "my-ai-app",
    instruments: new Set([
      NetraInstruments.OPENAI,
      NetraInstruments.PINECONE,
      NetraInstruments.LANGCHAIN,
    ]),
  });
  ```
</CodeGroup>

## Blocking Specific Instrumentations

Use `block_instruments` to exclude certain instrumentations while keeping the curated defaults:

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

  # Use curated defaults except HTTP clients
  Netra.init(
      app_name="my-ai-app",
      block_instruments={
          NetraInstruments.HTTPX,
          NetraInstruments.AIOHTTP,
          NetraInstruments.REQUESTS,
      },
  )
  ```

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

  // Use curated defaults except HTTP clients
  await Netra.init({
    appName: "my-ai-app",
    blockInstruments: new Set([
      NetraInstruments.HTTP,
      NetraInstruments.HTTPS,
      NetraInstruments.FETCH,
    ]),
  });
  ```
</CodeGroup>

## Controlling Root-Level Spans

Use `root_instruments` (`rootInstruments` in TypeScript) to control which libraries can produce root-level spans. It is independent of `instruments`, and defaults to the curated `DEFAULT_INSTRUMENTS_FOR_ROOT` subset (LLM providers and AI frameworks) when omitted.

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

  # Instrument the curated defaults, but only allow LLM providers to start traces
  Netra.init(
      app_name="my-ai-app",
      root_instruments={
          NetraInstruments.OPENAI,
          NetraInstruments.ANTHROPIC,
          NetraInstruments.GOOGLE_GENERATIVEAI,
      },
  )
  ```

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

  // Instrument the curated defaults, but only allow LLM providers to start traces
  await Netra.init({
    appName: "my-ai-app",
    rootInstruments: new Set([
      NetraInstruments.OPENAI,
      NetraInstruments.ANTHROPIC,
      NetraInstruments.GOOGLE_GENAI,
    ]),
  });
  ```
</CodeGroup>

Pass the `ALL` sentinel to `root_instruments` / `rootInstruments` to let every instrumentation produce root spans (legacy behavior). When a root span is enabled via `enable_root_span` / `enableRootSpan`, Netra attaches its own root span and every auto-instrumentation span becomes its child, so `root_instruments` has no effect.

<Warning>
  When a root span comes from an instrumentation outside the allowed set, only the disallowed root span is dropped: its children are **reparented** onto its parent so nested LLM and vector spans are kept. Use this to filter out noisy top-level traces from HTTP clients, web frameworks, or database drivers.
</Warning>

## Available Instruments

### Python Instruments

#### LLM Providers

| Instrument                          | Description               |
| ----------------------------------- | ------------------------- |
| `InstrumentSet.OPENAI`              | OpenAI API calls          |
| `InstrumentSet.ANTHROPIC`           | Anthropic Claude API      |
| `InstrumentSet.COHERE`              | Cohere API                |
| `InstrumentSet.GOOGLE_GENERATIVEAI` | Google Generative AI      |
| `InstrumentSet.MISTRALAI`           | Mistral AI API            |
| `InstrumentSet.GROQ`                | Groq API                  |
| `InstrumentSet.BEDROCK`             | AWS Bedrock               |
| `InstrumentSet.VERTEXAI`            | Google Vertex AI          |
| `InstrumentSet.OLLAMA`              | Ollama local models       |
| `InstrumentSet.REPLICATE`           | Replicate API             |
| `InstrumentSet.TOGETHER`            | Together AI               |
| `InstrumentSet.TRANSFORMERS`        | Hugging Face Transformers |
| `InstrumentSet.LITELLM`             | LiteLLM unified interface |

#### AI Frameworks

| Instrument                  | Description          |
| --------------------------- | -------------------- |
| `InstrumentSet.LANGCHAIN`   | LangChain framework  |
| `InstrumentSet.LANGGRAPH`   | LangGraph workflows  |
| `InstrumentSet.LLAMAINDEX`  | LlamaIndex framework |
| `InstrumentSet.HAYSTACK`    | Haystack framework   |
| `InstrumentSet.CREWAI`      | CrewAI agents        |
| `InstrumentSet.DSPY`        | DSPy framework       |
| `InstrumentSet.PYDANTIC_AI` | Pydantic AI          |

#### Vector Databases

| Instrument               | Description              |
| ------------------------ | ------------------------ |
| `InstrumentSet.PINECONE` | Pinecone vector database |
| `InstrumentSet.WEAVIATE` | Weaviate vector database |
| `InstrumentSet.QDRANT`   | Qdrant vector database   |
| `InstrumentSet.CHROMADB` | ChromaDB vector database |
| `InstrumentSet.MILVUS`   | Milvus vector database   |
| `InstrumentSet.LANCEDB`  | LanceDB vector database  |
| `InstrumentSet.MARQO`    | Marqo vector database    |

#### HTTP Clients

| Instrument               | Description          |
| ------------------------ | -------------------- |
| `InstrumentSet.HTTPX`    | HTTPX async client   |
| `InstrumentSet.AIOHTTP`  | AIOHTTP async client |
| `InstrumentSet.REQUESTS` | Requests library     |
| `InstrumentSet.URLLIB`   | urllib library       |
| `InstrumentSet.URLLIB3`  | urllib3 library      |

#### Web Frameworks

| Instrument                | Description         |
| ------------------------- | ------------------- |
| `InstrumentSet.FASTAPI`   | FastAPI framework   |
| `InstrumentSet.FLASK`     | Flask framework     |
| `InstrumentSet.DJANGO`    | Django framework    |
| `InstrumentSet.STARLETTE` | Starlette framework |
| `InstrumentSet.TORNADO`   | Tornado framework   |
| `InstrumentSet.FALCON`    | Falcon framework    |

#### Databases

| Instrument                    | Description           |
| ----------------------------- | --------------------- |
| `InstrumentSet.SQLALCHEMY`    | SQLAlchemy ORM        |
| `InstrumentSet.SQLITE3`       | SQLite3               |
| `InstrumentSet.PSYCOPG`       | PostgreSQL (psycopg)  |
| `InstrumentSet.PSYCOPG2`      | PostgreSQL (psycopg2) |
| `InstrumentSet.PYMYSQL`       | MySQL                 |
| `InstrumentSet.PYMONGO`       | MongoDB               |
| `InstrumentSet.REDIS`         | Redis                 |
| `InstrumentSet.ELASTICSEARCH` | Elasticsearch         |

#### Message Queues

| Instrument                      | Description         |
| ------------------------------- | ------------------- |
| `InstrumentSet.CELERY`          | Celery task queue   |
| `InstrumentSet.PIKA`            | RabbitMQ (pika)     |
| `InstrumentSet.AIO_PIKA`        | RabbitMQ (aio-pika) |
| `InstrumentSet.KAFKA_PYTHON`    | Kafka               |
| `InstrumentSet.CONFLUENT_KAFKA` | Confluent Kafka     |

### TypeScript Instruments

#### LLM Providers

| Instrument                        | Description          |
| --------------------------------- | -------------------- |
| `NetraInstrumentSet.OPENAI`       | OpenAI API calls     |
| `NetraInstrumentSet.GOOGLE_GENAI` | Google Generative AI |
| `NetraInstrumentSet.MISTRAL`      | Mistral AI API       |
| `NetraInstrumentSet.GROQ`         | Groq API             |
| `NetraInstrumentSet.VERTEX_AI`    | Google Vertex AI     |
| `NetraInstrumentSet.TOGETHER`     | Together AI          |

#### AI Frameworks

| Instrument                      | Description          |
| ------------------------------- | -------------------- |
| `NetraInstrumentSet.LANGCHAIN`  | LangChain framework  |
| `NetraInstrumentSet.LANGGRAPH`  | LangGraph workflows  |
| `NetraInstrumentSet.LLAMAINDEX` | LlamaIndex framework |

#### Vector Databases

| Instrument                    | Description              |
| ----------------------------- | ------------------------ |
| `NetraInstrumentSet.PINECONE` | Pinecone vector database |
| `NetraInstrumentSet.QDRANT`   | Qdrant vector database   |
| `NetraInstrumentSet.CHROMADB` | ChromaDB vector database |

#### HTTP Clients

| Instrument                 | Description          |
| -------------------------- | -------------------- |
| `NetraInstrumentSet.HTTP`  | Node.js HTTP module  |
| `NetraInstrumentSet.HTTPS` | Node.js HTTPS module |
| `NetraInstrumentSet.FETCH` | Fetch API            |

#### Web Frameworks

| Instrument                   | Description          |
| ---------------------------- | -------------------- |
| `NetraInstrumentSet.EXPRESS` | Express.js framework |
| `NetraInstrumentSet.FASTIFY` | Fastify framework    |
| `NetraInstrumentSet.NESTJS`  | NestJS framework     |

#### Databases

| Instrument                    | Description |
| ----------------------------- | ----------- |
| `NetraInstrumentSet.PRISMA`   | Prisma ORM  |
| `NetraInstrumentSet.TYPEORM`  | TypeORM     |
| `NetraInstrumentSet.MONGODB`  | MongoDB     |
| `NetraInstrumentSet.POSTGRES` | PostgreSQL  |
| `NetraInstrumentSet.MYSQL`    | MySQL       |
| `NetraInstrumentSet.REDIS`    | Redis       |

#### Message Queues

| Instrument                    | Description |
| ----------------------------- | ----------- |
| `NetraInstrumentSet.KAFKA`    | Kafka       |
| `NetraInstrumentSet.RABBITMQ` | RabbitMQ    |

## Common Use Cases

### LLM-Only Tracing

Trace only LLM provider calls, ignoring HTTP, database, and framework instrumentation:

<CodeGroup>
  ```python Python theme={null}
  from netra import Netra
  from netra.instrumentation.instruments import InstrumentSet

  Netra.init(
      app_name="llm-only-app",
      instruments={
          InstrumentSet.OPENAI,
          InstrumentSet.ANTHROPIC,
          InstrumentSet.GOOGLE_GENERATIVEAI,
      },
  )
  ```

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

  await Netra.init({
    appName: "llm-only-app",
    instruments: new Set([
      NetraInstrumentSet.OPENAI,
      NetraInstrumentSet.GOOGLE_GENAI,
      NetraInstrumentSet.MISTRAL,
    ]),
  });
  ```
</CodeGroup>

### Reduce HTTP Noise

Block HTTP client instrumentation to reduce trace noise while keeping everything else:

<CodeGroup>
  ```python Python theme={null}
  from netra import Netra
  from netra.instrumentation.instruments import InstrumentSet

  Netra.init(
      app_name="my-ai-app",
      block_instruments={
          InstrumentSet.HTTPX,
          InstrumentSet.AIOHTTP,
          InstrumentSet.REQUESTS,
          InstrumentSet.URLLIB,
          InstrumentSet.URLLIB3,
      },
  )
  ```

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

  await Netra.init({
    appName: "my-ai-app",
    blockInstruments: new Set([
      NetraInstrumentSet.HTTP,
      NetraInstrumentSet.HTTPS,
      NetraInstrumentSet.FETCH,
    ]),
  });
  ```
</CodeGroup>

### RAG Application

Instrument only what's needed for a typical RAG application:

<CodeGroup>
  ```python Python theme={null}
  from netra import Netra
  from netra.instrumentation.instruments import InstrumentSet

  Netra.init(
      app_name="rag-app",
      instruments={
          # LLM provider
          InstrumentSet.OPENAI,
          # Vector database
          InstrumentSet.PINECONE,
          # Framework
          InstrumentSet.LANGCHAIN,
      },
  )
  ```

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

  await Netra.init({
    appName: "rag-app",
    instruments: new Set([
      // LLM provider
      NetraInstrumentSet.OPENAI,
      // Vector database
      NetraInstrumentSet.PINECONE,
      // Framework
      NetraInstrumentSet.LANGCHAIN,
    ]),
  });
  ```
</CodeGroup>

### API Service

Instrument a FastAPI/Express service with database and LLM calls:

<CodeGroup>
  ```python Python theme={null}
  from netra import Netra
  from netra.instrumentation.instruments import InstrumentSet

  Netra.init(
      app_name="api-service",
      instruments={
          # Web framework
          InstrumentSet.FASTAPI,
          # LLM
          InstrumentSet.OPENAI,
          # Database
          InstrumentSet.SQLALCHEMY,
          InstrumentSet.REDIS,
      },
  )
  ```

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

  await Netra.init({
    appName: "api-service",
    instruments: new Set([
      // Web framework
      NetraInstrumentSet.EXPRESS,
      // LLM
      NetraInstrumentSet.OPENAI,
      // Database
      NetraInstrumentSet.POSTGRES,
      NetraInstrumentSet.REDIS,
    ]),
  });
  ```
</CodeGroup>

## Best Practices

1. **Start broad, then narrow** - Begin with default instrumentation (all libraries), then use `block_instruments` to remove noisy ones.
2. **Use `instruments` for minimal setups** - When you know exactly which libraries you need traced, use `instruments` for a cleaner configuration.
3. **Block HTTP for cleaner traces** - HTTP instrumentation can create many spans. Block it if you don't need to trace external API calls.
4. **Match your dependencies** - Only include instruments for libraries you actually use. Extra instruments have minimal overhead but can cause confusion.
5. **Document your choices** - Add comments explaining why certain instrumentations are enabled or blocked.

```python theme={null}
Netra.init(
    app_name="my-app",
    block_instruments={
        # Block HTTP to reduce noise - we only care about LLM calls
        InstrumentSet.HTTPX,
        InstrumentSet.REQUESTS,
    },
)
```

## Troubleshooting

### Instrumentation not working

1. **Check library installation order** - Initialize Netra before importing the library you want to instrument.
2. **Verify the instrument name** - Ensure you're using the correct enum value for your SDK version.
3. **Enable debug mode** - Use `debug_mode=True` to see which instrumentations are being loaded.

### Too many spans

1. **Block HTTP clients** - HTTP instrumentation often creates the most spans.
2. **Use `instruments`** - Switch from blocking to allowlisting for more control.
3. **Use `blocked_spans`** - Filter specific span names at export time (see [Initialization](/Observability/Traces/configuration/initialization)).

## Next Steps

* [Initialization](/Observability/Traces/configuration/initialization) - All configuration options
* [Environment Variables](/Observability/Traces/configuration/environment-variables) - Configure via environment
* [Custom Exporters](/Observability/Traces/configuration/custom-exporters) - Send traces to custom backends