snakemake-logger-plugin-stomp 0.1.0__tar.gz

snakemake_logger_plugin_stomp-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff

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

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+env:
+  PYTHON_VERSION: "3.11"
+
+jobs:
+  linting:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pixi
+        uses: prefix-dev/setup-pixi@v0.9.4
+        with:
+          cache: true
+          environments: dev
+          pixi-version: v0.63.2
+
+      - name: Check formatting
+        run: pixi run -e dev format-check
+
+      - name: Lint
+        run: pixi run -e dev lint
+
+  testing:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the code
+        uses: actions/checkout@v4
+
+      - name: Setup pixi
+        uses: prefix-dev/setup-pixi@v0.9.4
+        with:
+          cache: true
+          environments: dev
+
+      - name: Run tests with coverage
+        run: pixi run -e dev test
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage-report/coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

snakemake_logger_plugin_stomp-0.1.0/.github/workflows/conventional-prs.yml

@@ -0,0 +1,16 @@
+name: PR
+on:
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - edited
+      - synchronize
+
+jobs:
+  title-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v3.4.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

snakemake_logger_plugin_stomp-0.1.0/.github/workflows/release-please.yml

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+env:
+  PYTHON_VERSION: "3.11"
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          # In v4, configuration is typically done via .release-please-config.json
+          # But for simple Python projects, this should work with defaults
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created }}
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Check out the code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pixi
+        uses: prefix-dev/setup-pixi@v0.9.4
+        with:
+          cache: true
+          environments: dev
+          pixi-version: v0.63.2
+
+      - name: Build distribution packages
+        run: pixi run -e dev build
+
+      - name: Validate build
+        run: pixi run -e dev check-build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          print-hash: true

snakemake_logger_plugin_stomp-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Testing
+.pytest_cache/
+.coverage
+coverage-report/
+htmlcov/
+.tox/
+.nox/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Pixi
+.pixi/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Build artifacts
+dist/
+*.whl
+*.tar.gz
+
+# Legacy
+setup.cfg

snakemake_logger_plugin_stomp-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

