Traces are not arriving

When no trace appears, locate the first broken step:

Application creates spans
    ↓
Neatlogs initializes with a project key
    ↓
Exporter sends a completed batch
    ↓
Network and regional endpoint accept it
    ↓
Project receives and processes it
    ↓
Dashboard scope includes it

Use one distinctive test run and record its timestamp before changing configuration.

1. Run SDK Doctor

SDK Doctor separates SDK problems from application problems. Run it from the application root before editing instrumentation:

1. Local mode (doctor --local) needs no key and no network. It proves the installed SDK can capture, mask, and flush a controlled trace.
2. Probe mode (doctor --probe) uses NEATLOGS_API_KEY from the environment. It sends one controlled trace through the normal write path and reads that exact trace back.

python -m neatlogs doctor --local --json
python -m neatlogs doctor --probe --json

See SDK Doctor for the TypeScript and Go commands.

If the probe passes but your application's traces are missing, the problem is in your application's initialization, code path, or shutdown, not the key or endpoint. If it fails, read first_failure and the reason-code guide. Doctor does not check your own instrumentation or import order.

2. Confirm the destination project and region

The ingestion key determines the project. The dashboard project currently open does not change where telemetry was sent.

Check:

• organization and project selected in the workspace switcher;
• key used by the running deployment;
• region: a project created at https://eu.app.neatlogs.com needs the EU ingest endpoint;
• the Workflow, Tags, and Metadata filters in the trace list;
• the time range (the trace list defaults to Last 14 days, in your browser's timezone).

Clear filters and include enough time for delayed export or a long-running execution. The Status filter shows whether a trace is Processing, Ready, or Processing failed.

For a brand-new project, the setup page checks for the first trace automatically and shows Waiting for first trace until one arrives.

3. Confirm the key and endpoint are available

For SDK setup, verify that the expected environment variable or explicit key is present in the actual runtime, not only in a local shell.

export NEATLOGS_API_KEY="your-project-api-key"
# EU projects only:
export NEATLOGS_ENDPOINT="https://eu.ingest.neatlogs.com"

import neatlogs
neatlogs.init(debug=True)

With debug logging enabled, a missing key reports that HTTP export is disabled while the application continues running. Without debug logging, that message is not shown.

Server-side SDKs need the project API key or a project ingest credential. A browser write key (nlw_) only works with the Browser SDK and POST /v1/trace; SDK export rejects it with 401.

Never print the complete key. If it may have been exposed, see Understand project keys.

4. Check initialization order

In Python, call neatlogs.init() before importing libraries listed in instrumentations=[...]. Python wrap() and the TypeScript SDK have no import-order rule. No SDK warns when the order is wrong.

For explicit wrappers:

• confirm the application uses the wrapped client;
• confirm the executed code path reaches the instrumented operation;
• avoid creating an unwrapped second client later.

Create one explicit test span when you need to distinguish export failure from unsupported automatic instrumentation.

5. Let the run complete

Exporters buffer spans. A short-lived script can exit before the final batch is sent.

Confirm:

• the root operation finishes;
• spans close cleanly;
• the SDK flush or shutdown path runs;
• serverless and worker runtimes allow export time;
• errors do not terminate the process before cleanup.

Python and TypeScript register exit handlers by default. Go does not: call the shutdown function returned by Init (or neatlogs.Flush) before the process exits. See Flush and shutdown.

Several partial roots can indicate that no explicit workflow root surrounds the complete request or that context propagation was lost.

6. Check the endpoint and network

Inspect debug or exporter logs for:

• authorization errors, including a key from the other region;
• DNS or TLS failures;
• proxy and egress restrictions;
• connection timeouts;
• retries;
• an incorrect custom endpoint (use the base URL, such as https://eu.ingest.neatlogs.com, without a path);
• OTLP protocol or port mismatch for raw OpenTelemetry exporters.

Test from the same runtime or network as the application. A request working on a laptop does not prove production egress works.

7. Check what the SDK drops on purpose

Spans can be dropped before export by configuration:

• NEATLOGS_DISABLE_EXPORT (or disable_export) turns export off;
• a sample_rate below 1.0 exports only some traces;
• a mask callback that raises or times out drops the affected item rather than exporting it unmasked (in TypeScript and Go, returning null or nil also drops it).

8. Check instrumentation coverage

If explicit spans arrive but model or tool spans do not:

• confirm the installed integration supports the library and version;
• in Python, initialize before importing auto-instrumented libraries;
• check whether the failing path uses a different client;
• verify framework-specific instrumentation settings;
• check whether a mask callback dropped the span, or server-side redaction removed content.

Use the relevant SDK Reference or Integration page for canonical setup.

Diagnose by symptom

Frequently asked questions

Why is there no application error when the key is missing?

The SDK lets the application continue with export disabled. Enable debug logging during setup, or run Doctor probe mode.

Why do scripts lose their last trace?

The process may exit before a buffered batch is exported. Flush or shut down cleanly.

Why do I see several partial traces?

Create one explicit workflow root and propagate its context across services and workers.

What should I send support?

Project ID, test timestamp and timezone, region, SDK and version, workflow, runtime, debug output, endpoint type, the Doctor JSON result, and whether an explicit test span appeared. Never send the full key.

Next step

Find and read the first run →