Installation

From PyPI

pip install autopsy-cli

From Source

git clone https://github.com/zaappy/autopsy.git && cd autopsy
pip install -e ".[dev]"

Verify Installation

autopsy --version
# autopsy  0.3.0
# prompt   v1
# python   3.12.x

Quick Start

Three steps: install → init → diagnose.

1. Configure

autopsy init      # Interactive wizard — creates ~/.autopsy/config.yaml + .env

2. Diagnose

autopsy diagnose  # Run full pipeline: collect → reduce → AI → render

3. Or Use the TUI

autopsy           # Interactive menu: Diagnose, History, Setup, Validate, Config

TUI Shortcuts

Configuration

After autopsy init, edit ~/.autopsy/config.yaml or re-run the wizard. Credentials are stored in ~/.autopsy/.env.

Config Sections

Managing Config

autopsy config show       # Print config (secrets masked)
autopsy config show --reveal  # Show secrets
autopsy config validate   # Check env vars and connectivity

How It Works

Pipeline Details

Step 1: Collect

All configured collectors run in parallel by default using asyncio.to_thread with a ThreadPoolExecutor fallback. Each collector creates its own API client instance (thread-safe). Partial failures are handled gracefully.

• CloudWatch: Logs Insights queries, error-level log extraction
• Datadog: Logs API search with site support (us1, eu1, us3, us5, ap1)
• GitHub: Last N commits + diffs via PyGitHub
• GitLab: Commits, diffs, MRs, deployment events via python-gitlab

Step 2: Reduce

4-stage log reduction pipeline:

1. Query filter — regex at query level (~90% reduction)
2. Deduplication — hash message templates, keep 1 + count (~60%)
3. Truncation — 500 char/entry, stack traces to top 5 frames (~40%)
4. Token budget — hard cap at 6000 tokens, FIFO eviction

Step 3: Diagnose

The AI engine receives all collected data in a single prompt. Logs and deploys are grouped, and each collector is labeled in the prompt (e.g. per-source blocks) so the model can correlate across systems. When more than one collector runs, the prompt includes cross-source instructions. The LLM returns structured JSON with root cause, correlated deploy, suggested fix, timeline, and a sources array.

Step 4: Render

Output to Rich terminal panels (default), raw JSON (--json), markdown post-mortem (--postmortem), or Slack webhook (--slack).

• Terminal & Slack: A Sources summary panel/line appears only when there are multiple log sources and/or multiple deploy sources.
• Post-mortem: Data Sources markdown table only appears when more than one source contributed.
• JSON & History: Always includes the sources array structure when present (name, data_type, entry_count).

CLI Reference

Collectors

All collectors implement the BaseCollector ABC and run in parallel by default.

CloudWatch

Uses boto3 to run CloudWatch Logs Insights queries. Polls with backoff until results are ready. Applies the 4-stage log reduction pipeline.

• Config: region, log_groups, time_window
• Auth: AWS CLI credentials
• Errors: AWSAuthError, AWSPermissionError

Datadog

Optional. Uses the Datadog Logs Search API. Shares the same log reduction pipeline as CloudWatch.

• Config: site (us1/eu1/us3/us5/ap1), service, source, time_window
• Auth: DD_API_KEY + DD_APP_KEY
• Behavior: Skips with warning when keys not set

GitHub

Uses PyGithub to fetch recent commits and diffs. Smart diff reduction: filter by file extension, exclude lockfiles/generated, cap per file and per commit.

• Config: repo, branch, deploy_count, token_env
• Auth: GITHUB_TOKEN
• Errors: GitHubAuthError, GitHubRateLimitError

GitLab

Optional. Uses python-gitlab to pull commits, diffs, merge requests, and deployment events. Supports self-hosted instances.

• Config: url, project_id, branch, deploy_count, token_env
• Auth: GITLAB_TOKEN
• Errors: GitLabAuthError, GitLabRateLimitError

Parallel Execution

All active collectors run concurrently using asyncio.to_thread with asyncio.gather. Falls back to ThreadPoolExecutor if a running event loop is detected.

• Single collector → sequential (no asyncio overhead)
• Multiple → parallel (wall-clock ≈ slowest collector)
• Partial failure → warn and continue
• All fail → raises CollectorError
• Use --sequential for debugging

AI Engine

The orchestrator calls the AIEngine interface — never calls provider APIs directly.

Supported Providers

How It Works

1. Build prompt: System prompt + user prompt from all collected data
2. Call LLM: Single API call with structured JSON output instructions
3. Parse response: Validate JSON against Pydantic models
4. Retry: Once on malformed JSON. Falls back to raw text on second failure.

Output Structure

• Root Cause — summary, category, confidence (0.0–1.0), evidence
• Correlated Deploy — commit SHA, author, PR title, changed files
• Suggested Fix — immediate action + long-term recommendation
• Timeline — chronological event reconstruction

