neatlogs

LLM observability for AI agents.
Instrument once. Inspect everything.

PyPI version Python 3.10+ MIT License

Website  ·  Docs  ·  Get API key  ·  AI Skill


Agent failures don't throw exceptions — they produce wrong outputs, miss tool calls, or hallucinate.
Neatlogs captures every trace so you can see exactly what the model was given, what it decided, and what each step returned.

neatlogs

Installation

pip install neatlogs

Optional extras install the underlying LLM / framework libraries:

pip install "neatlogs[openai]"
pip install "neatlogs[crewai]"
pip install "neatlogs[langchain,langgraph]"
pip install "neatlogs[google-genai]"

Requires Python >= 3.10, < 3.14.

Quickstart

import neatlogs
from neatlogs import span

neatlogs.init(
    api_key="your-api-key",       # or NEATLOGS_API_KEY env var
    workflow_name="my-agent",
    instrumentations=["openai"],
)

# Import instrumented libraries AFTER init()
from openai import OpenAI


@span(kind="WORKFLOW", name="quickstart")
def main():
    client = OpenAI()
    return client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "What is AI?"}],
    )


main()
neatlogs.flush()
neatlogs.shutdown()

Auto-instrumentation captures LLM calls, tools, and retrievals as child spans. Use @span(kind="WORKFLOW") on your main function or request handler so each run shows up as a top-level trace in the dashboard.

Call neatlogs.init() before importing any instrumented library.

For long-running servers (FastAPI, Celery workers), call init() once at startup and decorate each request handler with @span(kind="WORKFLOW"). Do not call flush() / shutdown() per request.

Full walkthrough: Your First Trace.

Integrate into your codebase (recommended)

The fastest way to add NeatLogs to an existing project is the official Agent Skill — it encodes import order, @span kinds, CrewAI prompt binding, and troubleshooting so your coding agent gets it right.

Repo: github.com/neatlogs/skills

npx skills add neatlogs/skills --skill "neatlogs-py"

For Cursor:

npx skills add neatlogs/skills --skill "neatlogs-py" --agent "cursor"

No Node.js? Ask in chat: "Install the NeatLogs AI skill from github.com/neatlogs/skills"

Example prompts once installed:

  • "Add neatlogs tracing to my OpenAI calls"
  • "Instrument my CrewAI agents with neatlogs"
  • "Wrap my FastAPI handler so each request is a top-level trace"

Full install options: skills README

API reference: docs.neatlogs.com

Platform features

  • Traces: Full span trees — LLM calls, tools, retrievals, reranking, guardrails — with inputs, outputs, tokens, cost, and latency.

  • Timeline view: See which steps ran in parallel, where latency concentrated, and where the process was idle.

  • AI assistant: Ask questions grounded in the actual span data for a trace.

  • AI Search: Query traces in plain English without writing SQL.

  • Detections: Rules that flag matching spans — regex, numeric conditions, PII, or model classifiers.

  • Prompt management: Version prompts, promote labels, test in the Playground.

  • Evals: Human review campaigns — select traces or spans (or auto-collect future ones via filters), send custom rating forms to assigned reviewers, and track batch progress and scores.

  • Comments & voting: Pin notes to spans, @mention teammates, and thumbs-up/down vote outputs while debugging a trace.

Supported libraries

Pass keys to instrumentations in neatlogs.init(). Install extras when noted.

LLM providers

Provider Key Install
OpenAI openai pip install "neatlogs[openai]"
Anthropic anthropic pip install "neatlogs[anthropic]"
Google Gemini google_genai pip install "neatlogs[google-genai]"
Azure AI Inference azure_ai_inference pip install "neatlogs[azure-ai-inference]"
Azure OpenAI (AzureOpenAI client) openai pip install "neatlogs[azure-openai]"
AWS Bedrock bedrock pip install "neatlogs[bedrock]"
LiteLLM litellm pip install "neatlogs[litellm]"
Groq groq pip install "neatlogs[groq]"
Vertex AI vertexai pip install "neatlogs[vertexai]"
Vertex AI (google-genai SDK) vertex_ai pip install "neatlogs[vertex-ai]"
Mistral mistralai pip install "neatlogs[mistralai]"
Portkey portkey pip install "neatlogs[portkey]"

Agent frameworks

Framework Key Install
LangChain langchain pip install "neatlogs[langchain]"
LangGraph langgraph pip install "neatlogs[langgraph]"
CrewAI crewai pip install "neatlogs[crewai]"
LlamaIndex llamaindex pip install "neatlogs[llama-index]"
Haystack haystack pip install "neatlogs[haystack]"
AutoGen autogen pip install "neatlogs[autogen-agentchat]"
DSPy dspy pip install "neatlogs[dspy]"
MCP mcp pip install "neatlogs[mcp]"
Agno agno pip install "neatlogs[agno]"
Google ADK google_adk pip install "neatlogs[google-adk]"
OpenAI Agents openai_agents pip install "neatlogs[openai-agents]"
Pydantic AI pydantic_ai pip install "neatlogs[pydantic-ai]"
smolagents smolagents pip install "neatlogs[smolagents]"
Hermes hermes pip install "neatlogs[hermes]" (Python 3.11+)

Structured output & guardrails

Library Key Install
Instructor instructor pip install "neatlogs[instructor]"
Guardrails AI guardrails pip install "neatlogs[guardrails]"

