Overview

import { Netra } from "netra-sdk";

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

await Netra.init({
  appName: "my-ai-app",
  headers: `x-api-key=${process.env.NETRA_API_KEY}`,
  environment: "production",
  traceContent: true,
  instruments: new Set([NetraInstruments.OPENAI, NetraInstruments.LANGCHAIN]),
});

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

// Basic usage
const span = Netra.startSpan("process-document");
try {
  const result = await processDocument(doc);
  span.setAttribute("pages", result.pageCount);
  span.setSuccess();
} catch (error) {
  span.setError(error.message);
  throw error;
} finally {
  span.end();
}

// With options
const genSpan = Netra.startSpan("generate-response", {
  attributes: { model: "gpt-4" },
  moduleName: "chat",
  asType: SpanType.GENERATION,
});

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

// Basic usage — span auto-ends when the callback resolves
const result = await Netra.startActiveSpan("handle-request", async (span) => {
  span.setAttribute("endpoint", "/api/chat");
  const response = await processRequest();
  span.setSuccess();
  return response;
});

// With options
const result = await Netra.startActiveSpan(
  "generate-response",
  {
    attributes: { model: "gpt-4" },
    moduleName: "chat",
    asType: SpanType.GENERATION,
  },
  async (span) => {
    const response = await llm.generate(prompt);
    span.setSuccess();
    return response;
  },
);

Netra.startActiveSpan<T>(name: string, fn: (span: SpanWrapper) => T): T;
Netra.startActiveSpan<T>(name: string, options: SpanOptions, fn: (span: SpanWrapper) => T): T;

const traceId = Netra.getTraceId();
if (traceId) {
  console.log(`Current trace: ${traceId}`);
}

await Netra.init({
  appName: "my-app",
  enableRootSpan: true,
});

await Netra.runWithRootSpan(async () => {
  // All spans created here are parented under the root span
  const span = Netra.startSpan("child-operation");
  await doWork();
  span.end();
});

import { Netra } from "netra-sdk";

// Block all HTTP spans within this scope
const result = await Netra.withBlockedSpansLocal(
  ["http.*", "*.resolve"],
  async () => {
    // HTTP spans created inside here are filtered out
    const data = await fetch("https://api.example.com/data");
    return data.json();
  },
);

Netra.withBlockedSpansLocal<T>(patterns: readonly string[], fn: () => Promise<T>): Promise<T>;
Netra.withBlockedSpansLocal<T>(patterns: readonly string[], fn: () => T): T;

Netra.setSessionId("session-abc123");

Netra.setUserId("user-456");

Netra.setTenantId("tenant-org-789");

Netra.setCustomAttributes("customer_tier", "premium");
Netra.setCustomAttributes("region", "us-east");

Netra.setCustomEvent("user_feedback", {
  rating: 5,
  comment: "Great response!",
  category: "positive",
});

Netra.setInput("What is the capital of France?");
Netra.setInput({ query: "capital of France", language: "en" });

Netra.setOutput("The capital of France is Paris.");
Netra.setOutput({ answer: "Paris", confidence: 0.98 });

Netra.setRootInput("Summarize this document");

Netra.setRootOutput("The document discusses three main topics...");

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

Netra.addConversation(ConversationType.INPUT, "user", "What is the weather today?");
Netra.addConversation(ConversationType.OUTPUT, "assistant", "It's sunny and 72°F.");

// Content can also be an object
Netra.addConversation(ConversationType.INPUT, "user", {
  text: "Show me a chart",
  attachments: ["data.csv"],
});

span.setAttribute("query", userQuery);
span.setAttribute("results.count", results.length);

span.addEvent("validation-started");
span.addEvent("validation-completed", { valid: true, errors: 0 });

span.setPrompt("Summarize this article: ...");

span.setNegativePrompt("blurry, low quality, distorted");

span.setModel("gpt-4-turbo");

span.setLlmSystem("openai");

span.setUsage([
  {
    model: "gpt-4",
    costInUsd: 0.006,
    usageType: "chat",
    unitsUsed: 1,
  },
]);

span.setAction([
  {
    action: "DB",
    actionType: "INSERT",
    affectedRecords: [{ recordId: "123", recordType: "user" }],
    metadata: { table: "users" },
    success: true,
  },
]);

span.setSuccess();

span.setError("Failed to connect to database");

span.end();

import { SpanType } from "netra-sdk";

SpanType.SPAN;       // General operations (default)
SpanType.GENERATION; // LLM completions, image generation
SpanType.EMBEDDING;  // Vector embedding operations
SpanType.TOOL;       // Function calls, API requests
SpanType.AGENT;      // AI agent operations

interface UsageModel {
  model: string;
  costInUsd?: number;
  usageType?: string;
  unitsUsed?: number;
}

const usage: UsageModel = {
  model: "gpt-4",
  costInUsd: 0.0045,
  usageType: "chat",
  unitsUsed: 1,
};

