ghostspan

Built by MeshAI Labs, the Agent Control Plane for monitoring and governing AI agents.

ghostspan is a local, offline command-line scanner that finds silent failures in AI agent trace exports: OTel (OpenTelemetry) and Langfuse. It looks for the failure modes that never raise an exception and never show up as a 5xx: swallowed errors, empty completions, truncated responses, degraded tool-call success rates, retry loops, cost outliers, and latency outliers.

The guarantee

ghostspan runs entirely on your machine, on files you already have.

• 100% local. No data leaves this machine.
• Zero network calls. There is no HTTP client anywhere in this codebase.
• Zero telemetry. Nothing is phoned home, ever.
• No API keys required. There is nothing to configure and nothing to authenticate.

Detection always runs on tokens and structural facts, never on raw content, unless you explicitly opt in with --show-content (terminal only) or --content-in-file (markdown report). Redaction is on by default everywhere.

Install

pipx install ghostspan

pipx is recommended because a bare pip install fails on modern Debian/Ubuntu (PEP 668, externally managed environments). If you prefer plain pip, use a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install ghostspan

Usage

ghostspan traces.jsonl
ghostspan ./exports/            # recurses for *.json and *.jsonl
ghostspan traces.jsonl --format langfuse
ghostspan traces.jsonl --since 7d --fail-on high
ghostspan traces.jsonl --show-content --max-content-chars 120

By default ghostspan writes a markdown report to silent-failure-report.md (see examples/silent-failure-report.md for a sample) and prints a summary to the terminal.

Flags

Exit codes

• 0: scan completed. Findings never fail the process unless --fail-on is set.
• 1: only with --fail-on, when a finding at or above the given tier was found.
• 2: usage error (bad flags, no input paths).
• 3: input error, no parseable spans were found in any input.

What it detects

Every rule and its exact threshold is printed in the report's methodology appendix. Detectors degrade gracefully: a missing attribute never becomes an assumed value, and a detector with too little data to run says so explicitly rather than silently skipping or guessing.

What it does not catch

ghostspan runs deterministic and statistical heuristics over trace structure, status codes, token counts, and finish reasons. It cannot catch natural-language refusals, semantically wrong answers, or hallucination and faithfulness failures. A clean report is not proof the agent behaved correctly, only that it did not trip these particular structural heuristics.

License

MIT. See LICENSE.

Built by MeshAI Labs.