otel-utils 1.1.3__tar.gz → 1.1.5__tar.gz

{otel_utils-1.1.3 → otel_utils-1.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: otel-utils
-Version: 1.1.3
+Version: 1.1.5
 Summary: Utilidades simplificadas para instrumentación con OpenTelemetry
 License: Proprietary
 Author: Harold Portocarrero
@@ -58,6 +58,7 @@ config = OtelConfig(
     metric_export_interval_ms=30000,        # Metrics export interval
     log_level=logging.INFO,                 # Logging level
     enable_console_logging=True,            # Enable console logging
+    json_logging=True,                      # Use JSON format for logs (default: True)
     additional_resources={                   # Optional additional resources
         "deployment.region": "us-east-1",
         "team.name": "backend"
@@ -73,16 +74,21 @@ from otel_utils import Tracer
 
 tracer = Tracer("my-service")
 
-# Using the decorator
+# Using the decorator (auto-handles errors and status)
 @tracer.trace("my_operation")
 async def my_function():
     # Your code here
     pass
 
-# Using the context manager
+# Using the context manager for custom spans
 with tracer.create_span("my_operation") as span:
     span.set_attribute("key", "value")
     # Your code here
+
+# Using start_as_current_span for context propagation
+with tracer.start_as_current_span("parent_span") as span:
+    # Operations here will be associated with parent_span
+    pass
 ```
 
 ### Metrics
@@ -95,21 +101,38 @@ metrics = Metrics("my-service")
 counter = metrics.get_counter("requests_total")
 counter.add(1, {"endpoint": "/api/v1/resource"})
 
-# Histogram for latencies
-with metrics.measure_duration("request_duration"):
+# Histogram for latencies using a context manager
+with metrics.measure_duration("request_duration", attributes={"method": "GET"}):
     # Your code here
     pass
+
+# Asynchronous metrics (Observable Gauge)
+def get_system_load():
+    return 0.5  # Calculated value
+
+metrics.observe_async(
+    name="system_load",
+    description="Current system load",
+    callback=get_system_load
+)
 ```
 
 ### Structured Logging
+The library provides a `StructuredLogger` that outputs logs in JSON format (when `json_logging` is enabled) and automatically includes tracing context.
+
 ```python
 from otel_utils import StructuredLogger
 
-logger = StructuredLogger("my-service")
+logger = StructuredLogger("my-service", environment="production")
 
-with logger.operation_context("process_order", order_id="123"):
+# Using operation_context to auto-log start/end/errors
+with logger.operation_context("process_order", order_id="123", customer_type="vip"):
     logger.info("Starting processing")
-    # Your code here
+    # If an exception is raised here, it will be logged with status="failed"
+    # and the error message will be included in the JSON log.
+
+# Manual logging with extra context
+logger.info("Event occurred", action="login", user="user123")
 ```
 
 ## OpenTelemetry Collector Integration

{otel_utils-1.1.3 → otel_utils-1.1.5}/README.md

@@ -32,6 +32,7 @@ config = OtelConfig(
     metric_export_interval_ms=30000,        # Metrics export interval
     log_level=logging.INFO,                 # Logging level
     enable_console_logging=True,            # Enable console logging
+    json_logging=True,                      # Use JSON format for logs (default: True)
     additional_resources={                   # Optional additional resources
         "deployment.region": "us-east-1",
         "team.name": "backend"
@@ -47,16 +48,21 @@ from otel_utils import Tracer
 
 tracer = Tracer("my-service")
 
-# Using the decorator
+# Using the decorator (auto-handles errors and status)
 @tracer.trace("my_operation")
 async def my_function():
     # Your code here
     pass
 
-# Using the context manager
+# Using the context manager for custom spans
 with tracer.create_span("my_operation") as span:
     span.set_attribute("key", "value")
     # Your code here
+
+# Using start_as_current_span for context propagation
+with tracer.start_as_current_span("parent_span") as span:
+    # Operations here will be associated with parent_span
+    pass
 ```
 
 ### Metrics
@@ -69,21 +75,38 @@ metrics = Metrics("my-service")
 counter = metrics.get_counter("requests_total")
 counter.add(1, {"endpoint": "/api/v1/resource"})
 
-# Histogram for latencies
-with metrics.measure_duration("request_duration"):
+# Histogram for latencies using a context manager
+with metrics.measure_duration("request_duration", attributes={"method": "GET"}):
     # Your code here
     pass
+
+# Asynchronous metrics (Observable Gauge)
+def get_system_load():
+    return 0.5  # Calculated value
+
+metrics.observe_async(
+    name="system_load",
+    description="Current system load",
+    callback=get_system_load
+)
 ```
 
 ### Structured Logging
+The library provides a `StructuredLogger` that outputs logs in JSON format (when `json_logging` is enabled) and automatically includes tracing context.
+
 ```python
 from otel_utils import StructuredLogger
 
-logger = StructuredLogger("my-service")
+logger = StructuredLogger("my-service", environment="production")
 
-with logger.operation_context("process_order", order_id="123"):
+# Using operation_context to auto-log start/end/errors
+with logger.operation_context("process_order", order_id="123", customer_type="vip"):
     logger.info("Starting processing")
-    # Your code here
+    # If an exception is raised here, it will be logged with status="failed"
+    # and the error message will be included in the JSON log.
+
+# Manual logging with extra context
+logger.info("Event occurred", action="login", user="user123")
 ```
 
 ## OpenTelemetry Collector Integration

{otel_utils-1.1.3 → otel_utils-1.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "otel-utils"
-version = "1.1.3"
+version = "1.1.5"
 description = "Utilidades simplificadas para instrumentación con OpenTelemetry"
 authors = ["Harold Portocarrero <harold@getcometa.com>"]
 readme = "README.md"