init() Reference

Parameters

api_key

Type: str | Required (or NEATLOGS_API_KEY env var)

Your Neatlogs API key. If not passed, the SDK reads NEATLOGS_API_KEY from the environment. Get your key from the Neatlogs dashboard.

neatlogs.init(api_key=os.environ["NEATLOGS_API_KEY"], ...)

endpoint

Type: str | Required

Your Neatlogs ingest endpoint URL. Get this from the Neatlogs dashboard.

neatlogs.init(endpoint=os.environ["NEATLOGS_ENDPOINT"], ...)

workflow_name

Type: str | Optional (default: script filename)

A label for this application or feature. All traces from this process appear under this name in the dashboard. If omitted, the SDK uses the current script's filename.

neatlogs.init(workflow_name="customer-support", ...)

See Workflow Name for naming guidance.

instrumentations

Type: list[str] | Optional

Libraries to auto-instrument. Pass only what your app actually uses — Neatlogs patches each library at init time to capture LLM calls, token counts, latency, and more automatically.

neatlogs.init(
    instrumentations=["openai", "langchain", "chromadb"],
    ...
)

See Supported Libraries for all valid values.

tags

Type: list[str] | Optional

Labels attached to every trace produced by this init() call. Use them to filter traces in the dashboard by environment, version, team, or experiment.

neatlogs.init(tags=["production", "v2.1", "team-search"], ...)

See Tags.

user_id

Type: str | Optional

The identifier of the end-user in your application — whatever string you already use to identify users in your own system (a UUID, email, or username). Neatlogs attaches this to every trace so you can filter and group by user in the dashboard.

# Pull from your own auth/session context
user_id = current_user.id

neatlogs.init(user_id=user_id, ...)

auto_session

Type: bool | Optional (default: False)

When True, the SDK generates a unique session ID at startup and attaches it to every trace. Use this in chatbots and multi-turn agent apps to group all traces from a single conversation under one session in the dashboard.

neatlogs.init(auto_session=True, ...)

See Sessions.

session_id

Type: str | Optional

A custom session ID. Use this when you want to control the session identifier yourself rather than letting the SDK generate one. Takes precedence over auto_session.

neatlogs.init(session_id=f"conv_{conversation_id}", ...)

sample_rate

Type: float | Optional (default: 1.0)

Fraction of traces to export, between 0.0 and 1.0. At 1.0 (default), every trace is sent. Lower this in high-traffic production systems where you only need a statistical sample.

# Export 10% of traces
neatlogs.init(sample_rate=0.1, ...)

flush_interval

Type: float | Optional (default: 5.0)

How often (in seconds) the SDK sends buffered spans to the backend. The default of 5 seconds works for most applications. Lower this if you need near-real-time visibility; raise it to reduce network overhead in high-throughput systems.

batch_size

Type: int | Optional (default: 100)

Maximum number of spans sent in a single export request. If 100 spans accumulate before the flush interval fires, the SDK sends them immediately. Tune this together with flush_interval for high-volume workloads.

debug

Type: bool | Optional (default: False)

Enables verbose SDK logging. Useful when verifying instrumentation is working or diagnosing missing traces.

neatlogs.init(debug=True, ...)

log_level

Type: str | Optional (default: "WARNING")

Minimum Python logging level to auto-capture as LOG spans. Any logging.info(), logging.warning(), logging.error() call inside a @span or with neatlogs.trace(): block at or above this level is captured automatically — no manual neatlogs.log() required.

Set to "INFO" to also capture logging.info() calls:

neatlogs.init(log_level="INFO", ...)

pii_enabled

Type: bool | Optional (default: None)

Override the team-level server-side PII redaction toggle for this project. When None (default), the setting configured in the Neatlogs dashboard is used.

• True — force PII redaction on, regardless of the dashboard setting
• False — disable PII redaction entirely for all spans from this process

# Disable server-side PII redaction for a dev/test environment
neatlogs.init(pii_enabled=False, ...)

Note: This controls server-side redaction only. To redact data before it leaves your process, use the mask parameter instead.

pii_span_types

Type: list[str] | Optional (default: None)

Override which span types have server-side PII redaction applied. When None (default), the setting configured in the Neatlogs dashboard is used.

Pass a list of span kind strings to limit redaction to specific span types:

# Only redact PII in LLM and tool spans
neatlogs.init(pii_span_types=["LLM", "TOOL"], ...)

Valid span kinds: "LLM", "TOOL", "AGENT", "CHAIN", "WORKFLOW", "RETRIEVER", "RERANKER", "MCP_TOOL", "HTTP", "LOG".

Pass an empty list to disable redaction across all span types (equivalent to pii_enabled=False).

Full Example

import os
import neatlogs

neatlogs.init(
    api_key=os.environ["NEATLOGS_API_KEY"],
    endpoint=os.environ["NEATLOGS_ENDPOINT"],
    workflow_name="customer-support",
    instrumentations=["openai", "langchain"],
    tags=["production", "v2"],
    user_id=current_user.id,
    sample_rate=1.0,
    # PII redaction overrides (optional — defaults to team dashboard config)
    pii_enabled=True,
    pii_span_types=["LLM", "TOOL"],
)