Introduction

When your app talks to an AI model, a lot happens that you can't see: what prompt was actually sent, what the model replied, which tools it called, how long it took, and how much it cost. Neatlogs records all of that and shows it to you in a dashboard — so when something goes wrong (a weird answer, a slow response, a surprising bill) you can look at exactly what happened, step by step.

You add a few lines to your code once; from then on every AI call is captured automatically. It works with Python and TypeScript, and with the OpenAI, Anthropic, and Google models you're probably already using — no AI-framework experience required.

New here? Three words to know

You'll see these throughout the docs. They're simpler than they sound:

• Trace — the full record of one run of your app (e.g. answering one user's question). Think of it as one "story" from start to finish.
• Span — a single step inside that story: one call to an AI model, one tool/function call, one retrieval. A trace is made of spans nested inside each other.
• Instrument — the one-time setup that tells Neatlogs to start recording. Usually just adding neatlogs.init(...) and listing the libraries you use.

That's the whole mental model: you instrument once, your app produces traces made of spans, and you read them in the dashboard.

This is all it takes

Add a few lines near the top of your app:

import os
import neatlogs

neatlogs.init(
    api_key=os.environ["NEATLOGS_API_KEY"],   # from your Neatlogs dashboard
    workflow_name="my-agent",                  # any name for this app
    instrumentations=["openai"],               # the AI library you use
)

That's it. Every AI call your app makes after this is captured as a trace and shows up in your dashboard — no other code changes needed.

Or let the wizard do it

You don't have to wire this up by hand. From your project root:

npx @neatlogs/wizard

The wizard detects your stack, installs the right SDK, and instruments your code for you — all you need is your API key. See Instrument with the Wizard, or Your First Trace for the manual walkthrough.

Why Neatlogs

Agent failures don't throw exceptions. They produce wrong outputs, miss tool calls, or hallucinate. Diagnosing them requires seeing what the model was given, what it decided, and what each step returned. That context lives in traces.

Neatlogs is built around traces as the primary debugging artifact. Every run is fully captured. Engineers can inspect raw span data; non-engineers can search, comment, and flag issues without needing to understand the underlying data model.

Get started

How to use these docs

The docs are organized into these sections:

Quickstart: start here if you're new — what Neatlogs is, the core ideas, and the wizard that instruments your project automatically.

Features: everything the Neatlogs dashboard gives you and how to use it — traces, detections, analytics, triage, evals, and more.

Integrations: every provider, agent framework, and agent SDK Neatlogs supports — OpenAI, Anthropic, Bedrock, Vertex, LangChain, CrewAI, Mastra, and more — plus the Claude Code plugin, opencode, Agent Skills, and MCP server. Each page shows Python + TypeScript where both exist.

Python SDK: the core Python SDK — quickstart, instrumenting your own code with @span/trace(), prompt templates, and reference.

TypeScript SDK: the same for Node.js apps — quickstart, span()/trace(), prompt templates, and reference.

Guides: end-to-end examples for common agent patterns and use cases.

Reference: cross-language concepts — span kinds, sessions, tags, workflow names, and PII redaction.