Vector stores & HTTP

Library Key Notes
ChromaDB chromadb Auto-instrumented when installed
Pinecone pinecone Auto-instrumented when installed
Qdrant qdrant Auto-instrumented when installed
Weaviate weaviate Auto-instrumented when installed
Milvus milvus pip install "neatlogs[milvus]"
Redis redis Auto-instrumented when installed
OpenSearch opensearch Auto-instrumented when installed
Elasticsearch elasticsearch Auto-instrumented when installed
Marqo marqo Auto-instrumented when installed
HTTP clients requests, httpx, urllib3, aiohttp Auto-instrumented when installed

Configuration

NEATLOGS_API_KEY=your-api-key
NEATLOGS_ENDPOINT=https://ingest.neatlogs.com   # optional — this is the default

Get your API key from the NeatLogs dashboard. Full init() options: reference.

Examples

Runnable reference apps live in examples/sdk_examples/. Each folder has a requirements.txt (PyPI install) and .env.example.

Example Framework Run
anthropic_multiagent/ Anthropic + Bedrock python main.py
openai_multiagent/ OpenAI via Azure python main.py
google_genai_multiagent/ Google GenAI python main.py
langchain_react/ LangChain ReAct python react_agent.py
langgraph_multiagent/ LangGraph python main.py
langgraph_research_assistant/ LangGraph python main.py
marketing_strategy_demo/ CrewAI + Gemini search python main.py
neatlogs_support_bot/ CrewAI RAG bot python main.py
reasoning_model_workflow/ Multi-provider reasoning python main.py
support_copilot_demo/ Support agent demo traces RUN=A python support_copilot.py
support_copilot_demo_triaged/ Post-Triage support demo SENDGRID_FAKE_SUCCESS=1 RUN=B python support_copilot.py

Adding NeatLogs to your own code? Use the AI skill above — not copy-paste from this README.

Best practices

  1. init() before LLM imports — auto-instrumentation patches libraries at import time.
  2. Wrap script/server entry points in @span(kind="WORKFLOW") — each run gets a clear top-level trace in the dashboard.
  3. Use auto-instrumentation first — only add more @span decorators for custom orchestration.
  4. trace() for prompts and sessions — not as a wrapper around @span(kind="WORKFLOW").
  5. workflow_name = feature name — put env/version/tech stack in tags=.
  6. Scripts: flush() then shutdown() at exit. Servers: init() once, no per-request shutdown.

License

MIT — see LICENSE.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.4.21)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for shubham063 from gravatar.com shubham063

Credits

Author: Neatlogs

License

MIT License (MIT)

Requires

Python <3.14, >=3.10

Provides Extra

azure-ai-inference openai azure-openai anthropic langchain langgraph crewai llama-index google-adk groq agno bedrock dspy litellm google-genai openai-agents guardrails haystack instructor mcp mistralai portkey pydantic-ai smolagents hermes vertexai vertex-ai autogen-agentchat milvus

Tags

llm tracking monitoring logging ai machine-learning observability collaboration

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

neatlogs-1.4.20.tar.gz (222.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

neatlogs-1.4.20-py3-none-any.whl (241.1 kB view details)

Uploaded Python 3

File details

Details for the file neatlogs-1.4.20.tar.gz.

File metadata

  • Download URL: neatlogs-1.4.20.tar.gz
  • Upload date:
  • Size: 222.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.10.20

File hashes

Hashes for neatlogs-1.4.20.tar.gz
Algorithm Hash digest
SHA256 ac088f778a3dcc09f24961355e74e34c1a4cd03aeb829c4f709dec079bd65c4d
MD5 b8b28d2ff489a364166ee95c61e00ef4
BLAKE2b-256 eda09bcba81176d45c8a6514031f5dd059c11a70181c5c7d763a364e0ca893aa

See more details on using hashes here.

File details

Details for the file neatlogs-1.4.20-py3-none-any.whl.

File metadata

  • Download URL: neatlogs-1.4.20-py3-none-any.whl
  • Upload date:
  • Size: 241.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.10.20

File hashes

Hashes for neatlogs-1.4.20-py3-none-any.whl
Algorithm Hash digest
SHA256 009612af956d664cc1b881b19ce5b8cf8edfba8c2e517de4f30240d0a615f1bf
MD5 cc5b840c33caf57d20893873bf5ea8e0
BLAKE2b-256 acc66452bd795386c52a9cee6173c08ab37d926a0769267f30458ffe7f3643cc

See more details on using hashes here.

Release history Release notifications | RSS feed

1.4.21

2 files

This release

1.4.20 This release

2 files

1.4.19

2 files

1.4.18

2 files

1.4.17

2 files

1.4.16

2 files

1.4.15

2 files

1.4.14

2 files

1.4.13

2 files

1.4.12

2 files

1.4.11

2 files

1.4.10

2 files

1.4.9

2 files

1.4.8

2 files

1.4.7

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.9

2 files

1.3.8

2 files

1.3.7

2 files

1.3.6

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.9

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

1 file

1.1.9

2 files

1.1.8

2 files

1.1.7

2 files

1.1.6

2 files

1.1.5

2 files

1.1.4

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.0.0

2 files

0.8.0

2 files

0.7.0

2 files

0.6.0

2 files

0.5.0

2 files

0.4.0

2 files

0.3.0

2 files

0.2.0

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page