rebrandly-otel 0.3.1__py3-none-any.whl

rebrandly_otel/__init__.py

@@ -0,0 +1,32 @@
+# src/__init__.py
+from .rebrandly_otel import *
+from .flask_support import setup_flask
+from .fastapi_support import setup_fastapi
+from .pymysql_instrumentation import instrument_pymysql
+from .api_gateway_utils import (
+    is_api_gateway_event,
+    extract_api_gateway_http_attributes,
+    extract_api_gateway_context
+)
+
+# Explicitly define what's available
+__all__ = [
+    'otel',
+    'lambda_handler',
+    'span',
+    'aws_message_span',
+    'traces',
+    'tracer',
+    'metrics',
+    'logger',
+    'force_flush',
+    'aws_message_handler',
+    'shutdown',
+    'setup_flask',
+    'setup_fastapi',
+    'instrument_pymysql',
+    # API Gateway utilities
+    'is_api_gateway_event',
+    'extract_api_gateway_http_attributes',
+    'extract_api_gateway_context'
+]

rebrandly_otel/api_gateway_utils.py

@@ -0,0 +1,230 @@
+"""
+API Gateway instrumentation utilities for Lambda handlers.
+Extracts HTTP semantic attributes from API Gateway events (REST API v1 and HTTP API v2).
+"""
+
+import json
+import re
+from typing import Any, Dict, Optional, Tuple
+from urllib.parse import urlencode
+
+from .http_utils import (
+    filter_important_headers,
+    capture_request_body,
+    auto_detect_route_pattern
+)
+from .http_constants import (
+    HTTP_REQUEST_METHOD, HTTP_REQUEST_HEADERS, HTTP_REQUEST_HEADER_TRACEPARENT,
+    HTTP_REQUEST_BODY, HTTP_ROUTE, URL_FULL, URL_SCHEME,
+    URL_PATH, URL_QUERY, USER_AGENT_ORIGINAL, SERVER_ADDRESS, SERVER_PORT,
+    CLIENT_ADDRESS, NETWORK_PROTOCOL_VERSION,
+    USER_ID, REBRANDLY_WORKSPACE, REBRANDLY_ORGANIZATION
+)
+
+
+def is_api_gateway_event(event: Any) -> bool:
+    """
+    Check if the event is from API Gateway (REST v1 or HTTP v2).
+
+    Args:
+        event: Lambda event object
+
+    Returns:
+        True if the event is from API Gateway
+    """
+    if not isinstance(event, dict):
+        return False
+    return bool(
+        event.get('httpMethod') or
+        event.get('requestContext', {}).get('http', {}).get('method')
+    )
+
+
+def _is_valid_authorizer_value(value: Any) -> bool:
+    """
+    Check if a value is meaningful (not null/None/"None"/empty).
+    Per OpenTelemetry conventions, attributes should only be set when they have meaningful values.
+    """
+    return value is not None and value != 'None' and value != 'null' and value != ''
+
+
+def extract_api_gateway_authorizer_attributes(event: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Extract user and workspace context from API Gateway requestContext.authorizer.
+    Only sets attributes when values are present (per OpenTelemetry conventions).
+
+    Args:
+        event: API Gateway event object
+
+    Returns:
+        Dict with user.id, rebrandly.workspace, rebrandly.organization attributes (only if present)
+    """
+    attrs = {}
+    if not event or not isinstance(event, dict):
+        return attrs
+    authorizer = event.get('requestContext', {}).get('authorizer', {})
+
+    if not authorizer:
+        return attrs
+
+    user_id = authorizer.get('id')
+    if _is_valid_authorizer_value(user_id):
+        attrs[USER_ID] = str(user_id)
+
+    workspace = authorizer.get('workspace')
+    if _is_valid_authorizer_value(workspace):
+        attrs[REBRANDLY_WORKSPACE] = str(workspace)
+
+    organization = authorizer.get('organization')
+    if _is_valid_authorizer_value(organization):
+        attrs[REBRANDLY_ORGANIZATION] = str(organization)
+
+    return attrs
+
+
+def extract_api_gateway_http_attributes(event: Dict[str, Any]) -> Tuple[Dict[str, Any], Optional[str]]:
+    """
+    Extract HTTP semantic attributes from API Gateway event.
+    Supports both REST API (v1) and HTTP API (v2) formats.
+
+    Args:
+        event: API Gateway event object
+
+    Returns:
+        tuple: (attributes_dict, span_name)
+    """
+    attrs = {}
+
+    # Detect API Gateway v1 (REST) or v2 (HTTP API)
+    http_method = event.get('httpMethod') or (
+        event.get('requestContext', {}).get('http', {}).get('method')
+    )
+    if not http_method:
+        return attrs, None
+
+    # Extract path
+    path = event.get('path') or event.get('rawPath') or (
+        event.get('requestContext', {}).get('http', {}).get('path')
+    )
+
+    # Get request context
+    req_ctx = event.get('requestContext', {})
+    headers = event.get('headers') or {}
+
+    # Determine route pattern
+    if event.get('resource'):
+        route_pattern = event.get('resource')
+    elif event.get('routeKey'):
+        # HTTP API format (e.g., "GET /users/{id}") - strip the method prefix
+        route_pattern = re.sub(r'^[A-Z]+\s+', '', event.get('routeKey'))
+    else:
+        route_pattern = auto_detect_route_pattern(path) if path else '/'
+
+    # Build query string
+    query_params = event.get('queryStringParameters')
+    query_string = ''
+    if query_params:
+        query_string = urlencode(query_params)
+
+    # Extract server details
+    domain_name = req_ctx.get('domainName') or headers.get('host') or headers.get('Host')
+    protocol = req_ctx.get('protocol') or req_ctx.get('http', {}).get('protocol') or 'HTTP/1.1'
+
+    # Extract client IP (different locations for REST vs HTTP API)
+    client_ip = req_ctx.get('identity', {}).get('sourceIp') or req_ctx.get('http', {}).get('sourceIp')
+
+    # Extract user agent (case-insensitive header lookup)
+    user_agent = headers.get('user-agent') or headers.get('User-Agent')
+
+    # Set HTTP semantic attributes
+    attrs[HTTP_REQUEST_METHOD] = http_method
+    attrs[HTTP_ROUTE] = route_pattern
+    attrs[URL_PATH] = path
+    attrs[URL_SCHEME] = 'https'
+
+    if query_string:
+        attrs[URL_QUERY] = query_string
+
+    if domain_name:
+        attrs[SERVER_ADDRESS] = domain_name
+        attrs[SERVER_PORT] = 443
+        full_url = f"https://{domain_name}{path}"
+        if query_string:
+            full_url += f"?{query_string}"
+        attrs[URL_FULL] = full_url
+
+    if client_ip:
+        attrs[CLIENT_ADDRESS] = client_ip
+
+    if user_agent:
+        attrs[USER_AGENT_ORIGINAL] = user_agent
+
+    if protocol:
+        attrs[NETWORK_PROTOCOL_VERSION] = protocol
+
+    # Capture filtered headers (exclude sensitive ones)
+    if headers:
+        filtered_headers = filter_important_headers(headers)
+        if filtered_headers:
+            attrs[HTTP_REQUEST_HEADERS] = json.dumps(filtered_headers)
+        # Store traceparent for debugging/correlation
+        traceparent = headers.get('traceparent') or headers.get('Traceparent')
+        if traceparent:
+            attrs[HTTP_REQUEST_HEADER_TRACEPARENT] = traceparent
+
+    # Capture request body for POST/PUT/PATCH requests (with redaction)
+    body = event.get('body')
+    if body and http_method in ['POST', 'PUT', 'PATCH']:
+        content_type = headers.get('content-type') or headers.get('Content-Type')
+        captured_body = capture_request_body(body, content_type)
+        if captured_body:
+            attrs[HTTP_REQUEST_BODY] = captured_body
+
+    # Add request context ID for correlation
+    if req_ctx.get('requestId'):
+        attrs['http.request_id'] = req_ctx.get('requestId')
+
+    # Extract authorizer context (user, workspace, organization)
+    authorizer_attrs = extract_api_gateway_authorizer_attributes(event)
+    attrs.update(authorizer_attrs)
+
+    # Keep legacy attributes for backward compatibility
+    attrs['http.method'] = http_method
+    attrs['http.target'] = path + (f"?{query_string}" if query_string else '')
+    if domain_name:
+        attrs['http.scheme'] = 'https'
+        attrs['http.url'] = f"https://{domain_name}{path}" + (f"?{query_string}" if query_string else '')
+
+    # Build span name
+    span_name = f"{http_method} {route_pattern}"
+
+    return attrs, span_name
+
+
+def extract_api_gateway_context(event: Dict[str, Any]) -> Optional[Dict[str, str]]:
+    """
+    Extract trace context carrier from API Gateway headers.
+    Returns a dict with traceparent/tracestate if present.
+
+    Args:
+        event: API Gateway event object
+
+    Returns:
+        Dict with traceparent/tracestate if present, None otherwise
+    """
+    if not event or not isinstance(event, dict):
+        return None
+    headers = event.get('headers')
+    if not headers:
+        return None
+
+    # Normalize header keys to lowercase
+    normalized = {k.lower(): v for k, v in headers.items()}
+
+    carrier = {}
+    if 'traceparent' in normalized:
+        carrier['traceparent'] = normalized['traceparent']
+    if 'tracestate' in normalized:
+        carrier['tracestate'] = normalized['tracestate']
+
+    return carrier if carrier else None

rebrandly_otel/fastapi_support.py

@@ -0,0 +1,278 @@
+# fastapi_integration.py
+"""FastAPI integration for Rebrandly OTEL SDK."""
+import json
+from opentelemetry.trace import Status, StatusCode, SpanKind
+from .http_utils import filter_important_headers, capture_request_body, auto_detect_route_pattern
+from .http_constants import (
+    HTTP_REQUEST_METHOD,
+    HTTP_REQUEST_HEADERS,
+    HTTP_REQUEST_HEADER_TRACEPARENT,
+    HTTP_REQUEST_BODY,
+    HTTP_RESPONSE_STATUS_CODE,
+    HTTP_ROUTE,
+    URL_FULL,
+    URL_SCHEME,
+    URL_PATH,
+    URL_QUERY,
+    USER_AGENT_ORIGINAL,
+    NETWORK_PROTOCOL_VERSION,
+    SERVER_ADDRESS,
+    SERVER_PORT,
+    CLIENT_ADDRESS,
+    ERROR_TYPE
+)
+from .api_gateway_utils import extract_api_gateway_authorizer_attributes
+from fastapi import HTTPException, Depends
+from starlette.requests import Request
+from starlette.middleware.base import BaseHTTPMiddleware
+from fastapi.responses import JSONResponse
+
+import time
+
+def setup_fastapi(otel , app):
+    """
+    Setup FastAPI application with OTEL instrumentation.
+
+    Example:
+        from fastapi import FastAPI
+        from rebrandly_otel import otel
+        from rebrandly_otel.fastapi_integration import setup_fastapi
+
+        app = FastAPI()
+        setup_fastapi(otel, app)
+    """
+
+    # Add middleware
+    add_otel_middleware(otel, app)
+
+    # Add exception handlers
+    app.add_exception_handler(HTTPException, lambda request, exc: fastapi_exception_handler(otel, request, exc))
+    app.add_exception_handler(Exception, lambda request, exc: fastapi_exception_handler(otel, request, exc))
+
+    return app
+
+def add_otel_middleware(otel, app):
+    """
+    Add OTEL middleware to FastAPI application.
+    """
+
+    class OTELMiddleware(BaseHTTPMiddleware):
+        def __init__(self, app):
+            super().__init__(app)
+            self.otel = otel
+
+        async def dispatch(self, request: Request, call_next):
+            # Extract trace context from headers
+            headers = dict(request.headers)
+            token = self.otel.attach_context(headers)
+
+            # Initial span name - will be updated with route pattern after routing completes
+            # Using just method initially for low cardinality
+            span_name = f"{request.method}"
+
+            # Filter headers to keep only important ones
+            filtered_headers = filter_important_headers(headers)
+
+            # Capture request body if available (before span creation)
+            request_body = None
+            try:
+                content_type = request.headers.get('content-type', '')
+                # Read body (this caches it so FastAPI can still access it later)
+                body_bytes = await request.body()
+                # Try to parse as JSON, fallback to raw bytes
+                try:
+                    body = json.loads(body_bytes.decode('utf-8'))
+                except (json.JSONDecodeError, UnicodeDecodeError, ValueError):
+                    body = body_bytes
+
+                request_body = capture_request_body(body, content_type)
+            except Exception:
+                # Silently skip body capture if it fails
+                pass
+
+            # Build attributes dict, excluding None values
+            attributes = {
+                # Required HTTP attributes per semantic conventions
+                HTTP_REQUEST_METHOD: request.method,
+                HTTP_REQUEST_HEADERS: json.dumps(filtered_headers, default=str),
+                HTTP_REQUEST_HEADER_TRACEPARENT: headers.get('traceparent'),
+                HTTP_REQUEST_BODY: request_body,
+                URL_FULL: str(request.url),
+                URL_SCHEME: request.url.scheme,
+                URL_PATH: request.url.path,
+                NETWORK_PROTOCOL_VERSION: "1.1",  # FastAPI/Starlette typically uses HTTP/1.1
+                SERVER_ADDRESS: request.url.hostname,
+                SERVER_PORT: request.url.port or (443 if request.url.scheme == 'https' else 80),
+            }
+
+            # Add optional attributes only if they have values
+            if request.url.query:
+                attributes[URL_QUERY] = request.url.query
+
+            user_agent = request.headers.get("user-agent")
+            if user_agent:
+                attributes[USER_AGENT_ORIGINAL] = user_agent
+
+            if request.client and request.client.host:
+                attributes[CLIENT_ADDRESS] = request.client.host
+
+            # Extract authorizer context if available (when running behind API Gateway via Lambda)
+            # The Lambda handler should store the event in request.state.lambda_event
+            if hasattr(request.state, 'lambda_event') and request.state.lambda_event:
+                authorizer_attrs = extract_api_gateway_authorizer_attributes(request.state.lambda_event)
+                attributes.update(authorizer_attrs)
+
+            # Use start_as_current_span for proper context propagation
+            with self.otel.tracer.tracer.start_as_current_span(
+                    span_name,
+                    attributes=attributes,
+                    kind=SpanKind.SERVER
+            ) as span:
+                # Log request start
+                self.otel.logger.logger.info(f"Request started: {request.method} {request.url.path}",
+                                             extra={"http.method": request.method, "http.path": request.url.path})
+
+                # Store span in request state for access in routes
+                request.state.span = span
+                request.state.trace_token = token
+
+                start_time = time.time()
+
+                try:
+                    # Process request
+                    response = await call_next(request)
+
+                    # After routing completes, extract the route template
+                    # This is critical for OpenTelemetry compliance - http.route must be low cardinality
+                    route_pattern = None
+
+                    # Method 1: Get route from matched endpoint in scope
+                    # FastAPI/Starlette stores the matched route after routing completes
+                    if 'endpoint' in request.scope and 'router' in request.scope:
+                        endpoint = request.scope['endpoint']
+                        router = request.scope['router']
+
+                        # Find the route that matches this endpoint
+                        if hasattr(router, 'routes'):
+                            for route in router.routes:
+                                if hasattr(route, 'endpoint') and route.endpoint == endpoint:
+                                    if hasattr(route, 'path'):
+                                        route_pattern = route.path  # e.g., '/items/{item_id}'
+                                        break
+
+                    # Method 2: Fallback - auto-detect pattern from path using heuristics
+                    if not route_pattern:
+                        route_pattern = auto_detect_route_pattern(request.url.path)
+
+                    # Update span with route pattern (REQUIRED by OTEL spec)
+                    # Per spec: span name should be "{method} {http.route}" for low cardinality
+                    if route_pattern:
+                        span.update_name(f"{request.method} {route_pattern}")
+                        span.set_attribute(HTTP_ROUTE, route_pattern)
+
+                    # Set response attributes using semantic conventions
+                    span.set_attribute(HTTP_RESPONSE_STATUS_CODE, response.status_code)
+
+                    # Set span status based on HTTP status code following OpenTelemetry semantic conventions
+                    # For SERVER spans: only 5xx codes are marked as ERROR, all others left UNSET
+                    # Per spec: https://opentelemetry.io/docs/specs/semconv/http/http-spans/
+                    if response.status_code >= 500:
+                        span.set_status(Status(StatusCode.ERROR))
+                    # For all other codes (1xx, 2xx, 3xx, 4xx), leave status unset
+
+                    # Log request completion
+                    self.otel.logger.logger.info(f"Request completed: {response.status_code}",
+                                                 extra={"http.response.status_code": response.status_code})
+                    otel.force_flush(timeout_millis=100)
+                    return response
+
+                except Exception as e:
+                    # Record exception
+                    span.record_exception(e)
+                    span.set_status(Status(StatusCode.ERROR, str(e)))
+                    span.add_event("exception", {
+                        "exception.type": type(e).__name__,
+                        "exception.message": str(e)
+                    })
+
+                    # Log error
+                    self.otel.logger.logger.error(f"Unhandled exception: {e}",
+                                                  exc_info=True,
+                                                  extra={"exception.type": type(e).__name__})
+
+                    raise
+
+                finally:
+                    # Detach context
+                    self.otel.detach_context(token)
+
+    # Add middleware to app
+    app.add_middleware(OTELMiddleware)
+
+def fastapi_exception_handler(otel, request, exc):
+    """
+    Handle FastAPI exceptions and record them in the current span.
+    """
+
+    # Determine the status code
+    if isinstance(exc, HTTPException):
+        status_code = exc.status_code
+        error_detail = exc.detail
+    elif hasattr(exc, 'status_code'):
+        status_code = exc.status_code
+        error_detail = str(exc)
+    elif hasattr(exc, 'code'):
+        status_code = exc.code if isinstance(exc.code, int) else 500
+        error_detail = str(exc)
+    else:
+        status_code = 500
+        error_detail = str(exc)
+
+    # Record exception in span if available and still recording
+    if hasattr(request.state, 'span') and request.state.span.is_recording():
+        # Update response status code and error type
+        request.state.span.set_attribute(HTTP_RESPONSE_STATUS_CODE, status_code)
+        request.state.span.set_attribute(ERROR_TYPE, type(exc).__name__)
+
+        request.state.span.record_exception(exc)
+        request.state.span.set_status(Status(StatusCode.ERROR, str(exc)))
+        request.state.span.add_event("exception", {
+            "exception.type": type(exc).__name__,
+            "exception.message": str(exc)
+        })
+
+    # Log the error
+    otel.logger.logger.error(f"Unhandled exception: {exc} (status: {status_code})",
+                             exc_info=True,
+                             extra={
+                                 "exception.type": type(exc).__name__,
+                                 "http.response.status_code": status_code
+                             })
+
+    # Return error response
+    return JSONResponse(
+        status_code=status_code,
+        content={
+            "error": error_detail,
+            "type": type(exc).__name__
+        }
+    )
+
+# Optional: Dependency injection helper for accessing the span in routes
+def get_current_span(request: Request):
+    """
+    FastAPI dependency to get the current span in route handlers.
+
+    Example:
+        from fastapi import Depends
+        from rebrandly_otel.fastapi_integration import get_current_span
+
+        @app.get("/example")
+        async def example(span = Depends(get_current_span)):
+            if span:
+                span.add_event("custom_event", {"key": "value"})
+            return {"status": "ok"}
+    """
+    if hasattr(request.state, 'span'):
+        return request.state.span
+    return None