Portkey to Netra

If you’re looking to move away from Portkey — whether due to reliability concerns, pricing, or simply wanting deeper application-level observability — this guide walks through how to transition your tracing, observability, and gateway features from Portkey to Netra.

Migrating Tracing / Observability

Portkey captures LLM traffic at its gateway and groups related requests (retries, fallbacks) into traces using a trace ID header. Netra takes a different approach: it instruments your application code directly, producing hierarchical traces with nested spans that cover complete multi-step agent workflows — not just the gateway hops.

Option A: Use the Netra SDK (Recommended)

Netra ships official SDKs for Python and TypeScript to instrument application code directly, plus native integrations across 50+ frameworks and model providers including OpenAI, LangChain, LlamaIndex, Anthropic, and more. See the full integrations overview to pick the integration that matches your stack. If you’re using the Portkey SDK (portkey-ai), the migration starts by initializing Netra before your LLM calls. You can keep Portkey’s gateway running during the transition so your existing routing and fallback logic stays intact while Netra begins capturing traces:

from netra import Netra

# Initialize before importing other libraries for best results
Netra.init(app_name="my-ai-app", environment="production")

import { Netra } from "netra-sdk";

// Initialize before importing other libraries for best results
await Netra.init({
  appName: "my-ai-app",
  environment: "production",
});

Then switch from the Portkey SDK to the standard OpenAI SDK. You can keep Portkey’s gateway URL during the transition:

# Before (Portkey SDK)
# from portkey_ai import Portkey
# client = Portkey(api_key="PORTKEY_API_KEY", virtual_key="VIRTUAL_KEY")

# After (OpenAI SDK + Netra instrumentation)
from openai import OpenAI

client = OpenAI(
    base_url="https://api.portkey.ai/v1",  # Keep Portkey gateway during transition
    api_key="<your_api_key>",
    default_headers={"x-portkey-api-key": "<your_portkey_api_key>"}
)
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
)

// Before (Portkey SDK)
// import Portkey from "portkey-ai";
// const client = new Portkey({ apiKey: "PORTKEY_API_KEY", virtualKey: "VIRTUAL_KEY" });

// After (OpenAI SDK + Netra instrumentation)
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.portkey.ai/v1", // Keep Portkey gateway during transition
  apiKey: "<your_api_key>",
  defaultHeaders: { "x-portkey-api-key": "<your_portkey_api_key>" },
});

const response = await client.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello!" }],
});

Once you’ve verified traces are flowing into Netra, remove the Portkey gateway URL and point directly at your LLM provider:

from openai import OpenAI

client = OpenAI(api_key="<your_openai_api_key>")
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<your_openai_api_key>",
});

const response = await client.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello!" }],
});

Beyond gateway logging, Netra also supports application-level tracing via decorators in Python and equivalent patterns in TypeScript. This creates hierarchical traces with nested spans for multi-step workflows (tool calls, retrieval, post-processing, and more), giving you full execution context that a gateway alone can’t provide.

Option B: Use OpenTelemetry

If you already have OpenTelemetry in place — or if you were using Portkey’s OpenTelemetry integration — you don’t need to re-instrument. Point your OTLP exporter at Netra and keep your existing spans and context propagation. Configure your exporter using Netra’s OTLP endpoint:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.eu.getnetra.ai/telemetry"
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your_netra_api_key>"

If you were passing W3C Trace Context headers (traceparent, baggage) through Portkey, those same headers work with Netra’s OpenTelemetry backend.

Option C: Replace the Gateway with LiteLLM Proxy

If you relied on Portkey primarily as an AI gateway — provider routing, fallbacks, load balancing, retries, or caching — you can replace it with LiteLLM Proxy and continue sending traces to Netra. LiteLLM supports the same gateway capabilities: fallback chains, load balancing, retries, and caching across 100+ LLM providers.

from netra import Netra

# Initialize before importing other libraries for best results
Netra.init(app_name="my-ai-app", environment="production")

import { Netra } from "netra-sdk";

// Initialize before importing other libraries for best results
await Netra.init({
  appName: "my-ai-app",
  environment: "production",
});

Then keep your OpenAI client code the same — just point it at your LiteLLM proxy instead of Portkey:

# Your existing code works unchanged
from openai import OpenAI