snakemake_logger_plugin_stomp-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0](https://github.com/JeffersonLab/snakemake-logger-plugin-stomp/compare/snakemake-logger-plugin-stomp-v0.0.1...snakemake-logger-plugin-stomp-v0.1.0) (2026-03-02)
+
+
+### Features
+
+* initial plugin implementation ([4a05ede](https://github.com/JeffersonLab/snakemake-logger-plugin-stomp/commit/4a05ede3faebd045564ff2e574739b837358b690))
+
+
+### Bug Fixes
+
+* remove editable install from pixi config ([bbb2a9f](https://github.com/JeffersonLab/snakemake-logger-plugin-stomp/commit/bbb2a9ff340821cf250f68e735540813cd97c7f8))

snakemake_logger_plugin_stomp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+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.

snakemake_logger_plugin_stomp-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: snakemake-logger-plugin-stomp
+Version: 0.1.0
+Summary: Snakemake logger plugin for streaming events to STOMP message brokers
+Project-URL: Homepage, https://github.com/JeffersonLab/snakemake-logger-plugin-stomp
+Project-URL: Repository, https://github.com/JeffersonLab/snakemake-logger-plugin-stomp
+Project-URL: Documentation, https://snakemake.github.io/snakemake-plugin-catalog/plugins/logger/stomp.html
+Project-URL: Bug Tracker, https://github.com/JeffersonLab/snakemake-logger-plugin-stomp/issues
+Author-email: Anil Panta <anilpanta2@gmail.org>
+License: MIT
+License-File: LICENSE
+Keywords: activemq,logger,messaging,plugin,rabbitmq,snakemake,stomp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Requires-Python: <4.0,>=3.11
+Requires-Dist: snakemake-interface-common<2,>=1.22.0
+Requires-Dist: snakemake-interface-logger-plugins<3,>=2.0.0
+Requires-Dist: stomp-py>=8.2.0
+Description-Content-Type: text/markdown
+
+# Snakemake Logger Plugin for STOMP
+
+Send Snakemake workflow events monitoring to a STOMP message broker (ActiveMQ, RabbitMQ, etc.) in real-time.
+
+## Installation
+
+```bash
+pip install snakemake-logger-plugin-stomp
+```
+
+## Quick Start
+```bash
+snakemake --logger-plugin stomp \
+  --stomp-host localhost \
+  --stomp-port 61613 \
+  --stomp-user admin \
+  --stomp-password admin
+```
+
+Or use a profile:
+```yaml
+# profiles/stomp/config.yaml
+logger:
+  stomp:
+    host: "activemq.example.com"
+    port: 61613
+    user: "${STOMP_USER}"
+    password: "${STOMP_PASSWORD}"
+    queue: "/topic/snakemake.prod"
+```
+
+## Features
+
+  - JSON event streaming to message brokers
+  - SSL/TLS support
+  - Configurable formatters (default + JLab SWF schema)
+  - Event filtering (include/exclude)
+  - Heartbeat management
+  - Environment variable support for secrets

snakemake_logger_plugin_stomp-0.1.0/README.md

@@ -0,0 +1,39 @@
+# Snakemake Logger Plugin for STOMP
+
+Send Snakemake workflow events monitoring to a STOMP message broker (ActiveMQ, RabbitMQ, etc.) in real-time.
+
+## Installation
+
+```bash
+pip install snakemake-logger-plugin-stomp
+```
+
+## Quick Start
+```bash
+snakemake --logger-plugin stomp \
+  --stomp-host localhost \
+  --stomp-port 61613 \
+  --stomp-user admin \
+  --stomp-password admin
+```
+
+Or use a profile:
+```yaml
+# profiles/stomp/config.yaml
+logger:
+  stomp:
+    host: "activemq.example.com"
+    port: 61613
+    user: "${STOMP_USER}"
+    password: "${STOMP_PASSWORD}"
+    queue: "/topic/snakemake.prod"
+```
+
+## Features
+
+  - JSON event streaming to message brokers
+  - SSL/TLS support
+  - Configurable formatters (default + JLab SWF schema)
+  - Event filtering (include/exclude)
+  - Heartbeat management
+  - Environment variable support for secrets

snakemake_logger_plugin_stomp-0.1.0/commitlint.config.js

@@ -0,0 +1,31 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      2,
+      'always',
+      [
+        'feat',     // New feature
+        'fix',      // Bug fix
+        'docs',     // Documentation only
+        'style',    // Formatting (no code change)
+        'refactor', // Code refactoring
+        'perf',     // Performance improvement
+        'test',     // Adding/updating tests
+        'chore',    // Maintenance (build, deps, tooling)
+        'ci',       // CI/CD changes
+        'build',    // Build system changes
+        'revert',   // Revert previous commit
+      ],
+    ],
+    'type-case': [2, 'always', 'lower-case'],
+    'type-empty': [2, 'never'],
+    'subject-empty': [2, 'never'],
+    'subject-full-stop': [2, 'never', '.'],
+    'subject-case': [0], // Allow any case
+    'header-max-length': [2, 'always', 72],
+    'body-leading-blank': [1, 'always'],
+    'body-max-line-length': [2, 'always', 100],
+    'footer-leading-blank': [1, 'always'],
+  },
+};

snakemake_logger_plugin_stomp-0.1.0/docs/further.md

@@ -0,0 +1,265 @@
+# Advanced Configuration
+
+## SSL/TLS Encryption
+
+For production brokers requiring encrypted connections:
+
+**Profile configuration:**
+```yaml
+# profiles/production/config.yaml
+logger:
+  stomp:
+    host: "secure-broker.example.com"
+    port: 61614
+    use_ssl: true
+    cert_file: "/path/to/client.crt"
+    key_file: "/path/to/client.key"
+    queue: "/topic/snakemake.secure"
+```
+
+**Command line:**
+```bash
+snakemake --logger-plugin stomp \
+  --stomp-host secure-broker.example.com \
+  --stomp-port 61614 \
+  --stomp-use-ssl \
+  --stomp-cert-file /path/to/client.crt \
+  --stomp-key-file /path/to/client.key
+```
+
+## Event Filtering
+
+Control which events generate messages to reduce noise or focus on specific workflow stages.
+
+### Whitelist Approach
+
+Only send specific events:
+
+```bash
+snakemake --logger-plugin stomp \
+  --stomp-include-events "WORKFLOW_STARTED,JOB_STARTED,JOB_FINISHED,WORKFLOW_FINISHED"
+```
+
+### Blacklist Approach
+
+Exclude noisy events:
+
+```bash
+snakemake --logger-plugin stomp \
+  --stomp-exclude-events "DEBUG,PROGRESS,RESOURCES_INFO"
+```
+
+**Available events:** `WORKFLOW_STARTED`, `WORKFLOW_FINISHED`, `JOB_STARTED`, `JOB_FINISHED`, `JOB_ERROR`, `DEBUG`, `PROGRESS`, `RESOURCES_INFO`, and more.
+
+## Built-in Formatters
+
+### DefaultJSONFormatter (default)
+
+Produces flat, easy-to-parse JSON:
+
+```json
+{
+  "timestamp": "2024-01-15T14:30:00Z",
+  "hostname": "compute-node-01",
+  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
+  "event_type": "JOB_FINISHED",
+  "level": "INFO",
+  "message": "Job 5 completed successfully"
+}
+```
+
+### JLabSWFFormatter
+
+Nested schema compliant with JLab Scientific Workflow Facility standards:
+
+```json
+{
+  "schema_ref": "org.jlab.swf.event",
+  "schema_version": "1.0.0",
+  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "event_type": "SNAKEMAKE_JOB_FINISHED",
+  "event_time": "2024-01-15T14:30:00Z",
+  "source": {
+    "agent_id": "snakemake-compute-node-01",
+    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
+    "hostname": "compute-node-01"
+  },
+  "correlation": {
+    "run_number": "12345"
+  },
+  "payload": {
+    "msg": "Job 5 completed successfully",
+    "level": "INFO",
+    "name": "align_reads",
+    "jobid": 5,
+    "wildcards": {"sample": "A"},
+    "threads": 4,
+    "resources": {"mem_mb": 16000}
+  }
+}
+```
+
+**To use JLabSWFFormatter:**
+
+```bash
+snakemake --logger-plugin stomp \
+  --stomp-formatter-class "snakemake_logger_plugin_stomp.formatters.JLabSWFFormatter"
+```
+
+The `SWF_RUN_NUMBER` environment variable can be set to populate the `correlation.run_number` field for tracking related workflow runs.
+
+## Custom Formatters
+
+Create your own formatter by implementing the `BaseFormatter` interface:
+
+```python
+# my_formatter.py
+from snakemake_logger_plugin_stomp.formatters import BaseFormatter
+from datetime import UTC, datetime
+
+class MyFormatter(BaseFormatter):
+    def format(self, record, workflow_metadata):
+        return {
+            "ts": datetime.now(UTC).isoformat(),
+            "host": workflow_metadata.get("hostname"),
+            "event": str(getattr(record, "event", "UNKNOWN")),
+            "msg": record.getMessage() if hasattr(record, "getMessage") else str(record.msg),
+            "custom_field": "my_value"
+        }
+```
+
+Install your formatter in the same Python environment, then reference it:
+
+```bash
+snakemake --logger-plugin stomp \
+  --stomp-formatter-class "my_formatter.MyFormatter"
+```
+
+## Heartbeat Tuning
+
+STOMP heartbeats keep the connection alive and detect network failures. Configure intervals in milliseconds:
+
+```yaml
+logger:
+  stomp:
+    host: "broker.example.com"
+    heartbeat_send: 30000    # Client sends heartbeat every 30s (default: 10000ms = 10s)
+    heartbeat_receive: 30000 # Client expects broker heartbeat every 30s (default: 10000ms = 10s)
+```
+
+**How it works:**
+- `heartbeat_send`: How often the client sends heartbeat frames to the broker
+- `heartbeat_receive`: How often the client expects to receive heartbeat frames from the broker
+- Set to `0` to disable heartbeats entirely
+
+**Do you need heartbeats for Snakemake?**
+
+**YES, keep heartbeats enabled (default 10s)** if you have:
+- Long-running jobs (hours) with infrequent events
+- Workflows with idle periods waiting on external resources
+- Unreliable networks (cloud, VPN, cross-datacenter connections)
+- Enterprise firewalls/proxies that drop idle TCP connections
+- Production workflows where silent connection loss is unacceptable
+
+**NO, you can disable heartbeats (set to 0)** if you have:
+- Short workflows (< 30 minutes) with frequent job events
+- Localhost or same-datacenter broker (reliable network)
+- Development/testing environment
+- Jobs that start/finish frequently (events naturally keep connection alive)
+
+**Tuning guidance:**
+- **Default (10000ms = 10s)**: Good for most production workflows
+- **Increase (30000-60000ms)**: For slow/congested networks to prevent false timeouts
+- **Decrease (5000ms)**: For fast networks where you want quick failure detection
+- **Disable (0)**: Only for local testing with reliable connections
+- Both send and receive values should typically be the same
+- Brokers may negotiate the actual interval based on their own configuration
+
+**Example: Disable for local testing**
+```yaml
+logger:
+  stomp:
+    host: "localhost"
+    heartbeat_send: 0
+    heartbeat_receive: 0
+```
+
+## Queue vs Topic Destinations
+
+STOMP supports both queue (point-to-point) and topic (publish-subscribe) semantics:
+
+```yaml
+# Queue - one consumer receives each message
+queue: "/queue/snakemake.events"
+
+# Topic - all subscribers receive each message
+queue: "/topic/snakemake.broadcast"
+```
+
+Use **queues** when you want load balancing across multiple consumers. Use **topics** when multiple systems need to receive all events (e.g., monitoring + archival + alerting).
+
+## Complete Production Example
+
+A full production configuration combining SSL, event filtering, custom formatter, and heartbeat tuning:
+
+```yaml
+# profiles/production-stomp/config.yaml
+logger:
+  stomp:
+    host: "activemq.prod.internal"
+    port: 61614
+    use_ssl: true
+    cert_file: "/etc/certs/snakemake.crt"
+    key_file: "/etc/certs/snakemake.key"
+    queue: "/topic/snakemake.prod"
+    formatter_class: "snakemake_logger_plugin_stomp.formatters.JLabSWFFormatter"
+    include_events: "WORKFLOW_STARTED,JOB_STARTED,JOB_FINISHED,WORKFLOW_FINISHED,JOB_ERROR"
+    heartbeat_send: 30000
+    heartbeat_receive: 30000
+```
+
+**Usage:**
+```bash
+export STOMP_USER=workflow_user
+export STOMP_PASSWORD=secure_password
+export SWF_RUN_NUMBER=12345
+snakemake --profile profiles/production-stomp
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+If the plugin fails to connect:
+
+1. Verify the broker is running and accessible: `telnet <host> <port>`
+2. Check firewall rules allow the STOMP port
+3. Confirm credentials are correct
+4. Review broker logs for authentication errors
+
+### SSL Certificate Errors
+
+If SSL connections fail:
+
+1. Verify certificate paths are correct and readable
+2. Ensure certificates match the broker hostname
+3. Check certificate expiration dates
+4. Try with `use_ssl: false` first to isolate SSL-specific issues
+
+### No Events Appearing
+
+If events aren't reaching your consumer:
+
+1. Check event filtering settings (`include_events`/`exclude_events`)
+2. Verify the correct destination (queue vs topic)
+3. Confirm consumers are connected to the same queue/topic
+4. Review Snakemake logs for plugin connection errors
+
+### Performance Considerations
+
+For workflows with hundreds or thousands of jobs:
+
+- Use event filtering to reduce message volume
+- Consider using queues instead of topics if you don't need broadcast
+- Increase heartbeat intervals if network latency is high
+- Monitor broker memory usage and adjust configuration as needed

snakemake_logger_plugin_stomp-0.1.0/docs/intro.md

@@ -0,0 +1,67 @@
+# Snakemake Logger Plugin for STOMP
+
+Stream Snakemake workflow events to STOMP message brokers (ActiveMQ, RabbitMQ, Apollo) in real-time for monitoring, audit trails, and event-driven system integration.
+
+## Key Features
+
+- **Real-time event streaming** to STOMP-compatible message brokers
+- **SSL/TLS encryption** for secure production deployments
+- **Flexible formatters** - default flat JSON or JLab Scientific Workflow schema
+- **Event filtering** - include/exclude specific event types to reduce noise
+- **Custom formatters** - plugin your own formatter classes
+- **Environment variable support** for credentials and sensitive configuration
+
+## Installation
+
+```bash
+pip install snakemake-logger-plugin-stomp
+```
+
+## Quick Start
+
+### Command Line
+
+```bash
+snakemake --logger-plugin stomp \
+  --stomp-host localhost \
+  --stomp-port 61613 \
+  --stomp-user admin \
+  --stomp-password admin
+```
+
+### Profile Configuration
+
+```yaml
+# profiles/stomp/config.yaml
+logger:
+  stomp:
+    host: "activemq.example.com"
+    port: 61613
+    user: "${STOMP_USER}"
+    password: "${STOMP_PASSWORD}"
+    queue: "/topic/snakemake.events"
+```
+
+Then run:
+```bash
+snakemake --profile profiles/stomp
+```
+
+### Environment Variables
+
+Secure credentials using environment variables:
+
+```bash
+export SNAKEMAKE_LOGGER_STOMP_HOST=activemq.example.com
+export SNAKEMAKE_LOGGER_STOMP_USER=admin
+export SNAKEMAKE_LOGGER_STOMP_PASSWORD=secret
+snakemake --logger-plugin stomp
+```
+
+## Use Cases
+
+- **External monitoring** - Send workflow events to centralized monitoring systems
+- **Audit trails** - Create permanent records of workflow execution in message queues
+- **Event-driven automation** - Trigger downstream processes based on workflow events
+- **Team dashboards** - Build real-time dashboards showing workflow status across teams
+- **Integration** - Connect Snakemake to enterprise message bus architectures