ghostspan 0.1.0

Local, offline scanner that finds silent failures in OTel and Langfuse AI agent trace exports

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

Flag	Description
--format auto|otlp|langfuse	Force the input format instead of auto-detecting it.
--out PATH	Markdown report path (default silent-failure-report.md).
--no-file	Do not write the markdown report.
--json [PATH]	Write structured, already-redacted JSON findings to PATH or stdout.
--since / --until	Time filter: 7d or ISO 8601.
--show-content	Show redacted content snippets in the terminal only. Off by default.
--content-in-file	Also allow redacted content snippets in the markdown report. Off by default.
--redact PATTERN	Extra regex to redact from content snippets. Repeatable.
--max-content-chars N	Max characters per content snippet (default 200).
--min-samples N	Override the minimum group size used by every statistical detector gate.
--config ghostspan.toml	Defaults for any option above.
--price-map FILE	JSON file overriding the bundled pricing table for dollar estimates.
--fail-on high|medium|low	Exit 1 if a finding at or above this tier exists. Off by default.
--quiet	Compact terminal summary only.
--no-color	Disable terminal colors.
--version	Print the version and exit.

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

ID	Detector	Tier
D1	Errors not surfaced to the trace root, and abandoned tool calls	HIGH
D2	Truncation and finish_reason anomalies	HIGH / MEDIUM
D3	Empty completions and structured-error envelopes	HIGH
D4	Degraded tool-call success rate	MEDIUM
D5	Retry loops	MEDIUM
D6	Cost anomalies (token-based; dollars are display-only)	MEDIUM / INFO
D7	Latency anomalies	INFO

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.