rebrandly-otel 0.1.9

Python OTEL wrapper by Rebrandly

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

pip install rebrandly-otel

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

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:

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

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

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)

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

License

Rebrandly Python SDK is released under the MIT License.

Build and Deploy

brew install pipx
pipx ensurepath
pipx install build
pipx install twine

build

twine upload dist/*

If build gives you an error, try:

pyproject-build

twine upload dist/*