sentry-tool 0.1.0__tar.gz

sentry_tool-0.1.0/.env.template

@@ -0,0 +1,28 @@
+# Sentry Tool Environment Configuration Template
+# Copy to .envrc and fill in your values
+# NEVER commit .envrc with real credentials
+#
+# NOTE: The recommended approach is to use TOML profiles in
+# ~/.config/sentry-tool/config.toml (see README.md).
+# Environment variables below override profile values when set.
+
+# === PROFILE SELECTION ===
+
+# Select a named profile (overrides default_profile in config.toml)
+#SENTRY_PROFILE=my-profile
+
+# === OVERRIDES (optional, override active profile values) ===
+
+# Sentry API authentication token
+# Get from: Sentry Settings > Account > API > Auth Tokens
+# Required scopes: project:read, event:read
+#SENTRY_AUTH_TOKEN=sntrys_...
+
+# Sentry instance URL
+#SENTRY_URL=https://sentry.io
+
+# Organization slug
+#SENTRY_ORG=my-org
+
+# Default project slug
+#SENTRY_PROJECT=my-project

sentry_tool-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,219 @@
+# Contributing to Sentry Tool
+
+Thank you for your interest in contributing to Sentry Tool!
+
+## Development Setup
+
+### Prerequisites
+
+- Python >= 3.13
+- uv package manager
+- direnv (optional, for .envrc support)
+
+### Initial Setup
+
+```bash
+# Navigate to project directory
+cd sentry-tool
+
+# Install dependencies (including dev dependencies)
+uv sync --group dev
+
+# Install pre-commit hooks (if configured at repository level)
+pre-commit install
+
+# Verify installation
+uv run sentry-tool --help
+```
+
+### Environment Configuration
+
+Create a `.envrc` file for local development (never commit this file):
+
+```bash
+# .envrc (example)
+export SENTRY_AUTH_TOKEN=your_auth_token_here
+export SENTRY_URL=https://sentry.io
+export SENTRY_ORG=your-org
+export SENTRY_PROJECT=your-project
+```
+
+**Security:** Never commit `.envrc` with real credentials. Use the provided `.env.template` as a guide.
+
+## Development Workflow
+
+### Running the CLI Locally
+
+```bash
+# Run any command
+uv run sentry-tool list
+uv run sentry-tool show ISSUE-ID
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov
+
+# Run specific test file
+uv run pytest tests/test_cli.py
+
+# Run with verbose output
+uv run pytest -v
+```
+
+### Code Quality
+
+Before committing, ensure all quality checks pass:
+
+```bash
+# Stage your changes first
+git add <files>
+
+# Run linting
+uv run ruff check src tests
+
+# Auto-fix issues
+uv run ruff check --fix src tests
+
+# Format code
+uv run ruff format src tests
+
+# Type checking (source only, not tests)
+uv run mypy src
+
+# Run pre-commit hooks on staged files
+pre-commit run --files $(git diff --cached --name-only)
+```
+
+**Quality Gate:** All of the following must pass before committing:
+- pytest (all tests pass)
+- ruff check (no linting errors)
+- mypy (no type errors)
+- pre-commit hooks (all hooks pass)
+
+### Adding Dependencies
+
+```bash
+# Add runtime dependency
+uv add package-name
+
+# Add dev dependency
+uv add --group dev package-name
+
+# Remove dependency
+uv remove package-name
+
+# Update all dependencies
+uv sync --upgrade
+```
+
+**Always commit `uv.lock`** after changing dependencies to ensure reproducible builds.
+
+## Code Style Guidelines
+
+### General Principles
+
+- Follow PEP 8 style guide
+- Use type hints for all function signatures
+- Write descriptive docstrings for public APIs
+- Keep functions focused and small
+- Prefer composition over inheritance
+
+### CLI Command Structure
+
+When adding new commands:
+
+```python
+@app.command()
+def new_command(
+    arg: str = typer.Argument(..., help="Argument description"),
+    opt: str = typer.Option("default", "--option", "-o", help="Option description"),
+):
+    """
+    Brief command description.
+
+    Longer description with usage examples.
+
+    Examples:
+        sentry-tool new-command value
+        sentry-tool new-command value --option custom
+    """
+    ...
+```
+
+### Error Handling
+
+- Use appropriate exit codes (see `ExitCode` enum in patterns)
+- Write errors to stderr: `typer.echo("Error: ...", err=True)`
+- Provide actionable error messages
+- Never expose stack traces to users (unless --debug flag)
+
+### Testing
+
+- Write tests for all new features
+- Use `requests-mock` for mocking Sentry API calls
+- Aim for >80% code coverage
+- Test both success and error paths
+
+## Pull Request Process
+
+1. **Create a branch** for your feature or fix
+2. **Make your changes** following the style guide
+3. **Write tests** for new functionality
+4. **Run quality checks** (pytest, ruff, mypy, pre-commit)
+5. **Update documentation** if needed (README, docstrings)
+6. **Commit with clear message** describing the change
+7. **Push and create PR** with detailed description
+
+### Commit Message Format
+
+```
+type: brief description (50 chars max)
+
+Longer description if needed, explaining why the change
+was made and any important context.
+
+Examples:
+- feat: add support for filtering issues by level
+- fix: handle 404 errors gracefully in show command
+- docs: update README with new configuration options
+- test: add tests for tag analysis command
+```
+
+## Testing Guidelines
+
+### Unit Tests
+
+- Test individual functions and methods
+- Mock external dependencies (Sentry API)
+- Focus on business logic
+
+### Integration Tests
+
+- Test command-line interface end-to-end
+- Use `typer.testing.CliRunner`
+- Mock Sentry API responses
+
+### Test Organization
+
+```
+tests/
+├── conftest.py          # Shared fixtures
+├── test_cli.py          # CLI command tests
+├── test_client.py       # API client tests
+└── test_config.py       # Configuration tests
+```
+
+## Getting Help
+
+- Check existing issues and PRs
+- Ask questions in issues or discussions
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

