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.

Before initialization, run the local Doctor. It sends generated non-user workflow and tool spans through an isolated instance of the installed SDK's normalization, masking, capture, and flush pipeline. It performs no backend request and requires no API key:

python -m neatlogs doctor --local --json
# or: neatlogs-doctor --local --json

A passing local result proves that this installed SDK pipeline works. It does not prove that an application's own instrumentors or backend export are working. Doctor capture is enabled only inside the isolated local/probe pipeline, is strictly bounded, and is cleared during shutdown; normal application telemetry is never retained for diagnostics. Use doctor --probe to export a controlled trace through /v1/traces and read that exact trace back through /api/traces/v3/:traceId; HTTP acceptance or exporter flush alone is not a pass.

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.

Payload delivery status

Normal OTLP batches are byte-limited and gzip-compressed. Deploy and verify gzip-aware trace intake before releasing this SDK version. Captured text values are bounded to 100,000 UTF-8 bytes and telemetry items to a 1 MB capture budget. A truncated value contains its original byte length, SHA-256 digest, and backend_upload_contract_unavailable; spans/logs also carry neatlogs.capture.* diagnostics, exposed through get_delivery_diagnostics().

Typed-media metadata is detected without fetching remote content. Credential-bearing remote locators are reduced to scheme/host/path, and large inline media is replaced in captured bodies by typed unavailable metadata rather than a base64 prefix. Authenticated large-media and oversized trace uploads are available behind the default-off uploads_enabled=True option (or NEATLOGS_UPLOADS_ENABLED=true). The SDK masks first, prepares an API-key-authenticated upload, PUTs only to the returned HTTPS object URL, completes backend validation, and exports only a small canonical ready reference. Signed URLs and headers never enter telemetry. In-progress, rejected, expired, or otherwise incomplete uploads fail explicitly and are exposed through get_delivery_diagnostics(); an oversized item is never also sent through ordinary ingest.

Prompt client boundary

Prompt-management requests are product-data API calls, not trace telemetry. The telemetry mask= callback does not transform prompt content passed to PromptClient; apply any desired prompt transformation before calling the prompt API. The prompt client authenticates with the configured project API key and endpoint independently of the telemetry exporter.

Unpinned and label-based reads use a configurable 60-second cache by default. An expired entry is returned immediately while one background refresh runs for that key; a refresh failure leaves the stale entry available for the next retry. Explicitly versioned reads stay pinned to that immutable version for the lifetime of the client. Each client retains at most 100 prompt selectors and runs at most four background refreshes concurrently. Call PromptClient.close() when an explicitly constructed client is no longer needed. neatlogs.shutdown() closes the module-level prompt clients created from init() so a later SDK generation cannot reuse an earlier project's key or cache. Prompt API failures do not flush, stop, or reconfigure the telemetry provider, and API response bodies are not copied into SDK error messages.

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. The Wizard detects the project, downloads the needed Skill from the latest Skills release, applies the documented instrumentation, and runs the applicable checks.

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

Agent frameworks

Structured output & guardrails

Vector stores & HTTP

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.

Doctor diagnostics

Validate the SDK's final normalized and masked telemetry envelope without sending data:

neatlogs doctor --local
# or
neatlogs-doctor --local --json

To verify the complete ingestion path, export a controlled trace through the existing POST /v1/traces route and read that exact trace back through GET /api/traces/v3/:traceId:

NEATLOGS_API_KEY=your-api-key neatlogs doctor --probe --json

Local mode is network-free and uses generated diagnostic data. Probe mode reports the first failing backend stage with a stable reason code and never prints the API key.

Examples

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

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.