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

# Portkey to Netra

> Migrate from Portkey to Netra for AI observability. A step-by-step guide covering SDK integration, tracing, OpenTelemetry, and gateway feature mapping.

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](https://docs.getnetra.ai/sdk-reference/sdk/python) and [TypeScript](https://docs.getnetra.ai/sdk-reference/sdk/typescript) to instrument application code directly, plus native [integrations across 50+ frameworks and model providers](https://docs.getnetra.ai/Integrations/overview) including OpenAI, LangChain, LlamaIndex, Anthropic, and more. See the full [integrations overview](https://docs.getnetra.ai/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:

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

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

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

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

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

<CodeGroup>
  ```python Python theme={null}
  # 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!"}],
  )
  ```

  ```typescript TypeScript theme={null}
  // 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!" }],
  });
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python theme={null}
  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!"}],
  )
  ```

  ```typescript TypeScript theme={null}
  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!" }],
  });
  ```
</CodeGroup>

Beyond gateway logging, Netra also supports application-level tracing via decorators in [Python](https://docs.getnetra.ai/sdk-reference/sdk/python#decorators) and equivalent patterns in [TypeScript](https://docs.getnetra.ai/sdk-reference/sdk/typescript#decorators). 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](https://portkey.ai/docs/product/observability/opentelemetry) — 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:

```bash theme={null}
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](https://docs.litellm.ai/docs/simple_proxy) and continue sending traces to Netra. LiteLLM supports the same gateway capabilities: fallback chains, load balancing, retries, and caching across 100+ LLM providers.

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

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

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

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

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

<CodeGroup>
  ```python Python theme={null}
  # 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!"}],
  )
  ```

  ```typescript TypeScript theme={null}
  // 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!" }],
  });
  ```
</CodeGroup>

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**:

<CodeGroup>
  ```python Python theme={null}
  # 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"}
  )
  ```

  ```typescript TypeScript theme={null}
  // 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",
  });
  ```
</CodeGroup>

See the [manual tracing guide](/Observability/Traces/manual-tracing) and [decorators guide](https://docs.getnetra.ai/Observability/Traces/decorators) 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](https://docs.litellm.ai/docs/simple_proxy)**: Supports fallbacks, load balancing, retries, and caching across 100+ providers. See [Option C](#option-c-replace-the-gateway-with-litellm-proxy) 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](https://docs.litellm.ai/docs/proxy/configs).
* 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:

<CardGroup cols={2}>
  <Card icon="flask" href="/Simulation/Simulation-overview" title="Run Simulations">
    Test your agents with realistic, multi-turn conversations using configurable personas and goals.
  </Card>

  <Card icon="clipboard-check" href="/Evaluation/Evaluation-overview" title="Run Evaluations">
    Measure quality, accuracy, and reliability with LLM-as-Judge and code evaluators.
  </Card>

  <Card icon="chart-line" href="/Dashboard/Custom-dashboard" title="Set Up Custom Dashboards">
    Build your own views to track traces, costs, and agent behavior across projects.
  </Card>

  <Card icon="bell" href="/quick-start/QuickStart_Alerts" title="Configure Alerts">
    Get notified about anomalies, cost spikes, and performance issues.
  </Card>
</CardGroup>

***