loggerbuf 0.9.2__tar.gz → 0.9.3__tar.gz

{loggerbuf-0.9.2 → loggerbuf-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loggerbuf
-Version: 0.9.2
+Version: 0.9.3
 Summary: A powerful structured telemetry and debugging logger with Protobuf schemas
 Author-email: LoggerBuf Team <hello@loggerbuf.dev>
 Project-URL: Repository, https://github.com/calavraian/LoggerBuf
@@ -28,6 +28,8 @@ Requires-Dist: psutil
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Build Status](https://github.com/calavraian/LoggerBuf/actions/workflows/ci.yml/badge.svg)](https://github.com/calavraian/LoggerBuf/actions)
 
+**[Visit the official website: loggerbuf.dev](https://loggerbuf.dev)**
+
 </div>
 
 🇺🇸 English | 🇪🇸 [Español](README.es.md)
@@ -64,6 +66,15 @@ You are now ready to log! You can also run these sub-commands individually if yo
 
 ---
 
+## 🤖 AI Agent Integration (Agent Skill)
+
+LoggerBuf is incredibly easy for AI coding assistants (like Gemini, Claude, or Cursor) to use!
+We provide a dedicated **Agent Skill** (`SKILL.md`) located in `.agents/skills/loggerbuf/SKILL.md` within this repository. 
+
+If you are using an agentic AI system that supports custom skills, simply point it to our `SKILL.md`. Your agent will instantly understand the CLI workflow, Schema Management rules, Event formatting guidelines, and DRY Python implementation patterns required to integrate LoggerBuf seamlessly into your project.
+
+---
+
 ## 🤔 Why LoggerBuf? (The Problem & The Solution)
 
 **The Problem:** 
@@ -169,22 +180,57 @@ The custom formatter instantly reveals the *where* and *what* of any log entry w
 - `message::> [Payload]`: The actual log message or serialized JSON object.
 
 ### 2. Analytical Event Logging (Telemetry)
-Telemetry uses Protobuf. Every event you track should be categorized using your custom `EventType` and `EventStatus` enums to ensure consistency across your organization. Just like the debugger, Telemetry automatically injects creation timestamps and routing headers behind the scenes.
+Telemetry uses Protobuf to log structured events. Every event is categorized using `EventType` and `EventStatus`. LoggerBuf automatically injects timestamps, file names, lines, and system identifiers.
+
+**Way 1: Standard Method (`log_event`)**
+The simplest way to log an event. You can pass any field defined in your `main_data.proto` as a keyword argument (kwargs).
 
 ```python
-from telemetry import TelemetryLog
-from data_logs import Event, EventType, EventStatus
+from loggerbuf.telemetry import TelemetryLog
+
+telemetry = TelemetryLog("MAIN")
+
+# Fire an event asynchronously
+telemetry.log_event(
+    event_type="EVENT_DATA_BASE_PROCESSING",
+    general_note="User uploaded a new invoice",
+    status="STATUS_COMPLETED",
+    duration_ms=150
+)
+```
+
+**Way 2: Context Manager (`event_context`)**
+Ideal for tracking block execution. It automatically calculates `duration_ms` and will set the status to `STATUS_ERROR` if an unhandled exception occurs inside the block.
+
+```python
+from loggerbuf.telemetry import TelemetryLog
+
+telemetry = TelemetryLog("MAIN")
+
+with telemetry.event_context(general_note="Processing database migration"):
+    # ... your code here ...
+    # duration_ms is automatically tracked and the event is fired when exiting the block
+    pass
+```
+
+**Way 3: Manual Object Building (`send`)**
+If you need absolute control, you can build the Protobuf object manually:
+
+```python
+from loggerbuf.telemetry import TelemetryLog
+from loggerbuf import schema_loader
+
+main_data_pb2 = schema_loader.get_main_data_pb2()
+registry_pb2 = schema_loader.get_registry_pb2()
 
-# 1. Initialize Logger
 telemetry = TelemetryLog("MAIN")
 
-# 2. Create and populate Event
-event = Event()
-event.event_type = EventType.EVENT_DATA_BASE_PROCESSING
-event.general_note = "User successfully registered"
-event.status = EventStatus.STATUS_COMPLETED
+event = main_data_pb2.Event()
+event.event_type = registry_pb2.EventType.EVENT_DATA_BASE_PROCESSING
+event.general_note = "User uploaded a new invoice"
+event.status = registry_pb2.EventStatus.STATUS_PENDING
 
-# Send it to the async binary queue
+# Fire the event asynchronously
 telemetry.send(event)
 ```
 

{loggerbuf-0.9.2 → loggerbuf-0.9.3}/README.md

@@ -7,6 +7,8 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Build Status](https://github.com/calavraian/LoggerBuf/actions/workflows/ci.yml/badge.svg)](https://github.com/calavraian/LoggerBuf/actions)
 
+**[Visit the official website: loggerbuf.dev](https://loggerbuf.dev)**
+
 </div>
 
 🇺🇸 English | 🇪🇸 [Español](README.es.md)
@@ -43,6 +45,15 @@ You are now ready to log! You can also run these sub-commands individually if yo
 
 ---
 
+## 🤖 AI Agent Integration (Agent Skill)
+
+LoggerBuf is incredibly easy for AI coding assistants (like Gemini, Claude, or Cursor) to use!
+We provide a dedicated **Agent Skill** (`SKILL.md`) located in `.agents/skills/loggerbuf/SKILL.md` within this repository. 
+
+If you are using an agentic AI system that supports custom skills, simply point it to our `SKILL.md`. Your agent will instantly understand the CLI workflow, Schema Management rules, Event formatting guidelines, and DRY Python implementation patterns required to integrate LoggerBuf seamlessly into your project.
+
+---
+
 ## 🤔 Why LoggerBuf? (The Problem & The Solution)
 
 **The Problem:** 
@@ -148,22 +159,57 @@ The custom formatter instantly reveals the *where* and *what* of any log entry w
 - `message::> [Payload]`: The actual log message or serialized JSON object.
 
 ### 2. Analytical Event Logging (Telemetry)
-Telemetry uses Protobuf. Every event you track should be categorized using your custom `EventType` and `EventStatus` enums to ensure consistency across your organization. Just like the debugger, Telemetry automatically injects creation timestamps and routing headers behind the scenes.
+Telemetry uses Protobuf to log structured events. Every event is categorized using `EventType` and `EventStatus`. LoggerBuf automatically injects timestamps, file names, lines, and system identifiers.
+
+**Way 1: Standard Method (`log_event`)**
+The simplest way to log an event. You can pass any field defined in your `main_data.proto` as a keyword argument (kwargs).
 
 ```python
-from telemetry import TelemetryLog
-from data_logs import Event, EventType, EventStatus
+from loggerbuf.telemetry import TelemetryLog
+
+telemetry = TelemetryLog("MAIN")
+
+# Fire an event asynchronously
+telemetry.log_event(
+    event_type="EVENT_DATA_BASE_PROCESSING",
+    general_note="User uploaded a new invoice",
+    status="STATUS_COMPLETED",
+    duration_ms=150
+)
+```
+
+**Way 2: Context Manager (`event_context`)**
+Ideal for tracking block execution. It automatically calculates `duration_ms` and will set the status to `STATUS_ERROR` if an unhandled exception occurs inside the block.
+
+```python
+from loggerbuf.telemetry import TelemetryLog
+
+telemetry = TelemetryLog("MAIN")
+
+with telemetry.event_context(general_note="Processing database migration"):
+    # ... your code here ...
+    # duration_ms is automatically tracked and the event is fired when exiting the block
+    pass
+```
+
+**Way 3: Manual Object Building (`send`)**
+If you need absolute control, you can build the Protobuf object manually:
+
+```python
+from loggerbuf.telemetry import TelemetryLog
+from loggerbuf import schema_loader
+
+main_data_pb2 = schema_loader.get_main_data_pb2()
+registry_pb2 = schema_loader.get_registry_pb2()
 
-# 1. Initialize Logger
 telemetry = TelemetryLog("MAIN")
 
-# 2. Create and populate Event
-event = Event()
-event.event_type = EventType.EVENT_DATA_BASE_PROCESSING
-event.general_note = "User successfully registered"
-event.status = EventStatus.STATUS_COMPLETED
+event = main_data_pb2.Event()
+event.event_type = registry_pb2.EventType.EVENT_DATA_BASE_PROCESSING
+event.general_note = "User uploaded a new invoice"
+event.status = registry_pb2.EventStatus.STATUS_PENDING
 
-# Send it to the async binary queue
+# Fire the event asynchronously
 telemetry.send(event)
 ```
 

{loggerbuf-0.9.2 → loggerbuf-0.9.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loggerbuf"
-version = "0.9.2"
+version = "0.9.3"
 description = "A powerful structured telemetry and debugging logger with Protobuf schemas"
 readme = "README.md"
 requires-python = ">=3.8"

{loggerbuf-0.9.2 → loggerbuf-0.9.3}/src/loggerbuf/data_logs/main_data_pb2.py

@@ -1,8 +1,9 @@
+# WARNING: DO NOT EDIT THIS FILE MANUALLY.
 # -*- coding: utf-8 -*-
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # NO CHECKED-IN PROTOBUF GENCODE
 # source: main_data.proto
-# Protobuf Python Version: 6.33.4
+# Protobuf Python Version: 7.35.0
 """Generated protocol buffer code."""
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import descriptor_pool as _descriptor_pool
@@ -11,9 +12,9 @@ from google.protobuf import symbol_database as _symbol_database
 from google.protobuf.internal import builder as _builder
 _runtime_version.ValidateProtobufRuntimeVersion(
     _runtime_version.Domain.PUBLIC,
-    6,
-    33,
-    4,
+    7,
+    35,
+    0,
     '',
     'main_data.proto'
 )
@@ -22,10 +23,13 @@ _runtime_version.ValidateProtobufRuntimeVersion(
 _sym_db = _symbol_database.Default()
 
 
-from . import registry_pb2 as registry__pb2
+try:
+    from . import registry_pb2 as registry__pb2
+except ImportError:
+    import registry_pb2 as registry__pb2
 
 
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0fmain_data.proto\x12\tmain_data\x1a\x0eregistry.proto\"\xc0\x02\n\x05\x45vent\x12+\n\nevent_type\x18\x01 \x01(\x0e\x32\x17.enum_control.EventType\x12\x11\n\ttimestamp\x18\x02 \x01(\t\x12\x14\n\x0cgeneral_note\x18\x03 \x01(\t\x12)\n\x06status\x18\x04 \x01(\x0e\x32\x19.enum_control.EventStatus\x12\x13\n\x0blogger_name\x18\x06 \x01(\t\x12\x13\n\x0b\x63\x61ller_file\x18\x07 \x01(\t\x12\x14\n\x0c\x63\x61ller_class\x18\x08 \x01(\t\x12\x17\n\x0f\x63\x61ller_function\x18\t \x01(\t\x12\x0e\n\x06lineno\x18\n \x01(\x05\x12\x1b\n\x12previous_file_hash\x18\x8dN \x01(\x0c\x12\x17\n\x0eis_chain_start\x18\x8eN \x01(\x08\x12\x17\n\x0ehmac_signature\x18\x8fN \x01(\x0c\"\x99\x02\n\x0c\x43ounterEvent\x12/\n\x0c\x63ounter_type\x18\x01 \x01(\x0e\x32\x19.enum_control.CounterType\x12\x11\n\ttimestamp\x18\x02 \x01(\t\x12\r\n\x05\x63ount\x18\x03 \x01(\x05\x12\x13\n\x0blogger_name\x18\x04 \x01(\t\x12\x13\n\x0b\x63\x61ller_file\x18\x05 \x01(\t\x12\x14\n\x0c\x63\x61ller_class\x18\x06 \x01(\t\x12\x17\n\x0f\x63\x61ller_function\x18\x07 \x01(\t\x12\x0e\n\x06lineno\x18\x08 \x01(\x05\x12\x1b\n\x12previous_file_hash\x18\x8dN \x01(\x0c\x12\x17\n\x0eis_chain_start\x18\x8eN \x01(\x08\x12\x17\n\x0ehmac_signature\x18\x8fN \x01(\x0c\x62\x06proto3')
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0fmain_data.proto\x12\tmain_data\x1a\x0eregistry.proto\"\xd5\x02\n\x05\x45vent\x12+\n\nevent_type\x18\x01 \x01(\x0e\x32\x17.enum_control.EventType\x12\x11\n\ttimestamp\x18\x02 \x01(\t\x12\x14\n\x0cgeneral_note\x18\x03 \x01(\t\x12)\n\x06status\x18\x04 \x01(\x0e\x32\x19.enum_control.EventStatus\x12\x13\n\x0blogger_name\x18\x06 \x01(\t\x12\x13\n\x0b\x63\x61ller_file\x18\x07 \x01(\t\x12\x14\n\x0c\x63\x61ller_class\x18\x08 \x01(\t\x12\x17\n\x0f\x63\x61ller_function\x18\t \x01(\t\x12\x0e\n\x06lineno\x18\n \x01(\x05\x12\x13\n\x0b\x64uration_ms\x18\x0b \x01(\x03\x12\x1b\n\x12previous_file_hash\x18\x8dN \x01(\x0c\x12\x17\n\x0eis_chain_start\x18\x8eN \x01(\x08\x12\x17\n\x0ehmac_signature\x18\x8fN \x01(\x0c\"\x99\x02\n\x0c\x43ounterEvent\x12/\n\x0c\x63ounter_type\x18\x01 \x01(\x0e\x32\x19.enum_control.CounterType\x12\x11\n\ttimestamp\x18\x02 \x01(\t\x12\r\n\x05\x63ount\x18\x03 \x01(\x05\x12\x13\n\x0blogger_name\x18\x04 \x01(\t\x12\x13\n\x0b\x63\x61ller_file\x18\x05 \x01(\t\x12\x14\n\x0c\x63\x61ller_class\x18\x06 \x01(\t\x12\x17\n\x0f\x63\x61ller_function\x18\x07 \x01(\t\x12\x0e\n\x06lineno\x18\x08 \x01(\x05\x12\x1b\n\x12previous_file_hash\x18\x8dN \x01(\x0c\x12\x17\n\x0eis_chain_start\x18\x8eN \x01(\x08\x12\x17\n\x0ehmac_signature\x18\x8fN \x01(\x0c\x62\x06proto3')
 
 _globals = globals()
 _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
@@ -33,7 +37,7 @@ _builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'main_data_pb2', _globals)
 if not _descriptor._USE_C_DESCRIPTORS:
   DESCRIPTOR._loaded_options = None
   _globals['_EVENT']._serialized_start=47
-  _globals['_EVENT']._serialized_end=367
-  _globals['_COUNTEREVENT']._serialized_start=370
-  _globals['_COUNTEREVENT']._serialized_end=651
+  _globals['_EVENT']._serialized_end=388
+  _globals['_COUNTEREVENT']._serialized_start=391
+  _globals['_COUNTEREVENT']._serialized_end=672
 # @@protoc_insertion_point(module_scope)

{loggerbuf-0.9.2 → loggerbuf-0.9.3}/src/loggerbuf/data_logs/registry_pb2.py

@@ -1,8 +1,9 @@
+# WARNING: DO NOT EDIT THIS FILE MANUALLY.
 # -*- coding: utf-8 -*-
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # NO CHECKED-IN PROTOBUF GENCODE
 # source: registry.proto
-# Protobuf Python Version: 6.33.4
+# Protobuf Python Version: 7.35.0
 """Generated protocol buffer code."""
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import descriptor_pool as _descriptor_pool
@@ -11,9 +12,9 @@ from google.protobuf import symbol_database as _symbol_database
 from google.protobuf.internal import builder as _builder
 _runtime_version.ValidateProtobufRuntimeVersion(
     _runtime_version.Domain.PUBLIC,
-    6,
-    33,
-    4,
+    7,
+    35,
+    0,
     '',
     'registry.proto'
 )
@@ -24,7 +25,7 @@ _sym_db = _symbol_database.Default()
 
 
 
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0eregistry.proto\x12\x0c\x65num_control*\xf0\x01\n\x0b\x45ventStatus\x12\x16\n\x12STATUS_UNSPECIFIED\x10\x00\x12\x12\n\x0eSTATUS_PENDING\x10\x01\x12\x11\n\rSTATUS_ACTIVE\x10\x02\x12\x14\n\x10STATUS_COMPLETED\x10\x03\x12\x11\n\rSTATUS_FAILED\x10\x04\x12\x12\n\x0eSTATUS_ABORTED\x10\x05\x12 \n\x1c\x45XAMPLE_EVENT_STATUS_STARTED\x10\x33\x12\"\n\x1e\x45XAMPLE_EVENT_STATUS_COMPLETED\x10\x34\x12\x1f\n\x1b\x45XAMPLE_EVENT_STATUS_FAILED\x10\x35*\x94\x02\n\tEventType\x12\x15\n\x11\x45VENT_UNSPECIFIED\x10\x00\x12\x11\n\rEVENT_GENERIC\x10\x01\x12\x0e\n\nEVENT_MAIN\x10\x02\x12\x1e\n\x1a\x45VENT_DATA_BASE_PROCESSING\x10\x03\x12\x15\n\x11\x45VENT_API_REQUEST\x10\x04\x12\x16\n\x12\x45VENT_API_RESPONSE\x10\x05\x12\x1d\n\x19\x45XAMPLE_EVENT_API_INVOKED\x10\x65\x12\x1e\n\x1a\x45XAMPLE_EVENT_API_RESPONSE\x10\x66\x12 \n\x1c\x45XAMPLE_EVENT_DATA_PROCESSED\x10h\x12\x1d\n\x19\x45XAMPLE_EVENT_DATA_STORED\x10i*;\n\x0b\x43ounterType\x12\x17\n\x13\x43OUNTER_UNSPECIFIED\x10\x00\x12\x13\n\x0f\x43OUNTER_GENERIC\x10\x01\x62\x06proto3')
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0eregistry.proto\x12\x0c\x65num_control*\xe7\x01\n\x0b\x45ventStatus\x12\x16\n\x12STATUS_UNSPECIFIED\x10\x00\x12\x12\n\x0eSTATUS_PENDING\x10\x01\x12\x11\n\rSTATUS_ACTIVE\x10\x02\x12\x14\n\x10STATUS_COMPLETED\x10\x03\x12\x11\n\rSTATUS_FAILED\x10\x04\x12\x12\n\x0eSTATUS_ABORTED\x10\x05\x12\x1d\n\x19\x44\x45MO_EVENT_STATUS_STARTED\x10\x33\x12\x1f\n\x1b\x44\x45MO_EVENT_STATUS_COMPLETED\x10\x34\x12\x1c\n\x18\x44\x45MO_EVENT_STATUS_FAILED\x10\x35*\x88\x02\n\tEventType\x12\x15\n\x11\x45VENT_UNSPECIFIED\x10\x00\x12\x11\n\rEVENT_GENERIC\x10\x01\x12\x0e\n\nEVENT_MAIN\x10\x02\x12\x1e\n\x1a\x45VENT_DATA_BASE_PROCESSING\x10\x03\x12\x15\n\x11\x45VENT_API_REQUEST\x10\x04\x12\x16\n\x12\x45VENT_API_RESPONSE\x10\x05\x12\x1a\n\x16\x44\x45MO_EVENT_API_INVOKED\x10\x65\x12\x1b\n\x17\x44\x45MO_EVENT_API_RESPONSE\x10\x66\x12\x1d\n\x19\x44\x45MO_EVENT_DATA_PROCESSED\x10h\x12\x1a\n\x16\x44\x45MO_EVENT_DATA_STORED\x10i*;\n\x0b\x43ounterType\x12\x17\n\x13\x43OUNTER_UNSPECIFIED\x10\x00\x12\x13\n\x0f\x43OUNTER_GENERIC\x10\x01\x62\x06proto3')
 
 _globals = globals()
 _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
@@ -32,9 +33,9 @@ _builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'registry_pb2', _globals)
 if not _descriptor._USE_C_DESCRIPTORS:
   DESCRIPTOR._loaded_options = None
   _globals['_EVENTSTATUS']._serialized_start=33
-  _globals['_EVENTSTATUS']._serialized_end=273
-  _globals['_EVENTTYPE']._serialized_start=276
-  _globals['_EVENTTYPE']._serialized_end=552
-  _globals['_COUNTERTYPE']._serialized_start=554
-  _globals['_COUNTERTYPE']._serialized_end=613
+  _globals['_EVENTSTATUS']._serialized_end=264
+  _globals['_EVENTTYPE']._serialized_start=267
+  _globals['_EVENTTYPE']._serialized_end=531
+  _globals['_COUNTERTYPE']._serialized_start=533
+  _globals['_COUNTERTYPE']._serialized_end=592
 # @@protoc_insertion_point(module_scope)

{loggerbuf-0.9.2 → loggerbuf-0.9.3}/src/loggerbuf/telemetry.py

@@ -8,11 +8,40 @@ from .config import ConfigManager, QueueStrategy, ConfigKey
 
 from . import schema_loader
 main_data_pb2 = schema_loader.get_main_data_pb2()
+registry_pb2 = schema_loader.get_registry_pb2()
 Event = main_data_pb2.Event
 CounterEvent = main_data_pb2.CounterEvent
 
 from .queue_metrics import QueueMetrics, MetricField
 
+class EventContext:
+    def __init__(self, telemetry_instance, event_type, base_kwargs):
+        self.telemetry = telemetry_instance
+        self.event_type = event_type
+        self.kwargs = base_kwargs
+        self.start_time = None
+
+    def attach(self, **new_kwargs):
+        """Attaches additional data to the event context."""
+        self.kwargs.update(new_kwargs)
+
+    def __enter__(self):
+        self.start_time = time.time()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        duration_ms = int((time.time() - self.start_time) * 1000)
+        self.kwargs["duration_ms"] = duration_ms
+
+        if exc_type is not None:
+            status = registry_pb2.EventStatus.STATUS_FAILED
+            self.kwargs["general_note"] = f"[{exc_type.__name__}] {str(exc_value)} | {self.kwargs.get('general_note', '')}"
+        else:
+            status = registry_pb2.EventStatus.STATUS_COMPLETED
+
+        self.telemetry.log_event(event_type=self.event_type, status=status, stack_depth=3, **self.kwargs)
+        return False
+
 class BaseSettings:
     def __init__(self, prefix: str, name: str = None, logs_base_dir: str = ".", backup_dir: str = None, file_size: int = None, backup_count: int = None):
         config = ConfigManager()
@@ -310,17 +339,67 @@ class TelemetryLog:
                 self.__event_writer = TelemetryLog.__instances[name][1]
                 self.__metric_writer = TelemetryLog.__instances[name][2]
 
-    def create_event(self, event: Event):
+    def event_context(self, event_type=None, **kwargs):
+        """Returns a context manager for tracking an event's duration and status."""
+        if event_type is None:
+            event_type = registry_pb2.EventType.EVENT_GENERIC
+        return EventContext(self, event_type, kwargs)
+
+    def log_event(self, event_type=None, status=None, stack_depth=2, **kwargs):
+        """Convenience method to log an event directly with kwargs."""
+        if event_type is None:
+            event_type = registry_pb2.EventType.EVENT_GENERIC
+        if status is None:
+            status = registry_pb2.EventStatus.STATUS_COMPLETED
+            
+        main_event = Event()
+        main_event.event_type = event_type
+        main_event.status = status
+        
+        # Protected fields that the system handles
+        protected_fields = {"logger_name", "timestamp", "caller_file", "caller_class", "caller_function", "lineno"}
+        
+        for key, value in kwargs.items():
+            if key in protected_fields:
+                continue
+                
+            if hasattr(main_event, key):
+                field = getattr(main_event, key)
+                if hasattr(field, 'CopyFrom'):
+                    try:
+                        field.CopyFrom(value)
+                    except Exception as e:
+                        # Fallback for some types or error
+                        pass
+                else:
+                    try:
+                        setattr(main_event, key, value)
+                    except Exception:
+                        pass
+            else:
+                # Issue warning via debugger if enabled, or just pass
+                pass
+                
+        self.create_event(main_event, stack_depth=stack_depth)
+
+    def create_event(self, event: Event, stack_depth: int = 1):
         import sys
         try:
-            frame = sys._getframe(1)
-            event.caller_file = os.path.basename(frame.f_code.co_filename)
-            event.caller_function = frame.f_code.co_name
-            event.lineno = frame.f_lineno
-            if 'self' in frame.f_locals:
-                event.caller_class = frame.f_locals['self'].__class__.__name__
+            # Walk up the stack to find the actual caller outside telemetry.py
+            frame = sys._getframe(stack_depth)
+            while frame and os.path.basename(frame.f_code.co_filename) == "telemetry.py":
+                frame = frame.f_back
+            
+            if frame:
+                event.caller_file = os.path.basename(frame.f_code.co_filename)
+                event.caller_function = frame.f_code.co_name
+                event.lineno = frame.f_lineno
+                if 'self' in frame.f_locals:
+                    event.caller_class = frame.f_locals['self'].__class__.__name__
+                else:
+                    event.caller_class = "None"
             else:
-                event.caller_class = "None"
+                raise ValueError("No caller frame found")
         except Exception:
             event.caller_file = "Unknown"
             event.caller_function = "Unknown"
@@ -347,7 +426,7 @@ class TelemetryLog:
         _check_deprecated_fields(event)
         self.__event_writer.write_event(event)
 
-    def increment(self, counter_type, value: int = 1):
+    def increment(self, counter_type, value: int = 1, stack_depth: int = 1):
         if not self.__metric_writer:
             return
             
@@ -357,14 +436,20 @@ class TelemetryLog:
         
         import sys
         try:
-            frame = sys._getframe(1)
-            event.caller_file = os.path.basename(frame.f_code.co_filename)
-            event.caller_function = frame.f_code.co_name
-            event.lineno = frame.f_lineno
-            if 'self' in frame.f_locals:
-                event.caller_class = frame.f_locals['self'].__class__.__name__
+            frame = sys._getframe(stack_depth)
+            while frame and os.path.basename(frame.f_code.co_filename) == "telemetry.py":
+                frame = frame.f_back
+                
+            if frame:
+                event.caller_file = os.path.basename(frame.f_code.co_filename)
+                event.caller_function = frame.f_code.co_name
+                event.lineno = frame.f_lineno
+                if 'self' in frame.f_locals:
+                    event.caller_class = frame.f_locals['self'].__class__.__name__
+                else:
+                    event.caller_class = "None"
             else:
-                event.caller_class = "None"
+                raise ValueError("No caller frame found")
         except Exception:
             event.caller_file = "Unknown"
             event.caller_function = "Unknown"

{loggerbuf-0.9.2 → loggerbuf-0.9.3}/src/loggerbuf.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loggerbuf
-Version: 0.9.2
+Version: 0.9.3
 Summary: A powerful structured telemetry and debugging logger with Protobuf schemas
 Author-email: LoggerBuf Team <hello@loggerbuf.dev>
 Project-URL: Repository, https://github.com/calavraian/LoggerBuf
@@ -28,6 +28,8 @@ Requires-Dist: psutil
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Build Status](https://github.com/calavraian/LoggerBuf/actions/workflows/ci.yml/badge.svg)](https://github.com/calavraian/LoggerBuf/actions)
 
+**[Visit the official website: loggerbuf.dev](https://loggerbuf.dev)**
+
 </div>
 
 🇺🇸 English | 🇪🇸 [Español](README.es.md)
@@ -64,6 +66,15 @@ You are now ready to log! You can also run these sub-commands individually if yo
 
 ---
 
+## 🤖 AI Agent Integration (Agent Skill)
+
+LoggerBuf is incredibly easy for AI coding assistants (like Gemini, Claude, or Cursor) to use!
+We provide a dedicated **Agent Skill** (`SKILL.md`) located in `.agents/skills/loggerbuf/SKILL.md` within this repository. 
+
+If you are using an agentic AI system that supports custom skills, simply point it to our `SKILL.md`. Your agent will instantly understand the CLI workflow, Schema Management rules, Event formatting guidelines, and DRY Python implementation patterns required to integrate LoggerBuf seamlessly into your project.
+
+---
+
 ## 🤔 Why LoggerBuf? (The Problem & The Solution)
 
 **The Problem:** 
@@ -169,22 +180,57 @@ The custom formatter instantly reveals the *where* and *what* of any log entry w
 - `message::> [Payload]`: The actual log message or serialized JSON object.
 
 ### 2. Analytical Event Logging (Telemetry)
-Telemetry uses Protobuf. Every event you track should be categorized using your custom `EventType` and `EventStatus` enums to ensure consistency across your organization. Just like the debugger, Telemetry automatically injects creation timestamps and routing headers behind the scenes.
+Telemetry uses Protobuf to log structured events. Every event is categorized using `EventType` and `EventStatus`. LoggerBuf automatically injects timestamps, file names, lines, and system identifiers.
+
+**Way 1: Standard Method (`log_event`)**
+The simplest way to log an event. You can pass any field defined in your `main_data.proto` as a keyword argument (kwargs).
 
 ```python
-from telemetry import TelemetryLog
-from data_logs import Event, EventType, EventStatus
+from loggerbuf.telemetry import TelemetryLog
+
+telemetry = TelemetryLog("MAIN")
+
+# Fire an event asynchronously
+telemetry.log_event(
+    event_type="EVENT_DATA_BASE_PROCESSING",
+    general_note="User uploaded a new invoice",
+    status="STATUS_COMPLETED",
+    duration_ms=150
+)
+```
+
+**Way 2: Context Manager (`event_context`)**
+Ideal for tracking block execution. It automatically calculates `duration_ms` and will set the status to `STATUS_ERROR` if an unhandled exception occurs inside the block.
+
+```python
+from loggerbuf.telemetry import TelemetryLog
+
+telemetry = TelemetryLog("MAIN")
+
+with telemetry.event_context(general_note="Processing database migration"):
+    # ... your code here ...
+    # duration_ms is automatically tracked and the event is fired when exiting the block
+    pass
+```
+
+**Way 3: Manual Object Building (`send`)**
+If you need absolute control, you can build the Protobuf object manually:
+
+```python
+from loggerbuf.telemetry import TelemetryLog
+from loggerbuf import schema_loader
+
+main_data_pb2 = schema_loader.get_main_data_pb2()
+registry_pb2 = schema_loader.get_registry_pb2()
 
-# 1. Initialize Logger
 telemetry = TelemetryLog("MAIN")
 
-# 2. Create and populate Event
-event = Event()
-event.event_type = EventType.EVENT_DATA_BASE_PROCESSING
-event.general_note = "User successfully registered"
-event.status = EventStatus.STATUS_COMPLETED
+event = main_data_pb2.Event()
+event.event_type = registry_pb2.EventType.EVENT_DATA_BASE_PROCESSING
+event.general_note = "User uploaded a new invoice"
+event.status = registry_pb2.EventStatus.STATUS_PENDING
 
-# Send it to the async binary queue
+# Fire the event asynchronously
 telemetry.send(event)
 ```
 

{loggerbuf-0.9.2 → loggerbuf-0.9.3}/tests/test_telemetry.py

@@ -96,3 +96,37 @@ def test_telemetry_concurrency_lossless(tmp_path):
             count += 1
             
     assert count == 1000
+
+def test_telemetry_log_event(tmp_path):
+    settings = EventSettings(name=f"TEST_LOG_EVENT_{tmp_path.name}", logs_base_dir=str(tmp_path))
+    telemetry = TelemetryLog(settings)
+    
+    # Test setting a standard field
+    telemetry.log_event(general_note="Test log_event")
+    
+    writer = telemetry._TelemetryLog__event_writer
+    writer.queue.join()
+    time.sleep(0.1)
+
+def test_telemetry_event_context_success(tmp_path):
+    settings = EventSettings(name=f"TEST_CTX_SUCCESS_{tmp_path.name}", logs_base_dir=str(tmp_path))
+    telemetry = TelemetryLog(settings)
+    
+    with telemetry.event_context(general_note="Context Test"):
+        time.sleep(0.05)
+        
+    writer = telemetry._TelemetryLog__event_writer
+    writer.queue.join()
+    time.sleep(0.1)
+
+def test_telemetry_event_context_exception(tmp_path):
+    settings = EventSettings(name=f"TEST_CTX_FAIL_{tmp_path.name}", logs_base_dir=str(tmp_path))
+    telemetry = TelemetryLog(settings)
+    
+    with pytest.raises(ValueError, match="Test Error"):
+        with telemetry.event_context(general_note="Exception Test"):
+            raise ValueError("Test Error")
+            
+    writer = telemetry._TelemetryLog__event_writer
+    writer.queue.join()
+    time.sleep(0.1)