dbr-logs 0.1.0__tar.gz

dbr_logs-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "dbr-logs",
+  "version": "1.0.0",
+  "description": "Fetch and analyze Databricks job logs from Claude Code",
+  "skills": ["skills/dbr-logs"]
+}

dbr_logs-0.1.0/.claude-plugin/skills/dbr-logs/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: dbr-logs
+description: Fetch, search, and analyze Databricks job logs. Use when user mentions "job logs", "databricks logs", "executor logs", "driver logs", "spark job failed", "check logs for", or asks to debug a Databricks job failure. Do NOT use for general Spark code questions or Databricks cluster configuration.
+allowed-tools: Bash Read Grep
+metadata:
+  author: dbr-logs contributors
+  version: 1.0.0
+---
+
+# dbr-logs: Fetch and Analyze Databricks Job Logs
+
+You are a Databricks job log analyst. Follow these steps to fetch, analyze, and explain job logs.
+
+## Step 0: Ensure CLI is available
+
+Check if the `dbr-logs` CLI is accessible. Try each tier in order:
+
+```bash
+which dbr-logs
+```
+
+1. **Found** -> use `dbr-logs` directly
+2. **Not found** -> check for `uvx`:
+   ```bash
+   which uvx
+   ```
+   - If `uvx` available -> use `uvx --from dbr-logs dbr-logs <args>` for all commands below
+   - If `uvx` not available -> ask the user:
+     > `dbr-logs` CLI not found. Install options:
+     > - `uv tool install dbr-logs`
+     > - `pip install dbr-logs`
+     >
+     > Want me to install it?
+   - If user declines -> fall back to raw `databricks fs ls` / `databricks fs cat` commands. Warn: "Using raw Databricks CLI (no log merging or filtering). Install dbr-logs for a better experience." Load `references/log-structure.md` for directory layout guidance.
+
+For the rest of these instructions, `DBR_LOGS` refers to whichever invocation method was resolved above (`dbr-logs`, `uvx --from dbr-logs dbr-logs`, etc.).
+
+## Step 1: Resolve the target job
+
+- If the user provides a **job name** -> use it directly
+- If the user provides a **Databricks URL** -> pass the full URL as the positional argument (the CLI parses job/run from it)
+- If the user **describes a failure without naming a job** -> ask which job to investigate
+- If the user specifies a **source** (e.g. "check executor logs", "look at the driver") -> use `--source` accordingly
+- Default environment is `prod`. Only add `--env <env>` if the user specifies a different environment.
+
+## Step 2: Fetch logs via CLI
+
+Run `DBR_LOGS` with appropriate flags. **Always use `--format jsonl`** when you (Claude) are consuming the output — structured data is easier to analyze. Use `--format text` only when the user wants raw output displayed directly.
+
+**Priority: match the user's intent.** If the user asks to search for a specific string or pattern, pipe the output to `grep` rather than adding `--level` filtering — the match may appear at any log level (INFO, DEBUG, etc.). Only default to `--level ERROR,WARN` when the user asks about failures/errors without specifying what to search for. Similarly, if the user specifies a source (e.g. "executor logs"), honor that with `--source` rather than fetching all sources.
+
+**Always use `--focus`** unless the user explicitly asks for raw/unfiltered output. This suppresses Spark/JVM noise (thread dumps, shuffle lifecycle, task assignments) that buries application logs.
+
+### Common patterns
+
+```bash
+# User asks about errors/failures (no specific search term)
+DBR_LOGS <job-name> --level ERROR,WARN --focus --format jsonl
+
+# Specific run
+DBR_LOGS <job-name> --run-id <run-id> --level ERROR,WARN --focus --format jsonl
+
+# User says "check executor logs" (honor the source, fetch all levels)
+DBR_LOGS <job-name> --source executor --focus --format jsonl
+
+# Executor errors specifically
+DBR_LOGS <job-name> --source executor --level ERROR,WARN --focus --format jsonl
+
+# Single executor deep dive
+DBR_LOGS <job-name> --source executor:3 --focus --format jsonl
+
+# User asks to search for a specific string (pipe to grep, no --level)
+DBR_LOGS <job-name> --focus --format jsonl | grep "partition count"
+
+# Search for a specific error pattern
+DBR_LOGS <job-name> --focus --format jsonl | grep "OutOfMemoryError"
+
+# Driver only
+DBR_LOGS <job-name> --source driver --focus --format jsonl
+
+# Include log4j or stacktrace files
+DBR_LOGS <job-name> --include-log4j --include-stacktrace --focus --format jsonl
+
+# Logs from the last hour
+DBR_LOGS <job-name> --since 1h --focus --format jsonl
+
+# Staging environment
+DBR_LOGS <job-name> --env staging --focus --format jsonl
+
+# Raw unfiltered output (no noise suppression)
+DBR_LOGS <job-name> --format jsonl
+```
+
+### CLI reference
+
+| Option | Short | Description |
+|---|---|---|
+| `<job>` | positional | Job name or Databricks workspace URL |
+| `--run-id` | `-r` | Run ID. Omit for latest run. |
+| `--env` | `-e` | `prod` (default), `staging`, `ondemand` |
+| `--dbr-profile` | `-p` | Databricks CLI profile name |
+| `--source` | `-s` | `driver`, `executor`, `executor:N`, `all` (default) |
+| `--stream` | | `stderr`, `stdout`, `all` (default) |
+| `--level` | `-l` | Exact match, comma-separated: `ERROR`, `WARN`, `INFO`, `DEBUG` |
+| `--include-log4j` | | Include driver log4j files |
+| `--include-stacktrace` | | Include driver stacktrace files |
+| `--format` | `-f` | `text` or `jsonl` |
+| `--tail` | `-n` | Show only last N lines |
+| `--since` | | Logs since time (e.g. `1h`, `30m`, ISO datetime) |
+| `--focus` | | Suppress Spark/JVM noise (thread dumps, shuffle, task lifecycle) |
+
+## Step 3: Analyze the output
+
+Parse the JSONL output and look for these root cause patterns:
+
+| Pattern | Likely cause | Key fields to check |
+|---|---|---|
+| `OutOfMemoryError` / `java.lang.OutOfMemoryError` | Executor or driver memory too small | Which source (driver vs executor), heap vs off-heap |
+| `Connection refused` / `ShuffleBlockFetcher` / `TransportChannelHandler` | Network or shuffle issues, node went unhealthy | Target IP, timeout duration, which executor |
+| `RESOURCE_DOES_NOT_EXIST` | Missing table, view, or path | Resource name in error message |
+| `AnalysisException` | SQL/schema issues (column not found, type mismatch) | SQL statement or column name |
+| `HangingTaskDetector` | Data skew or stuck tasks | Task IDs, duration, which executor |
+| `FileNotFoundException` / `FileAlreadyExistsException` | Concurrent writes or stale metadata | File path |
+| `SparkException: Job aborted` | Upstream task failure cascade | Root cause in "caused by" chain |
+| `Py4JJavaError` | Python-side error propagated to JVM | Python traceback in the message |
+
+When analyzing:
+1. **Group errors by source** (driver vs specific executors)
+2. **Identify the root cause** — often the first error chronologically is the root cause; later errors are cascading failures
+3. **Note the timeline** — when errors started, how long the job ran before failing
+4. **Check for patterns across executors** — same error on all executors suggests a systemic issue; one executor suggests data skew or node problem
+
+## Step 4: Present findings and suggest next steps
+
+Structure your response as:
+
+1. **Summary**: What happened, which run, when
+2. **Errors found**: Grouped by source, with key log lines quoted
+3. **Root cause assessment**: Your best determination of why the job failed
+4. **Suggested actions** based on error type:
+
+| Error type | Suggested actions |
+|---|---|
+| OOM | Increase executor/driver memory, check for data skew, reduce partition size |
+| Shuffle/network | Enable shuffle retry settings, check cluster health, increase shuffle partitions |
+| Missing resource | Verify table/path exists, check permissions, check if upstream job ran |
+| Schema/SQL | Fix column references, check for schema evolution, verify data types |
+| Hanging tasks | Increase shuffle partitions, check for data skew, salting join keys |
+| Concurrent write | Check for overlapping job schedules, enable Delta conflict resolution |
+
+If the error is unclear, suggest:
+- Checking a specific executor's full logs (`--source executor:N`)
+- Looking at driver log4j for more context (`--include-log4j`)
+- Comparing with a previous successful run
+- Widening the log level to include WARN or INFO

