rebrandly-otel 0.1.1__py3-none-any.whl

rebrandly_otel-0.1.1.dist-info/METADATA

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: rebrandly_otel
+Version: 0.1.1
+Summary: Python OTEL wrapper by Rebrandly
+Home-page: https://github.com/pypa/sampleproject
+Author: Antonio Romano
+Author-email: antobio@rebrandly.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: summary
+
+# Rebrandly OpenTelemetry SDK for Python
+
+A comprehensive OpenTelemetry instrumentation SDK designed specifically for Rebrandly services, with built-in support for AWS Lambda functions and message processing.
+
+## Overview
+
+The Rebrandly OpenTelemetry SDK provides a unified interface for distributed tracing, metrics collection, and structured logging across Python applications. It offers automatic instrumentation for AWS Lambda functions, simplified span management, and seamless integration with OTLP-compatible backends.
+
+## Installation
+
+```bash
+pip install rebrandly-otel-sdk
+```
+
+### Dependencies
+
+- `opentelemetry-api`
+- `opentelemetry-sdk`
+- `opentelemetry-exporter-otlp-proto-grpc`
+- `opentelemetry-semantic-conventions`
+- `psutil` (for system metrics)
+
+## Configuration
+
+The SDK is configured through environment variables:
+
+| Variable                           | Description | Default |
+|------------------------------------|-------------|---------|
+| `OTEL_SERVICE_NAME`                | Service identifier | `default-service-python` |
+| `OTEL_SERVICE_VERSION`             | Service version | `1.0.0` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT`      | OTLP collector endpoint | `None` |
+| `OTEL_DEBUG`                       | Enable console debugging | `false` |
+| `BATCH_EXPORT_TIME_MILLIS`         | Batch export interval | `100` |
+| `ENV` or `ENVIRONMENT` or `NODE_ENV`       | Deployment environment | `local` |
+
+## Core Components
+
+### RebrandlyOTEL Class
+
+The main entry point for all telemetry operations. Implements a singleton pattern to ensure consistent instrumentation across your application.
+
+#### Properties
+
+- **`tracer`**: Returns the `RebrandlyTracer` instance for distributed tracing
+- **`meter`**: Returns the `RebrandlyMeter` instance for metrics collection
+- **`logger`**: Returns the configured Python logger with OpenTelemetry integration
+
+#### Initialization
+
+The SDK auto-initializes as soon as you embed it.
+
+### Key Methods
+
+#### `span(name, attributes=None, kind=SpanKind.INTERNAL, message=None)`
+
+Context manager for creating traced spans with automatic error handling and status management.
+
+#### `lambda_handler(name=None, attributes=None, kind=SpanKind.CONSUMER, auto_flush=True, skip_aws_link=True)`
+
+Decorator for AWS Lambda functions with automatic instrumentation, metrics collection, and telemetry flushing.
+
+#### `aws_message_handler(name=None, attributes=None, kind=SpanKind.CONSUMER, auto_flush=True)`
+
+Decorator for processing individual AWS messages (SQS/SNS) with context propagation.
+
+#### `aws_message_span(name, message=None, attributes=None, kind=SpanKind.CONSUMER)`
+
+Context manager for creating spans from AWS messages with automatic context extraction.
+
+#### `force_flush(start_datetime=None, timeout_millis=1000)`
+
+Forces all pending telemetry data to be exported. Critical for serverless environments.
+
+#### `shutdown()`
+
+Gracefully shuts down all OpenTelemetry components.
+
+## Built-in Metrics
+
+The SDK automatically registers and tracks the following metrics:
+
+### Standard Metrics
+
+- **`invocations`** (Counter): Total number of function invocations
+- **`successful_invocations`** (Counter): Number of successful completions
+- **`error_invocations`** (Counter): Number of failed invocations
+- **`duration`** (Histogram): Execution duration in milliseconds
+- **`cpu_usage_percentage`** (Gauge): CPU utilization percentage
+- **`memory_usage_bytes`** (Gauge): Memory usage in bytes
+
+### Global Metrics Access
+
+```python
+from rebrandly_otel import meter
+
+# Access pre-configured metrics
+meter.GlobalMetrics.invocations.add(1, {'function': 'my_function'})
+meter.GlobalMetrics.duration.record(150.5, {'source': 'api'})
+```
+
+## Tracing Features
+
+### Automatic Context Propagation
+
+The SDK automatically extracts and propagates trace context from:
+- AWS SQS message attributes
+- AWS SNS message attributes
+- HTTP headers
+- Custom carriers
+
+### Span Attributes
+
+Lambda spans automatically include:
+- `faas.trigger`: Detected trigger type (sqs, sns, api_gateway, etc.)
+- `faas.execution`: AWS request ID
+- `faas.id`: Function ARN
+- `cloud.provider`: Always "aws" for Lambda
+- `cloud.platform`: Always "aws_lambda" for Lambda
+
+### Exception Handling
+
+Spans automatically capture exceptions with:
+- Full exception details and stack traces
+- Automatic status code setting
+- Exception events in the span timeline
+
+## Logging Integration
+
+The SDK integrates with Python's standard logging module:
+
+```python
+from rebrandly_otel import logger
+
+# Use as a standard Python logger
+logger.info("Processing started", extra={"request_id": "123"})
+logger.error("Processing failed", exc_info=True)
+```
+
+Features:
+- Automatic trace context injection
+- Structured logging support
+- Console and OTLP export
+- Log level configuration via environment
+
+## AWS Lambda Support
+
+### Trigger Detection
+
+Automatically detects and labels Lambda triggers:
+- API Gateway (v1 and v2)
+- SQS
+- SNS
+- S3
+- Kinesis
+- DynamoDB
+- EventBridge
+- Batch
+
+### Automatic Metrics
+
+For Lambda functions, the SDK automatically captures:
+- Function duration
+- Memory usage
+- CPU utilization
+- Invocation counts by status
+
+### Context Extraction
+
+Automatically extracts trace context from:
+- SQS MessageAttributes
+- SNS MessageAttributes (including nested format)
+- Custom message attributes
+
+## Performance Considerations
+
+### Batch Processing
+
+- Configurable batch sizes and intervals
+- Automatic batching for traces, metrics, and logs
+- Optimized for high-throughput scenarios
+
+### Lambda Optimization
+
+- Automatic flushing before function freeze
+- Minimal cold start impact
+- Efficient memory usage
+- Configurable timeout handling
+
+## Export Formats
+
+### Supported Exporters
+
+- **OTLP/gRPC**: Primary export format for production
+- **Console**: Available for local development and debugging
+
+## Thread Safety
+
+All components are thread-safe and can be used in multi-threaded applications:
+- Singleton pattern ensures single initialization
+- Thread-safe metric recording
+- Concurrent span creation support
+
+## Resource Attributes
+
+Automatically includes:
+- Service name and version
+- Python runtime version
+- Deployment environment
+- Custom resource attributes via environment
+
+## Error Handling
+
+- Graceful degradation when OTLP endpoint unavailable
+- Non-blocking telemetry operations
+- Automatic retry with exponential backoff
+- Comprehensive error logging
+
+## Compatibility
+
+- Python 3.7+
+- AWS Lambda runtime support
+- Compatible with OpenTelemetry Collector
+- Works with any OTLP-compatible backend
+
+## Examples
+
+### Lambda - Send SNS / SQS message
+```python
+import os
+import json
+import boto3
+from rebrandly_otel import otel, lambda_handler, logger
+
+sqs = boto3.client('sqs')
+QUEUE_URL = os.environ.get('SQS_URL')
+
+@lambda_handler("sqs_sender")
+def handler(event, context):
+    logger.info("Starting SQS message send")
+
+    # Get trace context for propagation
+    trace_attrs = otel.tracer.get_attributes_for_aws_from_context()
+
+    # Send message with trace context
+    response = sqs.send_message(
+        QueueUrl=QUEUE_URL,
+        MessageBody=json.dumps({"data": "test message"}),
+        MessageAttributes=trace_attrs
+    )
+
+    logger.info(f"Sent SQS message: {response['MessageId']}")
+
+    return {
+        'statusCode': 200,
+        'body': json.dumps({'messageId': response['MessageId']})
+    }
+```
+
+### Lambda Receive SQS message
+```python
+import json
+from rebrandly_otel import lambda_handler, logger, aws_message_span
+
+@lambda_handler(name="sqs_receiver")
+def handler(event, context):
+    for record in event['Records']:
+        # Process each message with trace context
+        process_message(record)
+
+def process_message(record):
+    with aws_message_span("process_message_sqs_receiver", message=record) as s:
+        logger.info(f"Processing message: {record['messageId']}")
+
+        # Parse message body
+        body = json.loads(record['body'])
+        logger.info(f"Message data: {body}")
+```
+
+### Lambda Receive SNS message (record specific event)
+```python
+import json
+from rebrandly_otel import lambda_handler, logger, aws_message_span
+
+@lambda_handler(name="sns_receiver")
+def handler(event, context):
+    for record in event['Records']:
+        # Process each message with trace context
+        process_message(record)
+
+def process_message(record):
+    message = json.loads(record['Sns']['Message'])
+    if message['event'] == 'whitelisted-event':
+        with aws_message_span("process_message_sns_receiver", message=record) as s:
+            logger.info(f"Processing message: {record['messageId']}")
+    
+            # Parse message body
+            body = json.loads(record['body'])
+            logger.info(f"Message data: {body}")
+```
+
+### More examples
+You can find More examples [here](examples)
+
+## License
+
+Rebrandly Python SDK is released under the MIT License.

rebrandly_otel-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+rebrandly_otel-0.1.1.dist-info/licenses/LICENSE,sha256=KMXHvTwP62S2q-SG7CFfMU_09rUwxiqlM0izaYGdcgY,1103
+src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/logs.py,sha256=eClyZfmlE85Y8S0ZqrJoilf6SvwkT1p6aUfX57IBy-s,3727
+src/metrics.py,sha256=TyVEAaWyKuPoQRMBpkYhT4SUx6GYtnyEuz6DQtEK93I,8540
+src/otel_utils.py,sha256=uJmfz2NspSnTVJXGKoaLUl1CYb0ow6VHKjmg2d_rdwg,1704
+src/rebrandly_otel.py,sha256=9QhKD37ZqVauikAxNUN8C4muXOJSg_mioFt--jwL9IU,19828
+src/traces.py,sha256=O_9wEpsW8mBlJEwVQj9QQXKB8WHYPNigtiOEBX7xanQ,7051
+rebrandly_otel-0.1.1.dist-info/METADATA,sha256=oSXPbAfvQywoWT99Cm2kxgf8ohbOR2G8h3yShAuK_bw,9398
+rebrandly_otel-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rebrandly_otel-0.1.1.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
+rebrandly_otel-0.1.1.dist-info/RECORD,,

rebrandly_otel-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rebrandly_otel-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2025 RadiateCapital Ltd (dba Rebrandly). (https://rebrandly.com)
+
+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.

rebrandly_otel-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+src

src/logs.py

@@ -0,0 +1,112 @@
+# logs.py
+"""Logging implementation for Rebrandly OTEL SDK."""
+import logging
+from typing import Optional
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import (
+    BatchLogRecordProcessor,
+    ConsoleLogExporter,
+    SimpleLogRecordProcessor
+)
+from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
+from opentelemetry._logs import set_logger_provider
+
+from src.otel_utils import *
+
+
+class RebrandlyLogger:
+    """Wrapper for OpenTelemetry logging with Rebrandly-specific features."""
+
+    def __init__(self):
+        self._logger: Optional[logging.Logger] = None
+        self._provider: Optional[LoggerProvider] = None
+        self._setup_logging()
+
+    def _setup_logging(self):
+        """Initialize logging with configured exporters."""
+
+        # Create provider with resource
+        self._provider = LoggerProvider(resource=create_resource())
+
+        # Add console exporter for local debugging
+        if is_otel_debug():
+            console_exporter = ConsoleLogExporter()
+            self._provider.add_log_record_processor(SimpleLogRecordProcessor(console_exporter))
+
+        # Add OTLP exporter if configured
+        if get_otlp_endpoint():
+            otlp_exporter = OTLPLogExporter(endpoint=get_otlp_endpoint())
+            batch_processor = BatchLogRecordProcessor(otlp_exporter, export_timeout_millis=get_millis_batch_time())
+            self._provider.add_log_record_processor(batch_processor)
+
+        # Set as global provider
+        set_logger_provider(self._provider)
+
+        # Configure standard logging
+        self._configure_standard_logging()
+
+    def _configure_standard_logging(self):
+        """Configure standard Python logging with OTEL handler."""
+        # Set up basic configuration
+        logging.basicConfig(
+            level=logging.INFO,
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            stream=sys.stdout,
+            force=True
+        )
+
+        # Add OTEL handler
+        otel_handler = LoggingHandler(logger_provider=self._provider)
+        otel_handler.setLevel(logging.INFO)
+
+        # Get root logger
+        root_logger = logging.getLogger()
+        root_logger.addHandler(otel_handler)
+
+        # Create service-specific logger
+        self._logger = logging.getLogger(get_service_name())
+
+
+    @property
+    def logger(self) -> logging.Logger:
+        """Get the standard Python logger."""
+        if not self._logger:
+            self._logger = logging.getLogger(get_service_name())
+        return self._logger
+
+    def force_flush(self, timeout_millis: int = 5000) -> bool:
+        """
+        Force flush all pending logs.
+
+        Args:
+            timeout_millis: Maximum time to wait for flush in milliseconds
+
+        Returns:
+            True if flush succeeded, False otherwise
+        """
+        if not self._provider:
+            return True
+
+        try:
+            # Force flush the logger provider
+            success = self._provider.force_flush(timeout_millis)
+
+            # Also flush Python's logging handlers
+            if self._logger:
+                for handler in self._logger.handlers:
+                    if hasattr(handler, 'flush'):
+                        handler.flush()
+
+            return success
+        except Exception as e:
+            print(f"[Logger] Error during force flush: {e}")
+            return False
+
+    def shutdown(self):
+        """Shutdown the logger provider."""
+        if self._provider:
+            try:
+                self._provider.shutdown()
+                print("[Logger] Shutdown completed")
+            except Exception as e:
+                print(f"[Logger] Error during shutdown: {e}")