Skip to main content
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:
ParameterBehaviorDefault
instrumentsSet of libraries to instruments. When provided, only these instrumentations are enabled.DEFAULT_INSTRUMENTS
root_instrumentsSet of libraries allowed to produce root-level spans. When a root span is blocked, its entire subtree is discarded.DEFAULT_INSTRUMENTS_FOR_ROOT
block_instrumentsThese 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,
    },
)

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

​
Controlling Root-Level Spans

Use root_instruments to control which libraries can produce root-level spans.
Python
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,
    },
)
When a root span is blocked by root_instruments, its entire subtree is discarded. This means all child spans under that root are also dropped, even if they belong to an allowed instrumentation. Use this to filter out noisy top-level traces from HTTP clients or database drivers.

​
Available Instruments

​
Python Instruments

​
LLM Providers

InstrumentDescription
InstrumentSet.OPENAIOpenAI API calls
InstrumentSet.ANTHROPICAnthropic Claude API
InstrumentSet.COHERECohere API
InstrumentSet.GOOGLE_GENERATIVEAIGoogle Generative AI
InstrumentSet.MISTRALAIMistral AI API
InstrumentSet.GROQGroq API
InstrumentSet.BEDROCKAWS Bedrock
InstrumentSet.VERTEXAIGoogle Vertex AI
InstrumentSet.OLLAMAOllama local models
InstrumentSet.REPLICATEReplicate API
InstrumentSet.TOGETHERTogether AI
InstrumentSet.TRANSFORMERSHugging Face Transformers
InstrumentSet.LITELLMLiteLLM unified interface

​
AI Frameworks

InstrumentDescription
InstrumentSet.LANGCHAINLangChain framework
InstrumentSet.LANGGRAPHLangGraph workflows
InstrumentSet.LLAMAINDEXLlamaIndex framework
InstrumentSet.HAYSTACKHaystack framework
InstrumentSet.CREWAICrewAI agents
InstrumentSet.DSPYDSPy framework
InstrumentSet.PYDANTIC_AIPydantic AI

​
Vector Databases

InstrumentDescription
InstrumentSet.PINECONEPinecone vector database
InstrumentSet.WEAVIATEWeaviate vector database
InstrumentSet.QDRANTQdrant vector database
InstrumentSet.CHROMADBChromaDB vector database
InstrumentSet.MILVUSMilvus vector database
InstrumentSet.LANCEDBLanceDB vector database
InstrumentSet.MARQOMarqo vector database

​
HTTP Clients

InstrumentDescription
InstrumentSet.HTTPXHTTPX async client
InstrumentSet.AIOHTTPAIOHTTP async client
InstrumentSet.REQUESTSRequests library
InstrumentSet.URLLIBurllib library
InstrumentSet.URLLIB3urllib3 library

​
Web Frameworks

InstrumentDescription
InstrumentSet.FASTAPIFastAPI framework
InstrumentSet.FLASKFlask framework
InstrumentSet.DJANGODjango framework
InstrumentSet.STARLETTEStarlette framework
InstrumentSet.TORNADOTornado framework
InstrumentSet.FALCONFalcon framework

​
Databases

InstrumentDescription
InstrumentSet.SQLALCHEMYSQLAlchemy ORM
InstrumentSet.SQLITE3SQLite3
InstrumentSet.PSYCOPGPostgreSQL (psycopg)
InstrumentSet.PSYCOPG2PostgreSQL (psycopg2)
InstrumentSet.PYMYSQLMySQL
InstrumentSet.PYMONGOMongoDB
InstrumentSet.REDISRedis
InstrumentSet.ELASTICSEARCHElasticsearch

​
Message Queues

InstrumentDescription
InstrumentSet.CELERYCelery task queue
InstrumentSet.PIKARabbitMQ (pika)
InstrumentSet.AIO_PIKARabbitMQ (aio-pika)
InstrumentSet.KAFKA_PYTHONKafka
InstrumentSet.CONFLUENT_KAFKAConfluent Kafka

​
TypeScript Instruments

​
LLM Providers

InstrumentDescription
NetraInstrumentSet.OPENAIOpenAI API calls
NetraInstrumentSet.GOOGLE_GENAIGoogle Generative AI
NetraInstrumentSet.MISTRALMistral AI API
NetraInstrumentSet.GROQGroq API
NetraInstrumentSet.VERTEX_AIGoogle Vertex AI
NetraInstrumentSet.TOGETHERTogether AI

​
AI Frameworks

InstrumentDescription
NetraInstrumentSet.LANGCHAINLangChain framework
NetraInstrumentSet.LANGGRAPHLangGraph workflows
NetraInstrumentSet.LLAMAINDEXLlamaIndex framework

​
Vector Databases

InstrumentDescription
NetraInstrumentSet.PINECONEPinecone vector database
NetraInstrumentSet.QDRANTQdrant vector database
NetraInstrumentSet.CHROMADBChromaDB vector database

​
HTTP Clients

InstrumentDescription
NetraInstrumentSet.HTTPNode.js HTTP module
NetraInstrumentSet.HTTPSNode.js HTTPS module
NetraInstrumentSet.FETCHFetch API

​
Web Frameworks

InstrumentDescription
NetraInstrumentSet.EXPRESSExpress.js framework
NetraInstrumentSet.FASTIFYFastify framework
NetraInstrumentSet.NESTJSNestJS framework

​
Databases

InstrumentDescription
NetraInstrumentSet.PRISMAPrisma ORM
NetraInstrumentSet.TYPEORMTypeORM
NetraInstrumentSet.MONGODBMongoDB
NetraInstrumentSet.POSTGRESPostgreSQL
NetraInstrumentSet.MYSQLMySQL
NetraInstrumentSet.REDISRedis

​
Message Queues

InstrumentDescription
NetraInstrumentSet.KAFKAKafka
NetraInstrumentSet.RABBITMQRabbitMQ

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

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

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

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

​
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.
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).

​
Next Steps

Last modified on May 14, 2026