TypeScript 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 span type and attributes
const genSpan = Netra.startSpan("generate-response", { attributes: { model: "gpt-4" }, moduleName: "chat" }, undefined, SpanType.GENERATION);

Netra.setSessionId("session-abc123");

Netra.setUserId("user-456");

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

Netra.setCustomAttributes({ key: "customer_tier", value: "premium" });
Netra.setCustomAttributes({ key: "region", value: "us-east" });

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

await Netra.shutdown();

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();