vs-queue 0.1.0__tar.gz → 0.1.1__tar.gz

{vs_queue-0.1.0 → vs_queue-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vs-queue
-Version: 0.1.0
+Version: 0.1.1
 Summary: Pluggable async message queue library for Viveka Sutra — Redis Streams, RabbitMQ, retry, dead letter, and annotation-based consumers
 Project-URL: Homepage, https://vivekasutra.com/
 Project-URL: Source, https://github.com/vivekasutra/viveka-mula
@@ -560,6 +560,42 @@ await queue.publish("orchestrator:tasks", dlq_message)
 
 ---
 
+## Logging
+
+Both backends log consumer lifecycle and per-message activity on the provider logger
+(`vs_queue.provider.vs_redis_queue` / `vs_queue.provider.vs_rabbitmq_queue`). Every line uses a
+`Label | key=value` format.
+
+| Level | Line | When |
+|---|---|---|
+| `INFO` | `Subscribed \| queue=<q> consumer=<ClassName>` | `consumer.start()` has run and the queue / consumer group is ready — the loop is now listening |
+| `INFO` | `Message received \| queue=<q> id=<msg_id> retry_count=<n>` | Each message pulled off the queue, before `handle()` is called |
+| `DEBUG` | `Message processed \| queue=<q> id=<msg_id>` | `handle()` returned and the message was acked |
+| `INFO` | `Unsubscribed \| queue=<q> consumer=<ClassName>` | The subscribe loop exited (graceful shutdown or permanent failure) |
+| `ERROR` | `Message failed, no retry policy \| id=<msg_id> error=<e>` | `handle()` raised and no `VsRetryPolicy` was supplied |
+
+`VsQueueManager` logs lifecycle events on its own logger (`vs_queue.manager.vs_queue_manager`):
+
+| Level | Line |
+|---|---|
+| `INFO` | `Listener registered \| queue=<q> uuid=<uid>` |
+| `INFO` | `Listeners registered \| queue=<q> concurrency=<n>` |
+| `INFO` | `Listener stopped \| queue=<q> uuid=<uid>` |
+| `ERROR` | `Consumer crashed, restarting in <n>s \| queue=<q> attempt=<n> error=<e>` |
+| `CRITICAL` | `Consumer permanently failed after <n> restarts \| queue=<q> error=<e>` |
+
+`Subscribed` / `Message received` land only once the loop is actually consuming, so the absence of
+`Subscribed` after `Listener registered` means `subscribe()` is failing before it starts.
+
+Turn on the debug lines:
+
+```python
+import logging
+logging.getLogger("vs_queue").setLevel(logging.DEBUG)
+```
+
+---
+
 ## Redis Streams Backend
 
 `VsRedisQueue` implements the queue using Redis Streams (`XADD` / `XREADGROUP`). Redis Streams provide persistent, ordered, consumer-group-aware message delivery.

{vs_queue-0.1.0 → vs_queue-0.1.1}/README.md

@@ -529,6 +529,42 @@ await queue.publish("orchestrator:tasks", dlq_message)
 
 ---
 
+## Logging
+
+Both backends log consumer lifecycle and per-message activity on the provider logger
+(`vs_queue.provider.vs_redis_queue` / `vs_queue.provider.vs_rabbitmq_queue`). Every line uses a
+`Label | key=value` format.
+
+| Level | Line | When |
+|---|---|---|
+| `INFO` | `Subscribed \| queue=<q> consumer=<ClassName>` | `consumer.start()` has run and the queue / consumer group is ready — the loop is now listening |
+| `INFO` | `Message received \| queue=<q> id=<msg_id> retry_count=<n>` | Each message pulled off the queue, before `handle()` is called |
+| `DEBUG` | `Message processed \| queue=<q> id=<msg_id>` | `handle()` returned and the message was acked |
+| `INFO` | `Unsubscribed \| queue=<q> consumer=<ClassName>` | The subscribe loop exited (graceful shutdown or permanent failure) |
+| `ERROR` | `Message failed, no retry policy \| id=<msg_id> error=<e>` | `handle()` raised and no `VsRetryPolicy` was supplied |
+
+`VsQueueManager` logs lifecycle events on its own logger (`vs_queue.manager.vs_queue_manager`):
+
+| Level | Line |
+|---|---|
+| `INFO` | `Listener registered \| queue=<q> uuid=<uid>` |
+| `INFO` | `Listeners registered \| queue=<q> concurrency=<n>` |
+| `INFO` | `Listener stopped \| queue=<q> uuid=<uid>` |
+| `ERROR` | `Consumer crashed, restarting in <n>s \| queue=<q> attempt=<n> error=<e>` |
+| `CRITICAL` | `Consumer permanently failed after <n> restarts \| queue=<q> error=<e>` |
+
+`Subscribed` / `Message received` land only once the loop is actually consuming, so the absence of
+`Subscribed` after `Listener registered` means `subscribe()` is failing before it starts.
+
+Turn on the debug lines:
+
+```python
+import logging
+logging.getLogger("vs_queue").setLevel(logging.DEBUG)
+```
+
+---
+
 ## Redis Streams Backend
 
 `VsRedisQueue` implements the queue using Redis Streams (`XADD` / `XREADGROUP`). Redis Streams provide persistent, ordered, consumer-group-aware message delivery.

{vs_queue-0.1.0 → vs_queue-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vs-queue"
-version = "0.1.0"
+version = "0.1.1"
 description = "Pluggable async message queue library for Viveka Sutra — Redis Streams, RabbitMQ, retry, dead letter, and annotation-based consumers"
 readme = "README.md"
 requires-python = ">=3.11"

{vs_queue-0.1.0 → vs_queue-0.1.1}/vs_queue/provider/vs_rabbitmq_queue.py

@@ -62,6 +62,7 @@ class VsRabbitMQQueue(VsBaseQueue):
     async def subscribe(self, queue: str, consumer: VsBaseConsumer, retry_policy: Optional[VsRetryPolicy] = None) -> None:
         q = await self._channel.declare_queue(queue, durable=True)
         await consumer.start()
+        _logger.info(f"Subscribed | queue={queue} consumer={type(consumer).__name__}")
         try:
             async with q.iterator() as iterator:
                 async for amqp_message in iterator:
@@ -73,9 +74,11 @@ class VsRabbitMQQueue(VsBaseQueue):
                         headers=data["headers"],
                         payload=data["payload"],
                     )
+                    _logger.info(f"Message received | queue={queue} id={message.id} retry_count={message.retry_count}")
                     try:
                         await consumer.handle(message)
                         await amqp_message.ack()
+                        _logger.debug(f"Message processed | queue={queue} id={message.id}")
                     except Exception as e:
                         await consumer.on_error(message, e)
                         if retry_policy:
@@ -89,3 +92,4 @@ class VsRabbitMQQueue(VsBaseQueue):
                             _logger.error(f"Message failed, no retry policy | id={message.id} error={e}")
         finally:
             await consumer.stop()
+            _logger.info(f"Unsubscribed | queue={queue} consumer={type(consumer).__name__}")

{vs_queue-0.1.0 → vs_queue-0.1.1}/vs_queue/provider/vs_redis_queue.py

@@ -68,6 +68,7 @@ class VsRedisQueue(VsBaseQueue):
             pass
 
         await consumer.start()
+        _logger.info(f"Subscribed | queue={queue} consumer={type(consumer).__name__}")
         try:
             while True:
                 results = await self._client.xreadgroup(
@@ -89,9 +90,11 @@ class VsRedisQueue(VsBaseQueue):
                             headers=json.loads(data["headers"]),
                             payload=json.loads(data["payload"]),
                         )
+                        _logger.info(f"Message received | queue={queue} id={message.id} retry_count={message.retry_count}")
                         try:
                             await consumer.handle(message)
                             await self._client.xack(queue, group, msg_id)
+                            _logger.debug(f"Message processed | queue={queue} id={message.id}")
                         except Exception as e:
                             await consumer.on_error(message, e)
                             if retry_policy:
@@ -102,3 +105,4 @@ class VsRedisQueue(VsBaseQueue):
                                 _logger.error(f"Message failed, no retry policy | id={message.id} error={e}")
         finally:
             await consumer.stop()
+            _logger.info(f"Unsubscribed | queue={queue} consumer={type(consumer).__name__}")

{vs_queue-0.1.0 → vs_queue-0.1.1}/vs_queue.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vs-queue
-Version: 0.1.0
+Version: 0.1.1
 Summary: Pluggable async message queue library for Viveka Sutra — Redis Streams, RabbitMQ, retry, dead letter, and annotation-based consumers
 Project-URL: Homepage, https://vivekasutra.com/
 Project-URL: Source, https://github.com/vivekasutra/viveka-mula
@@ -560,6 +560,42 @@ await queue.publish("orchestrator:tasks", dlq_message)
 
 ---
 
+## Logging
+
+Both backends log consumer lifecycle and per-message activity on the provider logger
+(`vs_queue.provider.vs_redis_queue` / `vs_queue.provider.vs_rabbitmq_queue`). Every line uses a
+`Label | key=value` format.
+
+| Level | Line | When |
+|---|---|---|
+| `INFO` | `Subscribed \| queue=<q> consumer=<ClassName>` | `consumer.start()` has run and the queue / consumer group is ready — the loop is now listening |
+| `INFO` | `Message received \| queue=<q> id=<msg_id> retry_count=<n>` | Each message pulled off the queue, before `handle()` is called |
+| `DEBUG` | `Message processed \| queue=<q> id=<msg_id>` | `handle()` returned and the message was acked |
+| `INFO` | `Unsubscribed \| queue=<q> consumer=<ClassName>` | The subscribe loop exited (graceful shutdown or permanent failure) |
+| `ERROR` | `Message failed, no retry policy \| id=<msg_id> error=<e>` | `handle()` raised and no `VsRetryPolicy` was supplied |
+
+`VsQueueManager` logs lifecycle events on its own logger (`vs_queue.manager.vs_queue_manager`):
+
+| Level | Line |
+|---|---|
+| `INFO` | `Listener registered \| queue=<q> uuid=<uid>` |
+| `INFO` | `Listeners registered \| queue=<q> concurrency=<n>` |
+| `INFO` | `Listener stopped \| queue=<q> uuid=<uid>` |
+| `ERROR` | `Consumer crashed, restarting in <n>s \| queue=<q> attempt=<n> error=<e>` |
+| `CRITICAL` | `Consumer permanently failed after <n> restarts \| queue=<q> error=<e>` |
+
+`Subscribed` / `Message received` land only once the loop is actually consuming, so the absence of
+`Subscribed` after `Listener registered` means `subscribe()` is failing before it starts.
+
+Turn on the debug lines:
+
+```python
+import logging
+logging.getLogger("vs_queue").setLevel(logging.DEBUG)
+```
+
+---
+
 ## Redis Streams Backend
 
 `VsRedisQueue` implements the queue using Redis Streams (`XADD` / `XREADGROUP`). Redis Streams provide persistent, ordered, consumer-group-aware message delivery.