Interface Contracts

BaseCollector collectors/base.py

class CollectedData(BaseModel):
    source: str              # "cloudwatch", "github", "gitlab"
    data_type: str           # "logs" | "deploys" | "metrics"
    entries: list[dict]      # Normalized data entries
    time_range: tuple[datetime, datetime]
    raw_query: str           # The query used (for debugging)
    entry_count: int         # Total before dedup/truncation
    truncated: bool          # Whether data was reduced

class BaseCollector(ABC):
    @abstractmethod
    def validate_config(self, config: dict) -> bool: ...
    @abstractmethod
    def collect(self, config: dict) -> CollectedData: ...
    @property
    @abstractmethod
    def name(self) -> str: ...

AIEngine ai/engine.py

class AIEngine:
    def diagnose(self, collected_data: list[CollectedData]) -> DiagnosisResult:
        """Build prompt, call LLM, parse response.
        Retries once on malformed JSON."""
    def _build_prompt(self, collected_data) -> tuple[str, str]: ...
    def _parse_response(self, raw: str) -> DiagnosisResult: ...

DiagnosisOrchestrator diagnosis.py

class DiagnosisOrchestrator:
    def run(self, *, time_window=None, log_groups=None,
            provider=None, sequential=False) -> DiagnosisResult:
        """Full pipeline: validate → collect → diagnose → return"""

Data Models

All models are Pydantic BaseModel subclasses.

DiagnosisResult ai/models.py

class RootCause(BaseModel):
    summary: str
    category: str    # code_change | config_change | infra | dependency | traffic | unknown
    confidence: float  # 0.0 - 1.0
    evidence: list[str]

class CorrelatedDeploy(BaseModel):
    commit_sha: str | None = None
    author: str | None = None
    pr_title: str | None = None
    changed_files: list[str] = []

class SuggestedFix(BaseModel):
    immediate: str
    long_term: str

class TimelineEvent(BaseModel):
    time: str
    event: str

class DiagnosisResult(BaseModel):
    root_cause: RootCause
    correlated_deploy: CorrelatedDeploy
    suggested_fix: SuggestedFix
    timeline: list[TimelineEvent]
    prompt_version: str = "v1"
    raw_response: str | None = None

Error Hierarchy

All custom exceptions inherit from AutopsyError.

Error Display

[ERROR] CloudWatch query timeout after 60s.
[FIX]   Check that the log group exists: aws logs describe-log-groups
[DOCS]  https://docs.aws.amazon.com/...

Changelog

Unreleased

Added

• Multi-source diagnosis: All collected data goes into one LLM prompt with cross-source correlation instructions when multiple collectors run.
• autopsy diagnose --source <name> flag to restrict to named collector(s).
• JSON output (--json) and saved history now include a sources array.
• UX gating for Sources summary panel, Slack line, and post-mortem Data Sources table (only appear when multiple sources contribute).
• GitLab collector: optional integration via python-gitlab — commits, diffs, merge requests, deployment events; supports self-hosted; smart diff reduction.
• Datadog log collector: optional integration with Datadog Logs API; supports us1/eu1/us3/us5/ap1.
• Shared log reduction pipeline used by CloudWatch and Datadog.
• Parallel collector execution: all collectors run concurrently by default.
• autopsy diagnose --sequential flag for debugging.

0.3.0 — 2026-03-11

Added

• Demo mode (--demo) with bundled fixture data.
• Datadog log collector.
• Shared log reduction pipeline (utils/log_reduction.py).

0.2.2 — 2026-03-10

Added

• Diagnosis history with local SQLite storage.
• Markdown post-mortem via --postmortem.
• Slack webhook output via --slack.

0.2.0

Added

• Interactive TUI with menu.
• CloudWatch Logs Insights and GitHub collectors.
• AI diagnosis engine (Anthropic / OpenAI).
• Terminal and JSON renderers.

Contributing

Development Setup

1. Fork and clone

   git clone https://github.com/YOUR_USERNAME/autopsy.git && cd autopsy

2. Virtual environment

   python -m venv .venv && source .venv/bin/activate

3. Install with dev dependencies

   pip install -e ".[dev]"

Code Style

Project Layout

Submitting Changes

1. Create a branch from main
2. Make changes and add/update tests
3. Run ruff check . and pytest locally
4. Push to your fork and open a PR against main

Security Policy

Supported Versions

Reporting a Vulnerability

Email: zaappy@users.noreply.github.com with a clear description, steps to reproduce, and impact.

What We Care About

• Credential or token leakage (config, env, or logs)
• Insecure handling of ~/.autopsy/.env or API keys
• Issues in data sent to/from third-party APIs
• Any behavior that could expose user or deployment data