dbr_logs-0.1.0/.claude-plugin/skills/dbr-logs/references/log-structure.md

@@ -0,0 +1,75 @@
+# Databricks Log Directory Structure
+
+This reference is used when falling back to raw `databricks fs` commands (when `dbr-logs` CLI is not available).
+
+## Directory layout
+
+```
+dbfs:/Volumes/catalog/schema/logs/{env}/{job_name}/{run_id}/
+├── driver/
+│   ├── stderr                           # active file (plain text)
+│   ├── stderr--2026-03-11--18-00        # rotated (plain text, NOT gzipped)
+│   ├── stderr--2026-03-11--19-00
+│   ├── stdout                           # active file (plain text)
+│   ├── stdout--2026-03-11--18-00        # rotated (plain text)
+│   ├── log4j-active.log                 # active log4j (plain text)
+│   ├── log4j-2026-03-11-17.log.gz       # rotated log4j (gzipped)
+│   ├── stacktrace.log                   # active stacktrace (plain text)
+│   └── 2026-03-11-17.stacktrace.log.gz  # rotated stacktrace (gzipped)
+├── executor/
+│   └── app-20260311170849-0000/
+│       ├── 0/
+│       │   ├── stderr                   # active file (plain text)
+│       │   ├── stderr--2026-03-11--18.gz # rotated (gzipped)
+│       │   ├── stdout                   # active file (plain text)
+│       │   └── stdout--2026-03-11--18.gz # rotated (gzipped)
+│       ├── 1/
+│       ├── 2/
+│       ...
+│       └── N/
+├── eventlog/                            # Spark event log (not targeted)
+└── init_scripts/                        # optional
+```
+
+## Key differences between driver and executor logs
+
+| Property | Driver | Executor |
+|---|---|---|
+| Rotated stderr/stdout | `stderr--YYYY-MM-DD--HH-MM` (plain text) | `stderr--YYYY-MM-DD--HH.gz` (gzipped) |
+| Additional log files | `log4j-*.log.gz`, `stacktrace.log*` (may be absent) | None |
+| Executor hierarchy | N/A | `app-{id}/{executor_num}/` |
+| Presence | Always present | Only on multi-node jobs |
+
+## Not all files are present in every run
+
+Some driver directories have only `stderr`/`stdout` (no log4j, no stacktrace). Some jobs have no `executor/` directory at all. Always discover what exists rather than assuming a fixed structure.
+
+## Environments
+
+- `prod` — production jobs
+- `staging` — staging jobs
+- `ondemand` — ad-hoc runs
+
+## Fallback workflow using raw Databricks CLI
+
+When `dbr-logs` is not available, use these commands to manually navigate the log tree:
+
+```bash
+# 1. Find the latest run directory
+databricks fs ls "dbfs:/Volumes/catalog/schema/logs/prod/<job-name>/" | tail -1
+
+# 2. List available log sources
+databricks fs ls "dbfs:/Volumes/catalog/schema/logs/prod/<job-name>/<run-id>/"
+
+# 3. Read driver stderr (most useful starting point)
+databricks fs cat "dbfs:/Volumes/catalog/schema/logs/prod/<job-name>/<run-id>/driver/stderr"
+
+# 4. List executor directories (if they exist)
+databricks fs ls "dbfs:/Volumes/catalog/schema/logs/prod/<job-name>/<run-id>/executor/"
+# Then drill into: app-{id}/{executor_num}/stderr
+
+# 5. For gzipped files, download and decompress locally
+databricks fs cp "dbfs:/path/to/file.gz" /tmp/logfile.gz && gunzip -c /tmp/logfile.gz
+```
+
+Note: Without `dbr-logs`, you lose chronological merging across sources, level filtering, and regex grep. You must manually navigate each source and file.