client = OpenAI(
    base_url="<your_litellm_url>",  # Replace Portkey gateway URL with LiteLLM
    api_key="<your_api_key>"
)
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
)

// Your existing code works unchanged
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "<your_litellm_url>", // Replace Portkey gateway URL with LiteLLM
  apiKey: "<your_api_key>",
});

const response = await client.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello!" }],
});

This preserves the gateway pattern while routing your tracing data into Netra.

Migrating Portkey-Specific Features

Portkey bundles several gateway-level features beyond basic tracing. Here’s how each maps to Netra or an alternative:

Custom Metadata and Tags

Portkey lets you attach custom metadata to requests via the x-portkey-metadata header or SDK parameters for filtering and grouping in the dashboard. In Netra, you achieve the same using session attributes and decorators:

# Before (Portkey custom metadata)
# response = portkey.chat.completions.create(
#     model="gpt-4",
#     messages=[...],
#     metadata={"user_id": "u-123", "environment": "production", "team": "support"}
# )

# After (Netra session attributes and decorators)
from netra import Netra

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

# Use sessions to group related traces with custom attributes
session = Netra.create_session(
    session_id="session-abc",
    user_id="u-123",
    metadata={"team": "support"}
)

// Before (Portkey custom metadata)
// const response = await portkey.chat.completions.create({
//   model: "gpt-4",
//   messages: [...],
//   metadata: { user_id: "u-123", environment: "production", team: "support" }
// });

// After (Netra session attributes and decorators)
import { Netra } from "netra-sdk";

await Netra.init({
  appName: "my-ai-app",
  environment: "production",
});

See the manual tracing guide and decorators guide for details.

Caching, Routing, and Fallbacks

Portkey’s gateway offers simple and semantic caching, provider fallbacks, load balancing, retries, and conditional routing via Config objects. Netra focuses on observability rather than gateway routing, so for these capabilities:

LiteLLM Proxy: Supports fallbacks, load balancing, retries, and caching across 100+ providers. See Option C above.

You can run LiteLLM Proxy alongside Netra to get both routing and observability.

Virtual Keys and Model Catalog

Portkey’s Virtual Keys (now Model Catalog) store provider API keys server-side so your application only needs a Portkey API key. When moving to Netra, you’ll manage provider keys directly:

Store provider API keys (OpenAI, Anthropic, etc.) in your environment variables or secrets manager.
If using LiteLLM Proxy, configure provider keys in the LiteLLM config.
Netra does not require or store your LLM provider credentials — it only needs its own API key for sending telemetry data.

What’s next?

Once your tracing is set up, you’re ready to explore the rest of Netra. Pick what matters most to your team:

Run Simulations

Test your agents with realistic, multi-turn conversations using configurable personas and goals.

Run Evaluations

Measure quality, accuracy, and reliability with LLM-as-Judge and code evaluators.

Set Up Custom Dashboards

Build your own views to track traces, costs, and agent behavior across projects.

Configure Alerts

Get notified about anomalies, cost spikes, and performance issues.

Get Started

Observability

Insights

Evaluation

Simulation

Prompt Management

Monitoring & Dashboard

Account settings

Migrations

Migrating Tracing / Observability

Option A: Use the Netra SDK (Recommended)

Option B: Use OpenTelemetry

Option C: Replace the Gateway with LiteLLM Proxy

Migrating Portkey-Specific Features

Custom Metadata and Tags

Caching, Routing, and Fallbacks

Virtual Keys and Model Catalog

What’s next?

Run Simulations

Run Evaluations

Set Up Custom Dashboards

Configure Alerts

​Migrating Tracing / Observability

​Option A: Use the Netra SDK (Recommended)

​Option B: Use OpenTelemetry

​Option C: Replace the Gateway with LiteLLM Proxy

​Migrating Portkey-Specific Features

​Custom Metadata and Tags

​Caching, Routing, and Fallbacks

​Virtual Keys and Model Catalog

​What’s next?

Run Simulations

Run Evaluations

Set Up Custom Dashboards

Configure Alerts

Migrating Tracing / Observability

Option A: Use the Netra SDK (Recommended)

Option B: Use OpenTelemetry

Option C: Replace the Gateway with LiteLLM Proxy

Migrating Portkey-Specific Features

Custom Metadata and Tags

Caching, Routing, and Fallbacks

Virtual Keys and Model Catalog

What’s next?