SDK Overview - What is Netra? | Technical documentation

Netra provides official SDKs for Python and TypeScript/JavaScript, enabling you to instrument your AI applications with minimal code changes.

Available SDKs

Python SDK

Full-featured SDK for Python applications with support for decorators, auto-instrumentation, and manual tracing.

TypeScript SDK

Native TypeScript/JavaScript SDK for Node.js applications with full type support.

Installation

pip install netra-sdk

Quick Start

Initialize the SDK at the start of your application:

from netra import Netra

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

Core Features

Both SDKs provide the same core functionality:

Feature	Description
Auto-Instrumentation	Automatic tracing for 50+ LLM providers, frameworks, and databases
Manual Tracing	Create custom spans with full control over attributes and events
Decorators	Simple function decoration for `@agent`, `@task`, and `@workflow`
Context Tracking	Set user, session, and tenant IDs for filtering and analysis
Usage Tracking	Record token usage, costs, and custom metrics

SDK Architecture

┌─────────────────────────────────────────────────────────┐
│                    Your Application                      │
├─────────────────────────────────────────────────────────┤
│                      Netra SDK                          │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐    │
│  │    Auto-     │ │   Manual     │ │  Decorators  │    │
│  │Instrumentation│ │   Tracing    │ │              │    │
│  └──────────────┘ └──────────────┘ └──────────────┘    │
│  ┌──────────────────────────────────────────────────┐  │
│  │              OpenTelemetry Core                   │  │
│  └──────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────┤
│                    OTLP Exporter                        │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
                    Netra Cloud /
                    Custom Backend

Main Classes

Netra (Static Class)

The main entry point for SDK operations:

Method	Description
`init()`	Initialize the SDK with configuration
`start_span()`	Create a new span for manual tracing
`get_current_span()`	Get the currently active span
`set_user_id()`	Set user context for traces
`set_session_id()`	Set session context for traces
`set_tenant_id()`	Set tenant context for traces
`set_custom_attributes()`	Add custom key-value attributes
`set_custom_event()`	Record a custom event
`shutdown()`	Gracefully shutdown the SDK

SpanWrapper

Returned by start_span(), provides methods to enrich spans:

Method	Description
`set_attribute()`	Add a custom attribute
`add_event()`	Record an event within the span
`set_prompt()`	Set the input prompt (for LLM spans)
`set_model()`	Set the model name
`set_usage()`	Record usage metrics
`set_action()`	Track actions/tool calls
`set_success()`	Mark span as successful
`set_error()`	Mark span as failed with error message
`end()`	End the span (TypeScript only)

Models

Model	Description
`UsageModel`	Token usage and cost tracking
`ActionModel`	Action/tool call tracking
`SpanType`	Enum for span categorization

Environment Variables

Configure the SDK via environment variables:

Variable	Description
`NETRA_API_KEY`	API key for authentication
`NETRA_APP_NAME`	Application name
`NETRA_ENV`	Environment (production, staging, etc.)
`NETRA_OTLP_ENDPOINT`	Custom OTLP endpoint URL
`NETRA_TRACE_CONTENT`	Enable/disable content tracing
`NETRA_DEBUG`	Enable debug logging

Next Steps

Python SDK Reference - Complete Python API reference
TypeScript SDK Reference - Complete TypeScript API reference
Auto-Instrumentation - Supported libraries
Manual Tracing - Creating custom spans
Decorators - Using decorators for tracing

SDK Reference

​Available SDKs

Python SDK

TypeScript SDK

​Installation

​Quick Start

​Core Features

​SDK Architecture

​Main Classes

​Netra (Static Class)

​SpanWrapper

​Models

​Environment Variables

​Next Steps