nightgaze 0.1.0

Observability for AI agents — trace agents, tools, MCP and LLM calls with token usage, cost and latency

NightGaze

Observability for AI agents. Trace your agents, tools, MCP and LLM calls with two lines of code — and see every step, token, and millisecond of your agent workflows.

Installation

pip install nightgaze

Quick start

import nightgaze

nightgaze.init(
    api_key="al_live_...",               # from your NightGaze project settings
    base_url="https://your-nightgaze-host.com",
)

@nightgaze.agent("planner")
def plan_trip(query: str) -> str:
    hotels = search_hotels(query)
    return summarize(hotels)

@nightgaze.tool("search_hotels")
def search_hotels(query: str) -> list:
    ...

That's it. The outermost call becomes a trace; everything inside it — nested functions, LLM calls, tool calls — becomes a child span with timing, token usage, and error capture. Works with sync, async, and generator functions.

Trace your LLM calls automatically

nightgaze.instrument_openai()      # Chat Completions + Responses API
nightgaze.instrument_anthropic()   # Messages API
nightgaze.instrument_gemini()      # Google Gemini (google-genai)

Every request is captured with model, token usage, latency, and time-to-first-token for streaming — no changes to your calling code.

Framework integrations

nightgaze.instrument_langchain()    # chains, LLMs, tools, retrievers
nightgaze.instrument_langgraph()    # graphs with named node spans
nightgaze.instrument_llamaindex()   # queries, retrieval, synthesis

Decorators and manual spans

@nightgaze.agent("researcher")      # agent step
@nightgaze.tool("web_search")       # tool call
@nightgaze.trace("checkout")        # explicit workflow root
@nightgaze.mcp("fetch_docs")        # MCP tool call
@nightgaze.span                     # generic span

# or as a context manager, with custom attributes:
with nightgaze.span_context("rerank", kind="tool") as span:
    results = rerank(docs)
    span.add_metadata(doc_count=len(results))

Attribute traces to your users

nightgaze.identify(user_id="u_123", session_id="sess_9", customer_id="acme")

Every event emitted afterwards carries these identifiers, so you can filter traces by user, follow a session end-to-end, and break down cost per customer.

Streaming support

Streamed LLM responses are traced correctly: the span stays open until the stream is consumed (full generation latency) and records time_to_first_token_ms.

Safe by design

• Never breaks your app — after init(), telemetry is best-effort; any failure means a dropped event, never an exception in your code.
• Off the hot path — events batch in the background with compression, retries, and a circuit breaker. Fork-safe under gunicorn/celery.

Optional extras

pip install "nightgaze[openai]"       # openai
pip install "nightgaze[anthropic]"    # anthropic
pip install "nightgaze[gemini]"       # google-genai
pip install "nightgaze[langchain]"    # langchain-core
pip install "nightgaze[langgraph]"    # langgraph
pip install "nightgaze[llamaindex]"   # llama-index-core

Requirements

Python 3.9+

License

Apache-2.0