Metadata-Version: 2.4
Name: oneport-debug-tracer
Version: 0.1.0
Summary: Cross-service distributed trace debugger: ingest OTel/Datadog/Splunk trace IDs and pin failures to exact source lines across multiple repos
Project-URL: Homepage, https://github.com/oneport-debug/oneport-debug
Project-URL: Repository, https://github.com/oneport-debug/oneport-debug
Project-URL: Bug Tracker, https://github.com/oneport-debug/oneport-debug/issues
Project-URL: Changelog, https://github.com/oneport-debug/oneport-debug/blob/main/CHANGELOG.md
Author: OnePort Debug Contributors
License: Apache-2.0
Keywords: datadog,debugging,distributed-tracing,enterprise,observability,opentelemetry,rca,splunk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1.7
Requires-Dist: httpx>=0.27.0
Requires-Dist: oneport-debug-core>=0.1.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=13.8.0
Provides-Extra: multilang
Requires-Dist: oneport-debug-core[multilang]>=0.1.0; extra == 'multilang'
Description-Content-Type: text/markdown

# oneport-debug-tracer

**Cross-service distributed-trace root cause analysis.** Give it a trace ID; it
maps every span to the exact line of code across *all* your repositories — even
when a single request crosses a React frontend, a Go API gateway, and a Python
payment service — and tells you what broke and why.

This is the gap Claude Code and Copilot can't close: they trace code within one
repo. A real production request fails across many.

## Try it in 60 seconds (no Datadog, no API key)

```bash
pip install oneport-debug-tracer
oneport-tracer demo
```

The demo runs the **real** span-to-code engine against a bundled sample trace and
a mini three-language monorepo (TypeScript → Go → Python). You'll see each span
resolved to its exact `file:line` and a full root-cause analysis of a realistic
cross-service bug — a checkout `500` whose true cause is a broken contract with
the auth service.

```
  Span (call tree)     Service           Duration   Status    Matched code location
 ─────────────────────────────────────────────────────────────────────────────────
  submitCheckout       frontend           1240 ms   ● error   frontend/src/checkout.ts:7
    └─ RouteCharge     api-gateway        1150 ms   ● error   api-gateway/handlers/charge.go:6
      └─ charge_card   payment-service       8 ms   ● error   payment-service/src/payment.py:8
```

Add `--format json` to get machine-readable output for Jira/CI pipelines.

## Use it on your own traces

```bash
# 1. Authenticate (stores your license key)
oneport-auth login

# 2. Point it at your trace platform + repos
export DD_API_KEY=…  DD_APP_KEY=…
export ANTHROPIC_API_KEY=…           # or run fully local: see oneport-debug-local

oneport-tracer analyze \
  --trace-id <id-from-pagerduty> \
  --platform datadog \
  --repos repos.yaml
```

`repos.yaml` maps service names (as they appear in your traces) to git remotes
or local clones:

```yaml
payment-service: git@github.com:acme/payment-service.git
api-gateway:     git@github.com:acme/api-gateway.git
frontend:        git@github.com:acme/frontend.git
```

Supported platforms: `datadog`, `splunk`, `otel`, `jaeger`, `tempo`.
Supported languages for code mapping: Python, Java, Kotlin, Go, TypeScript/JavaScript.

## How it works

1. **Ingest** all spans for the trace from your APM platform.
2. **Index** every repo's symbols and HTTP routes (Python AST + tree-sitter for
   Java/Kotlin/Go/TS, with a regex fallback when tree-sitter isn't installed).
3. **Match** each span to its source line by operation name, HTTP route, and
   qualified `Class.method` notation.
4. **Analyze** the failing path with an LLM (cloud or fully on-prem) and emit a
   structured `RCAResult` — ready for the terminal, Jira, Slack, or a SIEM.

Secrets are scanned and redacted from every prompt before it leaves your machine,
and every analysis is written to a tamper-evident, hash-chained audit log.

## Output

A structured root-cause analysis: severity, root cause, confidence, the exact
affected code locations (repo · file · line · function · git-blame author), and a
recommended fix. Part of the [OnePort Debug](https://github.com/) enterprise
debugging suite.

## License

Apache-2.0
