chore: daily sync of plugin metadata and READMEs [automated]

Author: github-actions[bot]

plugins/advanced-alchemy.yml

@@ -16,7 +16,7 @@ compatibility:
   litestar: '>=2.0.0'
 icon: advanced-alchemy.png
 stars: 693
-monthly_downloads: 109904
+monthly_downloads: 115882
 latest_version: 1.8.0
 updated_at: '2025-10-28T21:01:30'
 created_at: '2023-09-17T17:39:42'

plugins/litestar-asyncpg.yml

@@ -16,7 +16,7 @@ compatibility:
   litestar: '>=2.0.0'
 icon: litestar-asyncpg.svg
 stars: 14
-monthly_downloads: 801
+monthly_downloads: 663
 latest_version: 0.5.0
 updated_at: '2025-06-24T16:45:09'
 created_at: '2023-10-01T23:31:27'

plugins/litestar-granian.yml

@@ -16,7 +16,7 @@ compatibility:
   litestar: '>=2.0.0'
 icon: litestar-granian.png
 stars: 38
-monthly_downloads: 15296
+monthly_downloads: 15952
 latest_version: 0.14.2
 updated_at: '2025-08-06T19:54:57'
 created_at: '2023-10-02T01:42:04'

plugins/litestar-htmx.yml

@@ -16,7 +16,7 @@ compatibility:
   litestar: '>=2.0.0'
 icon: litestar-htmx.svg
 stars: 12
-monthly_downloads: 1067484
+monthly_downloads: 1094616
 latest_version: 0.5.0
 updated_at: '2025-06-11T21:19:45'
 created_at: '2024-10-20T17:49:03'

plugins/litestar-saq.yml

@@ -16,9 +16,9 @@ compatibility:
   litestar: '>=2.0.0'
 icon: _default_icon.svg
 stars: 26
-monthly_downloads: 19121
-latest_version: 0.5.3
-updated_at: '2025-05-05T14:54:31'
+monthly_downloads: 22476
+latest_version: 0.6.0
+updated_at: '2025-12-02T23:39:38'
 created_at: '2023-10-04T03:57:48'
 python_compatibility_raw: '>=3.9'
 python_compatibility:

plugins/litestar-vite.yml

@@ -16,7 +16,7 @@ compatibility:
   litestar: '>=2.0.0'
 icon: litestar-vite.svg
 stars: 26
-monthly_downloads: 14278
+monthly_downloads: 15952
 latest_version: 0.14.2
 updated_at: '2025-08-06T19:54:57'
 created_at: '2023-10-02T01:42:04'

plugins/sqlspec.yml

@@ -16,7 +16,7 @@ compatibility:
   litestar: '>=2.0.0'
 icon: _default_icon.svg
 stars: 48
-monthly_downloads: 2487
+monthly_downloads: 2510
 latest_version: 0.31.0
 updated_at: '2025-11-25T15:19:25'
 created_at: '2024-10-30T00:48:46'

readmes/litestar-saq.md

@@ -6,21 +6,29 @@
 pip install litestar-saq
 ```
 
+For OpenTelemetry support:
+
+```shell
+pip install litestar-saq[otel]
+```
+
 ## Usage
 
 Here is a basic application that demonstrates how to use the plugin.
 
 ```python
-from __future__ import annotations
-
 from litestar import Litestar
-
 from litestar_saq import QueueConfig, SAQConfig, SAQPlugin
 
-saq = SAQPlugin(config=SAQConfig(dsn="redis://localhost:6397/0", queue_configs=[QueueConfig(name="samples")]))
+saq = SAQPlugin(
+    config=SAQConfig(
+        use_server_lifespan=True,
+        queue_configs=[
+            QueueConfig(name="samples", dsn="redis://localhost:6379/0")
+        ],
+    )
+)
 app = Litestar(plugins=[saq])
-
-
 ```
 
 You can start a background worker with the following command now:
@@ -29,7 +37,7 @@ You can start a background worker with the following command now:
 litestar --app-dir=examples/ --app basic:app workers run
 Using Litestar app from env: 'basic:app'
 Starting SAQ Workers ──────────────────────────────────────────────────────────────────
-INFO - 2023-10-04 17:39:03,255 - saq - worker - Worker starting: Queue<redis=Redis<ConnectionPool<Connection<host=localhost,port=6397,db=0>>>, name='samples'>
+INFO - 2023-10-04 17:39:03,255 - saq - worker - Worker starting: Queue<redis=Redis<ConnectionPool<Connection<host=localhost,port=6379,db=0>>>, name='samples'>
 INFO - 2023-10-04 17:39:06,545 - saq - worker - Worker shutting down
 ```
 
@@ -39,7 +47,7 @@ You can also start the process for only specific queues. This is helpful if you
 litestar --app-dir=examples/ --app basic:app workers run --queues sample
 Using Litestar app from env: 'basic:app'
 Starting SAQ Workers ──────────────────────────────────────────────────────────────────
-INFO - 2023-10-04 17:39:03,255 - saq - worker - Worker starting: Queue<redis=Redis<ConnectionPool<Connection<host=localhost,port=6397,db=0>>>, name='samples'>
+INFO - 2023-10-04 17:39:03,255 - saq - worker - Worker starting: Queue<redis=Redis<ConnectionPool<Connection<host=localhost,port=6379,db=0>>>, name='samples'>
 INFO - 2023-10-04 17:39:06,545 - saq - worker - Worker shutting down
 ```
 
@@ -49,16 +57,59 @@ If you are starting the process for only specific queues and still want to read
 import os
 from saq import Queue
 
-
 def get_queue_directly(queue_name: str, redis_url: str) -> Queue:
     return Queue.from_url(redis_url, name=queue_name)
 
 redis_url = os.getenv("REDIS_URL")
 queue = get_queue_directly("queue-in-other-process", redis_url)
+
 # Get queue info
 info = await queue.info(jobs=True)
+
 # Enqueue new task
-queue.enqueue(
-    ....
+await queue.enqueue("task_name", arg1="value1")
+```
+
+## Monitored Jobs
+
+For long-running tasks, use the `monitored_job` decorator to automatically send heartbeats and prevent SAQ from marking jobs as stuck:
+
+```python
+from litestar_saq import monitored_job
+
+@monitored_job()  # Auto-calculates interval from job.heartbeat
+async def long_running_task(ctx):
+    await process_large_dataset()
+    return {"status": "complete"}
+
+@monitored_job(interval=30.0)  # Explicit 30-second interval
+async def train_model(ctx, model_id: str):
+    for epoch in range(100):
+        await train_epoch(model)
+    return {"model_id": model_id}
+```
+
+## OpenTelemetry Integration
+
+litestar-saq supports optional OpenTelemetry instrumentation for distributed tracing.
+
+### Configuration
+
+```python
+from litestar_saq import SAQConfig, QueueConfig
+
+config = SAQConfig(
+    queue_configs=[QueueConfig(dsn="redis://localhost:6379/0")],
+    enable_otel=None,  # Auto-detect (default) - enabled if OTEL installed AND Litestar OpenTelemetryPlugin is active
+    # enable_otel=True,  # Force enable (raises error if not installed)
+    # enable_otel=False,  # Force disable
 )
 ```
+
+When enabled, the plugin creates:
+
+- **CONSUMER spans** for job processing
+- **PRODUCER spans** for job enqueue operations
+- **Automatic context propagation** across process boundaries
+
+Spans follow [OpenTelemetry messaging semantic conventions](https://opentelemetry.io/docs/specs/semconv/messaging/) with `messaging.system = "saq"`.