Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sidmanale643/northstar/llms.txt

Use this file to discover all available pages before exploring further.

northstar.auto_instrument() monkey-patches the OpenAI and Anthropic Python client libraries so that every LLM API call is captured as a model span inside the current NorthStar trace — without any changes to the call sites themselves. It must be called before northstar.init() and before any OpenAI or Anthropic client instances are created. Calling it after the libraries have already been imported and instantiated will still patch the class methods, but calling it first guarantees the patch is in place before any client object is used.
auto_instrument() patches class-level methods (Completions.create, AsyncCompletions.create, Responses.create, AsyncResponses.create, Messages.create, AsyncMessages.create). The patch is applied once per process and is idempotent.

​
Quick Start

1

Install NorthStar

uv add northstar-ai
For USD cost tracking, install the optional pricing extra:
uv add 'northstar-ai[pricing]'
2

Set credentials

export NORTHSTAR_API_KEY="ns_..."
export NORTHSTAR_PROJECT_ID="<supabase-project-ref>"
3

Call auto_instrument() before init()

import northstar

northstar.auto_instrument()   # patch FIRST
northstar.init(
    api_key=os.environ["NORTHSTAR_API_KEY"],
    project_id=os.environ["NORTHSTAR_PROJECT_ID"],
    project="Support Agent",
    environment="production",
)

​
Anthropic Example

The example below mirrors the NorthStar quick-start. A single client.messages.create() call is automatically captured as a model span with all messages, token usage, and cost. 
import os

import anthropic
import northstar

northstar.auto_instrument()  # instruments openai + anthropic
northstar.init(
    api_key=os.environ["NORTHSTAR_API_KEY"],
    project_id=os.environ["NORTHSTAR_PROJECT_ID"],
    project="Support Agent",
    environment="production",
)

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[{"role": "user", "content": "How do I reset my password?"}],
)
northstar.flush()

​
OpenAI Example

Auto-instrumentation covers both the Chat Completions API and the newer Responses API, including their async variants. 
import os

import openai
import northstar

northstar.auto_instrument()
northstar.init(
    api_key=os.environ["NORTHSTAR_API_KEY"],
    project_id=os.environ["NORTHSTAR_PROJECT_ID"],
    project="Support Agent",
    environment="production",
)

client = openai.OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarise this article for me."}],
)
northstar.flush()

​
What Is Captured

Every instrumented call records the following data automatically:
FieldDetails
Request messagesThe full messages array passed to the API, including system prompts
Tools / tool_choiceTool schemas and any tool_choice constraint
Model-emitted tool callsTool call objects in the assistant message
Tool result messagesrole: "tool" messages included in subsequent LLM requests
Output messageThe first choice’s message (Chat Completions) or output_text (Responses API)
Token usageinput_tokens, output_tokens, total_tokens stored on the span’s attributes
USD costComputed via litellm pricing and stored as cost_usd on the span
LatencyWall-clock time from request to response, stored as latency_ms
ExceptionsAny exception raised by the API call is recorded and the span is marked ERROR
Local tool execution is not traced automatically. The instrumentation only captures what passes through the LLM API boundary. If you want to trace the execution of your own tool functions, wrap them with @northstar.observe or a with northstar.span(...) block.

​
USD Cost Tracking

Cost computation requires the litellm package, which is bundled in the pricing extra: 
uv add 'northstar-ai[pricing]'
Without this extra, token counts are still recorded but cost_usd will be absent from span attributes. The pricing_source attribute on the span will be "litellm" when pricing succeeds or "unknown" when the model is not found in litellm’s price list.
Set debug=True in northstar.init() to print a confirmation message to stderr each time auto-instrumentation patches a method. This is useful for verifying the patch is applied before your first API call.

​
Covered Endpoints

LibraryPatched methodSyncAsync
openaichat.completions.create✓✓
openairesponses.create✓✓
anthropicmessages.create✓✓
If the openai or anthropic package is not installed, the corresponding patch is silently skipped — no error is raised.

Build docs developers (and LLMs) love

Get started for freeTalk to us