Tracing

Capture spans and events across LLMs, tools, chains, and retrievers.

Njira Tracing provides end-to-end observability for your AI agents, capturing every LLM call, tool invocation, and chain execution.

What Gets Captured

The core SDK provides a span API. Framework adapters (LangChain, CrewAI, etc.) automatically map framework events into structured spans:

Span Type Description Example
llm LLM API calls Chat completions, embeddings
tool Tool/function calls Web search, database queries
chain Agent chains/workflows Multi-step reasoning
retriever Vector/document retrieval RAG pipelines
custom User-defined spans Custom business logic

Creating Spans

TypeScript

const spanId = njira.trace.startSpan({
  name: "llm-call",
  type: "llm",
  input: { prompt },
  tags: { model: "gpt-5.2" },
});

try {
  const output = await callLLM(prompt);
  njira.trace.endSpan(spanId, { output, metrics: { tokens: 150 } });
} catch (err) {
  njira.trace.error(spanId, err as Error);
  throw err;
}

Python

span_id = njira.start_span(
    name="llm-call",
    span_type="llm",
    input_data={"prompt": prompt},
    tags={"model": "gpt-5.2"},
)

try:
    output = await call_llm(prompt)
    njira.end_span(span_id, output=output, metrics={"tokens": 150})
except Exception as e:
    njira.span_error(span_id, e)
    raise

Custom Events

Use events for key milestones and debug breadcrumbs that don't warrant a full span:

njira.trace.event("policy_decision", { 
  verdict: "allow", 
  policy: "payments_guard",
  latency_ms: 12 
});

Common use cases:

  • Policy evaluation results
  • Tool routing decisions
  • User-visible "why was this blocked?" correlations
  • Checkpoint markers in long-running chains

Adding Metrics

Attach numeric metrics to spans for dashboards and analysis:

njira.trace.endSpan(spanId, {
  output: result,
  metrics: {
    latency_ms: 245,
    input_tokens: 100,
    output_tokens: 50,
    cost_usd: 0.0015
  }
});

Viewing Traces in Console

Navigate to the Traces tab in the Njira Console to:

  1. Search by request ID, user ID, or time range.
  2. Drill down into individual traces to see the full span tree.
  3. Inspect inputs, outputs, and enforcement verdicts for each span.
  4. Replay a trace to simulate policy changes (if enabled).

Best Practices

  • Always close spans: Use try/finally to ensure endSpan or error is called.
  • Use meaningful names: Span names like search_products are more useful than tool-1.
  • Tag liberally: Add user_id, session_id, environment for easier filtering.
  • Keep inputs/outputs reasonable: Truncate large payloads to avoid storage bloat.