dbr_logs-0.1.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      dev-dependencies:
+        patterns:
+          - "pytest*"
+          - "ruff"
+          - "mypy"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

dbr_logs-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Format check
+        run: uv run ruff format --check src/ tests/
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Test
+        run: uv run pytest --cov=dbr_logs --cov-report=term-missing

dbr_logs-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,70 @@
+name: Release & Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*
+
+  publish:
+    name: Publish to PyPI
+    if: github.repository == 'zencity/databricks-logs-reader'
+    needs: [build, github-release]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dbr-logs
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

dbr_logs-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.idea/*
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.pyc
+src/dbr_logs/_version.py
+.claude/settings.local.json

dbr_logs-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

dbr_logs-0.1.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

dbr_logs-0.1.0/CLAUDE.md

@@ -0,0 +1,29 @@
+# dbr-logs
+
+CLI tool for fetching and displaying Databricks job logs from Unity Catalog Volumes.
+
+## Commands
+
+```bash
+uv sync --dev                             # Install dependencies
+uv run python -m pytest                   # Run tests (74 tests)
+uv run ruff check src/ tests/             # Lint
+uv run ruff format --check src/ tests/    # Format check (add --fix to auto-format)
+uv run python -m mypy src/                # Type check
+```
+
+## Architecture
+
+Pipeline: `cli.py` -> `resolver.py` -> `discovery.py` -> `fetcher.py` -> `parser.py` -> `merger.py` -> `noise.py` -> `filters.py` -> `formatter.py`
+
+- `databricks_client.py` - SOLE file importing `databricks.sdk`. All other modules use the adapter.
+- `models.py` - Data models with `StrEnum` types (`SourceType`, `Stream`) and `logging` level ints
+- `config.py` - Profile/config management via `~/.config/dbr-logs/config.toml`
+
+## Gotchas
+
+- **src layout**: Package lives in `src/dbr_logs/` — IDEs may need `src/` marked as source root
+- `databricks-sdk` has incomplete type stubs — `databricks_client.py` has `ignore_errors = true` in mypy config
+- Driver rotated log files are plain text; executor rotated files are `.gz`
+- Level values are `logging.ERROR`/`logging.WARNING` ints, not strings
+- All CI must pass: ruff check + ruff format --check + mypy strict + pytest

dbr_logs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zencity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dbr_logs-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: dbr-logs
+Version: 0.1.0
+Summary: Fetch and display Databricks job logs from Unity Catalog Volumes
+Project-URL: Homepage, https://github.com/zencity/databricks-logs-reader
+Project-URL: Repository, https://github.com/zencity/databricks-logs-reader
+Project-URL: Issues, https://github.com/zencity/databricks-logs-reader/issues
+Author-email: alonisser <alonisser@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: databricks-sdk>=0.20.0
+Description-Content-Type: text/markdown
+
+# dbr-logs
+
+Fetch and display Databricks job logs from Unity Catalog Volumes.
+
+Merges driver and executor logs chronologically with source labels, so you can pipe them to `grep`, `jq`, or feed them to an LLM.
+
+## Why
+
+Debugging a failed Databricks job means navigating a deeply nested, inconsistently structured log directory tree:
+
+```
+dbfs:/Volumes/catalog/schema/logs/prod/my-spark-job/0311-170011-t5450avl/
+├── driver/
+│   ├── stderr
+│   ├── stderr--2026-03-11--18-00        # rotated, plain text
+│   ├── stderr--2026-03-11--19-00        # rotated, plain text
+│   ├── stdout
+│   ├── log4j-active.log
+│   └── log4j-2026-03-11-17.log.gz      # rotated, gzipped
+├── executor/
+│   └── app-20260311170849-0000/         # opaque app ID
+│       ├── 0/
+│       │   ├── stderr
+│       │   ├── stderr--2026-03-11--18.gz   # rotated, gzipped
+│       │   └── stdout
+│       ├── 1/
+│       ├── 2/
+│       ...
+│       └── 8/
+└── eventlog/
+```
+
+The manual process to find what went wrong:
+
+1. **Find the run** — run IDs are opaque strings like `0311-170011-t5450avl`, not human-readable
+2. **Navigate the tree** — driver logs, executor logs, or both? Which of the 9 executors had the error?
+3. **Handle mixed compression** — driver rotated files are plain text, executor rotated files are `.gz`. You need to `databricks fs cp` + `gunzip` to read them
+4. **Concatenate rotated files** — a single stream is split across the active file and multiple rotated files that must be read in chronological order
+5. **Repeat across executors** — for a job with 9 executors, that's potentially 9 x 4 files to check
+6. **Cross-reference timestamps** — the root cause is often in one source, but the symptoms appear in another
+
+For background on how Python logging works in Databricks and why it ends up in this structure, see [Everything You Wanted to Know About Python Logging in Databricks](https://medium.com/python-in-plain-english/everything-you-wanted-to-know-about-python-logging-in-databricks-0c64da6f56c9).
+
+There are heavier alternatives — Databricks' own [Practitioner's Ultimate Guide to Scalable Logging](https://www.databricks.com/blog/practitioners-ultimate-guide-scalable-logging) describes a full logging pipeline, and you could also route Databricks logs to Datadog or similar observability platforms. But these solutions carry significant ongoing costs and infrastructure overhead for something most teams only need occasionally when debugging a failed job. `dbr-logs` is a zero-cost, zero-infrastructure alternative: install a CLI tool, run one command, get your answer.
+
+`dbr-logs` replaces the manual process with a single command. It discovers the log structure, downloads and decompresses all files, merges everything chronologically with source labels, and lets you filter by level, source, or regex.
+
+## Prerequisites
+
+- **Python 3.11+** (tested on 3.11, 3.12, 3.13, 3.14)
+- **Databricks CLI** configured with at least one profile in `~/.databrickscfg` ([setup guide](https://docs.databricks.com/dev-tools/cli/index.html))
+- **Unity Catalog Volumes** log destination configured on your Databricks jobs (`cluster_log_conf` pointing to a Volumes path)
+
+## Installation
+
+```bash
+# Install as a CLI tool with uv (recommended)
+uv tool install dbr-logs
+
+# Or with pipx (isolated environment)
+pipx install dbr-logs
+
+# Or with pip (use --user to install globally without affecting your venv)
+pip install --user dbr-logs
+
+# Or run directly without installing
+uvx dbr-logs <job-name>
+```
+
+## Usage
+
+```bash
+# Fetch logs for the latest run of a job
+dbr-logs my-job-name
+
+# Fetch logs from a specific run
+dbr-logs my-job-name --run-id 12345
+
+# Use a Databricks workspace URL
+dbr-logs "https://dbc-xxx.cloud.databricks.com/jobs/12345/runs/67890?o=123"
+
+# Show only errors
+dbr-logs my-job-name --level ERROR
+
+# Focus on application logs (suppress Spark/JVM noise)
+dbr-logs my-job-name --focus
+
+# Show only executor logs
+dbr-logs my-job-name --source executor
+
+# Show last 50 lines from a specific executor
+dbr-logs my-job-name --source executor:3 --tail 50
+
+# JSONL output for piping to jq
+dbr-logs my-job-name --format jsonl | jq '.level'
+
+# Logs since last hour
+dbr-logs my-job-name --since 1h
+```
+
+## Claude Code Integration
+
+`dbr-logs` includes a Claude Code plugin so you can fetch and analyze logs directly from a Claude conversation.
+
+### Install the plugin
+
+```bash
+# Option 1: Claude Code Plugin
+/plugin add zencity/databricks-logs-reader
+
+# Option 2: skills.sh (works with Claude Code, Cursor, Windsurf, etc.)
+npx skills add zencity/databricks-logs-reader
+```
+
+The CLI tool still needs to be installed separately (`pip install dbr-logs` or `uv tool install dbr-logs`), but the skill can also use `uvx` as a zero-install fallback.
+
+### Example interaction
+
+```
+You: check the logs for my-spark-job
+
+Claude:
+  Runs: dbr-logs my-spark-job --level ERROR,WARN --focus --format jsonl
+  Analyzes output, then responds:
+
+  "The latest run (0311-170011-t5450avl) has 3 errors:
+
+  - driver/stderr: TransportChannelHandler connection timeout to 10.177.10.232 after 600s
+  - executor/0-7 stderr: HangingTaskDetector reports tasks 140953, 140957 stuck for 10+ min
+
+  Root cause: Shuffle read stall — executors are hanging on remote block fetches.
+
+  Suggested actions:
+  - Check executor at 10.177.10.232 for resource pressure
+  - Enable spark.shuffle.io.retryWait / spark.shuffle.io.maxRetries
+  - Review shuffle partitions to reduce per-task data volume"
+```
+
+## Options
+
+| Option | Short | Description |
+|---|---|---|
+| `--run-id` | `-r` | Databricks run ID (numeric). Defaults to latest run. |
+| `--env` | `-e` | Environment: prod, staging, ondemand. Default: prod. |
+| `--dbr-profile` | `-p` | Databricks CLI profile name. |
+| `--source` | `-s` | `driver`, `executor`, `executor:N`, or `all` (default). |
+| `--stream` | | `stderr`, `stdout`, or `all` (default). |
+| `--level` | `-l` | Exact match, comma-separated: ERROR, WARN, INFO, DEBUG. |
+| `--include-log4j` | | Include driver log4j files. |
+| `--include-stacktrace` | | Include driver stacktrace files. |
+| `--format` | `-f` | `text` (default) or `jsonl`. |
+| `--tail` | `-n` | Show only last N lines. |
+| `--since` | | Show logs since time (e.g. `1h`, `30m`, ISO datetime). |
+| `--focus` | | Suppress Spark/JVM noise (thread dumps, shuffle, task lifecycle). |
+
+## Configuration
+
+On first run with multiple Databricks profiles, you'll be prompted to select a default. Config is saved to `~/.config/dbr-logs/config.toml`.
+
+## Releasing
+
+Version is derived from git tags via [hatch-vcs](https://github.com/ofek/hatch-vcs) — no version string to maintain in source code.
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+This triggers the CI pipeline which: builds the package -> creates a GitHub Release with auto-generated notes -> publishes to PyPI.
+
+## Limitations
+
+- Only Unity Catalog Volumes log destinations are supported. S3 destinations are not yet supported.
+- Jobs must have `cluster_log_conf` configured.