interface ActionModel {
  action: string;
  actionType: string;
  affectedRecords?: Array<{
    recordId: string;
    recordType: string;
  }>;
  metadata?: Record<string, string>;
  success: boolean;
}

const action: ActionModel = {
  action: "API",
  actionType: "CALL",
  affectedRecords: [{ recordId: "order-123", recordType: "order" }],
  metadata: {
    endpoint: "/api/orders",
    method: "POST",
    statusCode: "201",
  },
  success: true,
};

import { agent } from "netra-sdk/decorators";

@agent
async function researchAgent(query: string) {
  return await performResearch(query);
}

@agent({ name: "customer-support" })
async function supportAgent(request: Request) {
  return await handleRequest(request);
}

import { task } from "netra-sdk/decorators";

@task
async function fetchData(query: string) {
  return await database.query(query);
}

@task({ name: "web-search" })
async function searchWeb(query: string) {
  return await searchApi.search(query);
}

import { workflow } from "netra-sdk/decorators";

@workflow
async function processOrder(order: Order) {
  await validateOrder(order);
  await processPayment(order);
  await fulfillOrder(order);
}

import { NetraInstruments } from "netra-sdk";

// LLM Providers
NetraInstruments.OPENAI;
NetraInstruments.GOOGLE_GENAI;
NetraInstruments.MISTRAL;
NetraInstruments.GROQ;
NetraInstruments.VERTEX_AI;
NetraInstruments.TOGETHER;

// AI Frameworks
NetraInstruments.LANGCHAIN;
NetraInstruments.LANGGRAPH;
NetraInstruments.LLAMAINDEX;

// Vector Databases
NetraInstruments.PINECONE;
NetraInstruments.QDRANT;
NetraInstruments.CHROMADB;

// HTTP Clients
NetraInstruments.HTTP;
NetraInstruments.HTTPS;
NetraInstruments.FETCH;

// Web Frameworks
NetraInstruments.EXPRESS;
NetraInstruments.FASTIFY;
NetraInstruments.NESTJS;

// Databases
NetraInstruments.PRISMA;
NetraInstruments.TYPEORM;
NetraInstruments.MONGODB;
NetraInstruments.POSTGRES;
NetraInstruments.MYSQL;
NetraInstruments.REDIS;

// Message Queues
NetraInstruments.KAFKA;
NetraInstruments.RABBITMQ;

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

// Initialize SDK (must await to ensure instrumentations are ready)
await Netra.init({
  appName: "my-ai-app",
  headers: `x-api-key=${process.env.NETRA_API_KEY}`,
  environment: "production",
  instruments: new Set([NetraInstruments.OPENAI]),
});

// Set context
Netra.setUserId("user-123");
Netra.setSessionId("session-abc");

// Create a traced operation
async function chatWithAI(userMessage: string): Promise<string> {
  const span = Netra.startSpan("chat-completion", {}, undefined, SpanType.GENERATION);

  span.setPrompt(userMessage);
  span.setModel("gpt-4");
  span.setLlmSystem("openai");

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

    // Calculate cost based on token usage
    const promptCost = ((response.usage?.prompt_tokens || 0) / 1000) * 0.03;
    const completionCost = ((response.usage?.completion_tokens || 0) / 1000) * 0.06;
    const totalCost = promptCost + completionCost;

    span.setUsage([
      {
        model: "gpt-4",
        costInUsd: totalCost,
        usageType: "chat",
        unitsUsed: 1,
      },
    ]);

    span.setSuccess();
    return response.choices[0].message.content || "";
  } catch (error: any) {
    span.setError(error.message);
    throw error;
  } finally {
    span.end();
  }
}

// Use the function
const result = await chatWithAI("What is the capital of France?");
console.log(result);

// Shutdown gracefully
await Netra.shutdown();

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

async function main() {
  // Initialize before creating the app (must await)
  await Netra.init({
    appName: "my-api",
    headers: `x-api-key=${process.env.NETRA_API_KEY}`,
    instruments: new Set([NetraInstruments.EXPRESS, NetraInstruments.OPENAI]),
  });

  const app = express();

  // Middleware to set user context
  app.use((req, res, next) => {
    if (req.headers["x-user-id"]) {
      Netra.setUserId(req.headers["x-user-id"] as string);
    }
    if (req.headers["x-session-id"]) {
      Netra.setSessionId(req.headers["x-session-id"] as string);
    }
    next();
  });

  app.post("/api/chat", async (req, res) => {
    const span = Netra.startSpan("handle-chat-request");

    try {
      const { message } = req.body;
      span.setAttribute("input.length", message.length);

      const response = await processMessage(message);

      span.setSuccess();
      res.json({ response });
    } catch (error: any) {
      span.setError(error.message);
      res.status(500).json({ error: error.message });
    } finally {
      span.end();
    }
  });

  // Graceful shutdown
  process.on("SIGTERM", async () => {
    await Netra.shutdown();
    process.exit(0);
  });

  app.listen(3000);
}

main();