Netra Custom Spans And Actions

Use this skill when auto/decorator tracing is not enough and you need explicit span lifecycle control.

When To Use

You need spans around external APIs, tool calls, or batch steps.
You need usage/cost tracking per operation.
You need structured action records for DB/API side effects.

Procedure

Wrap each critical operation in Netra.start_span(...).
Set span attributes (model, llm_system, operation keys).
Attach usage via UsageModel.
Attach actions via ActionModel.
Add events for checkpoints and failures.

Python Pattern

from netra import Netra, UsageModel, ActionModel


def process_item(item_id: str):
    with Netra.start_span("process_item") as span:
        span.set_attribute("item.id", item_id)
        span.set_model("gpt-4o")
        span.set_llm_system("openai")

        usage = [
            UsageModel(
                model="gpt-4o",
                usage_type="generation",
                units_used=1,
                cost_in_usd=0.01,
            )
        ]
        span.set_usage(usage)

        action = ActionModel(
            action="DB",
            action_type="UPDATE",
            metadata={"table": "items"},
            success=True,
        )
        span.set_action([action])

        span.add_event("item.processed", {"item_id": item_id})

TypeScript Pattern

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

async function processItem(itemId: string): Promise<void> {
    const span = Netra.startSpan(
        "process_item",
        { attributes: { "item.id": itemId }, moduleName: "items" },
        undefined,
        SpanType.TOOL
    );

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

    try {
        span.setUsage([
            {
                model: "gpt-4o",
                usageType: "generation",
                unitsUsed: 1,
                costInUsd: 0.01,
            },
        ]);

        span.setAction([
            {
                action: "DB",
                actionType: "UPDATE",
                metadata: { table: "items" },
                success: true,
            },
        ]);

        span.addEvent("item.processed", { itemId });
        span.setSuccess();
    } catch (error: any) {
        span.setError(error.message || "process_item failed");
        throw error;
    } finally {
        span.end();
    }
}

Checklist

Each custom span maps to a meaningful business boundary.
Usage and cost fields are populated for paid model calls.
Action records capture side effects with success/failure state.
Spans always close cleanly on exceptions.

netra-custom-spans-and-actions

Netra Custom Spans And Actions

When To Use

Procedure

Python Pattern

TypeScript Pattern

Checklist

References