Metadata-Version: 2.4
Name: snakemake-logger-plugin-snakesee
Version: 0.1.1
Summary: Snakemake logger plugin for snakesee workflow monitoring
Project-URL: Homepage, https://github.com/nh13/snakesee
Project-URL: Repository, https://github.com/nh13/snakesee
Author-email: Nils Homer <nils@fulcrumgenomics.com>
License-Expression: MIT
Keywords: logger,monitor,plugin,snakemake,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.11
Requires-Dist: snakemake-interface-logger-plugins>=1.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# snakemake-logger-plugin-snakesee

A Snakemake logger plugin that integrates with [snakesee](https://github.com/nh13/snakesee) for enhanced workflow monitoring.

## Overview

This plugin captures real-time workflow events directly from Snakemake's execution engine and writes them to a JSONL file that snakesee can read. This provides more accurate and timely job status information than log parsing alone.

## Installation

```bash
pip install snakemake-logger-plugin-snakesee
```

Or install alongside snakesee:

```bash
pip install snakesee snakemake-logger-plugin-snakesee
```

## Usage

Run Snakemake with the snakesee logger:

```bash
snakemake --logger snakesee --cores 4
```

In another terminal, run snakesee to monitor:

```bash
snakesee watch
```

The plugin writes workflow events to `.snakesee_events.jsonl` in the workflow directory. Snakesee automatically detects and reads these events for real-time updates.

## Benefits

Using the logger plugin provides:

- **Instant job detection**: Jobs are reported immediately when they start/finish, not when log lines are parsed
- **Accurate timing**: Job durations are calculated from actual execution timestamps
- **Direct wildcard access**: Wildcard values come directly from Snakemake, not regex parsing
- **Reliable error tracking**: Failed jobs are detected via Snakemake events, not log patterns

## Configuration

| Setting | Default | Description |
|---------|---------|-------------|
| `event_file` | `.snakesee_events.jsonl` | Path to event file (relative to workflow directory) |
| `buffer_size` | `1` | Events to buffer before flush (1 = immediate) |

## Event Types

The plugin emits the following event types:

| Event | Description |
|-------|-------------|
| `workflow_started` | Workflow initialization |
| `job_submitted` | Job queued for execution |
| `job_started` | Job execution began |
| `job_finished` | Job completed successfully |
| `job_error` | Job failed |
| `progress` | Overall progress update |

## Event File Format

Events are written as JSON Lines (one JSON object per line):

```jsonl
{"event_type":"workflow_started","timestamp":1703001234.123}
{"event_type":"job_submitted","timestamp":1703001235.0,"job_id":1,"rule_name":"align","wildcards":{"sample":"A"}}
{"event_type":"job_started","timestamp":1703001235.5,"job_id":1}
{"event_type":"job_finished","timestamp":1703001335.5,"job_id":1,"duration":100.0}
{"event_type":"progress","timestamp":1703001335.6,"completed_jobs":1,"total_jobs":10}
```

## Backward Compatibility

Snakesee works with or without this plugin:

- **Without plugin**: Uses log parsing and metadata files (existing behavior)
- **With plugin**: Uses real-time events for enhanced accuracy

The plugin is completely optional - snakesee will automatically use events when available and fall back to log parsing otherwise.

## Requirements

- Python 3.11+
- Snakemake 8.0+ (for logger plugin support)
- snakemake-interface-logger-plugins >= 1.0.0

## License

MIT
