Instrumentation Selection - What is Netra?

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).	`DEFAULT_INSTRUMENTS_FOR_ROOT`
`block_instruments`	These instrumentations are excluded from both `instruments` and `root_instruments` independently.	`None`

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.

The `ALL` Sentinel

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

Python

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:

from netra import Netra, NetraInstruments

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

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

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

Blocking Specific Instrumentations

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

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,
    },
)

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,
  ]),
});

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.

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,
    },
)

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,
  ]),
});

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.

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.

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:

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,
    },
)

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

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

Reduce HTTP Noise

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

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,
    },
)

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

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

RAG Application

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

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,
    },
)

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,
  ]),
});

API Service

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

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,
    },
)

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,
  ]),
});

Best Practices

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

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

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

Too many spans

Block HTTP clients - HTTP instrumentation often creates the most spans.
Use instruments - Switch from blocking to allowlisting for more control.
Use blocked_spans - Filter specific span names at export time (see Initialization).

Next Steps

Initialization - All configuration options
Environment Variables - Configure via environment
Custom Exporters - Send traces to custom backends

​How It Works

​The ALL Sentinel

​Enabling Specific Instrumentations

​Blocking Specific Instrumentations

​Controlling Root-Level Spans

​Available Instruments

​Python Instruments

​LLM Providers

​AI Frameworks

​Vector Databases

​HTTP Clients

​Web Frameworks

​Databases

​Message Queues

​TypeScript Instruments

​LLM Providers

​AI Frameworks

​Vector Databases

​HTTP Clients

​Web Frameworks

​Databases

​Message Queues

​Common Use Cases

​LLM-Only Tracing

​Reduce HTTP Noise

​RAG Application

​API Service

​Best Practices

​Troubleshooting

​Instrumentation not working

​Too many spans

​Next Steps

How It Works

The `ALL` Sentinel

Enabling Specific Instrumentations

Blocking Specific Instrumentations

Controlling Root-Level Spans

Available Instruments

Python Instruments

LLM Providers

AI Frameworks

Vector Databases

HTTP Clients

Web Frameworks

Databases

Message Queues

TypeScript Instruments

LLM Providers

AI Frameworks

Vector Databases

HTTP Clients

Web Frameworks

Databases

Message Queues

Common Use Cases

LLM-Only Tracing

Reduce HTTP Noise

RAG Application

API Service

Best Practices

Troubleshooting

Instrumentation not working

Too many spans

Next Steps