sentry_tool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vlad Korolev
+
+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.

sentry_tool-0.1.0/PKG-INFO

@@ -0,0 +1,404 @@
+Metadata-Version: 2.4
+Name: sentry-tool
+Version: 0.1.0
+Summary: CLI tool for querying and managing Sentry issues
+Project-URL: Homepage, https://github.com/vladistan/sentry-tool
+Project-URL: Repository, https://github.com/vladistan/sentry-tool
+Project-URL: Issues, https://github.com/vladistan/sentry-tool/issues
+Project-URL: Source, https://github.com/vladistan/sentry-tool
+Project-URL: Documentation, https://github.com/vladistan/sentry-tool#readme
+Author-email: Vlad Korolev <vlad@arsenale.bio>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sentry-sdk>=2.0.0
+Requires-Dist: structlog>=24.0
+Requires-Dist: tenacity>=8.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: requests-mock>=1.11.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: types-requests>=2.31.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sentry Tool
+
+CLI tool for querying and managing Sentry issues.
+
+## Overview
+
+Sentry Tool provides a command-line interface for interacting with Sentry's API to query issues, view events, and analyze error patterns. It's designed for DevOps engineers, developers, and SREs who need quick CLI access to Sentry data.
+
+## Features
+
+- **List issues**: View recent issues in a project or across all projects
+- **Show issue details**: Get comprehensive information about specific issues
+- **View events**: Examine event details and stacktraces
+- **List events**: See recent events for an issue
+- **Tag analysis**: Analyze tag distributions across issues
+- **List projects**: View all projects in an organization
+- **Open in browser**: Quick-launch Sentry web UI
+- **Multi-instance support**: TOML-based profiles for multiple Sentry instances
+- **Configuration management**: Validate connectivity, list projects across profiles
+
+## Installation
+
+### Requirements
+
+- Python >= 3.13
+- uv package manager
+
+### Setup
+
+```bash
+# Clone or navigate to the sentry-tool directory
+cd sentry-tool
+
+# Install dependencies
+uv sync
+
+# Install dev dependencies (optional)
+uv sync --group dev
+```
+
+## Configuration
+
+Sentry Tool supports a TOML-based profile system for managing multiple Sentry instances, with environment variable overrides for flexibility.
+
+### Profile Configuration (Recommended)
+
+Create a TOML configuration file at `~/.config/sentry-tool/config.toml`:
+
+```toml
+default_profile = "my-sentry"
+
+[profiles.my-sentry]
+url = "https://sentry.example.com"
+org = "my-org"
+project = "my-project"
+auth_token = "sntrys_..."
+
+[profiles.cloud]
+url = "https://sentry.io"
+org = "my-cloud-org"
+project = "web-app"
+auth_token = "sntrys_..."
+```
+
+Each profile defines:
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `url` | Sentry instance URL | `https://sentry.io` |
+| `org` | Organization slug | `sentry` |
+| `project` | Default project slug | *(none)* |
+| `auth_token` | API authentication token | *(required)* |
+
+### Environment Variable Overrides
+
+Environment variables override profile values. This is useful for CI/CD or temporary overrides.
+
+| Variable | Overrides | Description |
+|----------|-----------|-------------|
+| `SENTRY_AUTH_TOKEN` | `auth_token` | API authentication token |
+| `SENTRY_URL` | `url` | Sentry instance URL |
+| `SENTRY_ORG` | `org` | Organization slug |
+| `SENTRY_PROJECT` | `project` | Default project slug |
+| `SENTRY_PROFILE` | *(profile selection)* | Use this profile instead of default |
+
+### Getting a Sentry Auth Token
+
+1. Log into your Sentry instance
+2. Navigate to Settings > Account > API > Auth Tokens
+3. Create a new token with appropriate scopes (at minimum: `project:read`, `event:read`)
+4. Add the token to your profile configuration or set `SENTRY_AUTH_TOKEN`
+
+### Verifying Configuration
+
+```bash
+# Show current configuration and all profiles
+sentry-tool config show
+
+# Verify connectivity to all profiles
+sentry-tool config validate
+```
+
+## Global Flags
+
+These flags are available on the root command and apply to all subcommands.
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--profile` | `-P` | Use a named profile from config |
+| `--project` | `-p` | Override the project slug from the active profile |
+
+Most commands also accept:
+
+| Flag | Short | Values | Description |
+|------|-------|--------|-------------|
+| `--format` | `-f` | `table`, `json` | Output format (default: `table`) |
+
+## Usage
+
+### `list` - List Recent Issues
+
+List recent issues in a project. Use `--all-projects/-A` to list across all projects.
+
+```bash
+sentry-tool list
+sentry-tool list -p my-project -n 5
+sentry-tool list -s unresolved
+sentry-tool list -A
+sentry-tool list --format json
+```
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--project` | `-p` | Project slug | profile default |
+| `--all-projects` | `-A` | List issues across all projects (mutually exclusive with `-p`) | |
+| `--max` | `-n` | Maximum issues to show | `10` |
+| `--status` | `-s` | Filter by status: `resolved`, `unresolved`, `muted` | |
+| `--format` | `-f` | Output format: `table`, `json` | `table` |
+
+---
+
+### `show` - Show Issue Details
+
+Show comprehensive details for a specific issue.
+
+```bash
+sentry-tool show 24
+sentry-tool show OTEL-COLLECTOR-Q
+sentry-tool show 24 --format json
+```
+
+| Argument | Description |
+|----------|-------------|
+| `ISSUE_ID` | Issue ID (numeric like `24` or short ID like `OTEL-COLLECTOR-Q`) |
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--format` | `-f` | Output format: `table`, `json` | `table` |
+
+**Output includes:** Title, Status, Level, Priority, Event count, First/Last seen, Tags, Release info, Permalink
+
+---
+
+### `event` - Show Event Details
+
+Show event details for an issue. By default shows the latest event.
+
+```bash
+sentry-tool event 24
+sentry-tool event OTEL-COLLECTOR-Q
+sentry-tool event 24 -e abc123...
+sentry-tool event 24 -c
+sentry-tool event 24 --format json
+```
+
+| Argument | Description |
+|----------|-------------|
+| `ISSUE_ID` | Issue ID (numeric or short ID) |
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--event` | `-e` | Specific event ID | latest |
+| `--context` | `-c` | Show only context/stacktrace | |
+| `--format` | `-f` | Output format: `table`, `json` | `table` |
+
+**Output includes:** Event ID, Title, Message, Date, Server, SDK info, Release, Context, Exception with stacktrace
+
+---
+
+### `events` - List Recent Events
+
+List recent events for an issue.
+
+```bash
+sentry-tool events 24
+sentry-tool events OTEL-COLLECTOR-Q -n 5
+sentry-tool events 24 --format json
+```
+
+| Argument | Description |
+|----------|-------------|
+| `ISSUE_ID` | Issue ID (numeric or short ID) |
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--max` | `-n` | Maximum events to show | `10` |
+| `--format` | `-f` | Output format: `table`, `json` | `table` |
+
+**Output:** Table with Event ID, Date, Server
+
+---
+
+### `tags` - Show Tag Values
+
+Show tag values for an issue. Lists available tags when no tag key is provided.
+
+```bash
+sentry-tool tags OTEL-COLLECTOR-14
+sentry-tool tags OTEL-COLLECTOR-14 server_name
+sentry-tool tags OTEL-COLLECTOR-14 release
+sentry-tool tags 14 server_name --format json
+```
+
+| Argument | Description |
+|----------|-------------|
+| `ISSUE_ID` | Issue ID (numeric or short ID) |
+| `TAG_KEY` | *(optional)* Tag key to show values for (e.g., `server_name`, `release`) |
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--format` | `-f` | Output format: `table`, `json` | `table` |
+
+**Output:**
+- Without `TAG_KEY`: Table of available tags with unique value counts
+- With `TAG_KEY`: Table showing tag values with count and percentage distribution
+
+---
+
+### `list-projects` - List Projects
+
+List all projects in the configured organization.
+
+```bash
+sentry-tool list-projects
+sentry-tool list-projects --format json
+```
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--format` | `-f` | Output format: `table`, `json` | `table` |
+
+---
+
+### `open` - Open in Browser
+
+Open Sentry web UI in the default browser. Without arguments, opens the organization dashboard. With an issue ID, opens that issue directly.
+
+```bash
+sentry-tool open
+sentry-tool open 24
+```
+
+| Argument | Description |
+|----------|-------------|
+| `ISSUE_ID` | *(optional)* Issue ID to open directly |
+
+---
+
+### `config` - Configuration Management
+
+Subcommands for managing and verifying configuration.
+
+#### `config show`
+
+Display current configuration including active profile and all configured profiles.
+
+```bash
+sentry-tool config show
+sentry-tool config show --format json
+```
+
+#### `config profiles`
+
+List configured profile names with default marked.
+
+```bash
+sentry-tool config profiles
+sentry-tool config profiles --format json
+```
+
+#### `config list-projects`
+
+Enumerate Sentry projects for each configured profile. Profiles with missing auth tokens are skipped.
+
+```bash
+sentry-tool config list-projects
+sentry-tool config list-projects --format json
+```
+
+#### `config validate`
+
+Verify connectivity to all configured profiles by querying projects. Useful after initial setup.
+
+```bash
+sentry-tool config validate
+sentry-tool config validate --format json
+```
+
+All `config` subcommands accept `--format/-f` (`table` or `json`, default: `table`).
+
+---
+
+### Common Workflows
+
+**Investigate a New Issue:**
+```bash
+# 1. List recent unresolved issues
+sentry-tool list -s unresolved
+
+# 2. Show details for an issue
+sentry-tool show OTEL-COLLECTOR-14
+
+# 3. See the latest event with stack trace
+sentry-tool event OTEL-COLLECTOR-14
+
+# 4. Check which servers are affected
+sentry-tool tags OTEL-COLLECTOR-14 server_name
+```
+
+**Cross-Instance Investigation:**
+```bash
+# List issues across all projects on a specific instance
+sentry-tool -P production list -A
+
+# Compare the same project on different instances
+sentry-tool -P staging -p web-app list
+sentry-tool -P production -p web-app list
+```
+
+**Export Data for Analysis:**
+```bash
+# Get issue details as JSON
+sentry-tool show OTEL-COLLECTOR-14 --format json > issue.json
+
+# Get event details as JSON
+sentry-tool event OTEL-COLLECTOR-14 --format json > event.json
+```
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, testing, and contribution guidelines.
+
+### Quick Start
+
+```bash
+# Install with dev dependencies
+uv sync --group dev
+
+# Run tests
+uv run pytest
+
+# Type checking
+uv run mypy src
+
+# Linting
+uv run ruff check src tests
+
+# Format code
+uv run ruff format src tests
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.