# Python: Install the auto-instrumentation package
# pip install opentelemetry-distro opentelemetry-exporter-otlp

# This instruments Flask, FastAPI, requests, sqlalchemy, redis, etc. automatically
# No code changes required

# requirements.txt
opentelemetry-distro==0.45b0
opentelemetry-exporter-otlp-proto-grpc==1.24.0
opentelemetry-instrumentation-fastapi==0.45b0
opentelemetry-instrumentation-sqlalchemy==0.45b0
opentelemetry-instrumentation-redis==0.45b0
opentelemetry-instrumentation-httpx==0.45b0

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode
from functools import wraps
import time

tracer = trace.get_tracer(__name__)

def traced(span_name: str = None, attributes: dict = None):
    """Decorator for adding spans to business logic functions."""
    def decorator(func):
        @wraps(func)
        async def async_wrapper(*args, **kwargs):
            name = span_name or f"{func.__module__}.{func.__qualname__}"
            with tracer.start_as_current_span(name) as span:
                if attributes:
                    for key, value in attributes.items():
                        span.set_attribute(key, value)
                try:
                    result = await func(*args, **kwargs)
                    span.set_status(Status(StatusCode.OK))
                    return result
                except Exception as e:
                    span.set_status(Status(StatusCode.ERROR, str(e)))
                    span.record_exception(e)
                    raise
        
        @wraps(func)
        def sync_wrapper(*args, **kwargs):
            name = span_name or f"{func.__module__}.{func.__qualname__}"
            with tracer.start_as_current_span(name) as span:
                if attributes:
                    for key, value in attributes.items():
                        span.set_attribute(key, value)
                try:
                    result = func(*args, **kwargs)
                    span.set_status(Status(StatusCode.OK))
                    return result
                except Exception as e:
                    span.set_status(Status(StatusCode.ERROR, str(e)))
                    span.record_exception(e)
                    raise
        
        import asyncio
        return async_wrapper if asyncio.iscoroutinefunction(func) else sync_wrapper
    return decorator


class OrderService:
    @traced("order.process_payment")
    async def process_payment(self, order_id: str, amount: float) -> bool:
        span = trace.get_current_span()
        span.set_attribute("order.id", order_id)
        span.set_attribute("payment.amount", amount)
        span.set_attribute("payment.currency", "USD")
        
        # Add events for important milestones
        span.add_event("payment.validation.started")
        
        if amount <= 0:
            span.set_status(Status(StatusCode.ERROR, "Invalid amount"))
            return False
        
        span.add_event("payment.gateway.called", {
            "gateway": "stripe",
            "retry_count": 0
        })
        
        # ... actual payment logic ...
        
        span.add_event("payment.succeeded")
        span.set_attribute("payment.transaction_id", "txn_abc123")
        return True

# BAD: user_id has millions of unique values
# This creates millions of time series and crashes your metrics backend
span.set_attribute("user.id", user_id)  # As a metric label

# BAD: Request URL includes dynamic IDs
span.set_attribute("http.url", f"/api/users/{user_id}/orders")

# GOOD: Use route pattern, not actual URL
span.set_attribute("http.route", "/api/users/{user_id}/orders")

# GOOD: Use low-cardinality bucketed values
def categorize_user(user_id: str) -> str:
    # Return bucketed label instead of raw ID
    tier = get_user_tier(user_id)  # "free", "pro", "enterprise"
    return tier

span.set_attribute("user.tier", categorize_user(user_id))

# GOOD: Use histograms instead of per-user gauges
from opentelemetry import metrics

meter = metrics.get_meter(__name__)
request_duration = meter.create_histogram(
    "http.server.duration",
    unit="ms",
    description="HTTP request duration",
    # Explicit buckets tailored to your SLAs
    # (use ExplicitBucketHistogramAggregation in SDK config)
)

import logging
from opentelemetry import trace
from opentelemetry.instrumentation.logging import LoggingInstrumentor

# Automatically inject trace_id and span_id into log records
LoggingInstrumentor().instrument(set_logging_format=True)

# Configure structured logging
import structlog

structlog.configure(
    processors=[
        structlog.processors.add_log_level,
        structlog.processors.TimeStamper(fmt="iso"),
        # Add OTel trace context to every log entry
        structlog.processors.CallsiteParameterAdder([
            structlog.processors.CallsiteParameter.FUNC_NAME,
        ]),
        structlog.processors.JSONRenderer()
    ]
)

logger = structlog.get_logger()

class PaymentProcessor:
    async def charge(self, order_id: str, amount: float):
        with trace.get_tracer(__name__).start_as_current_span("payment.charge") as span:
            span.set_attribute("order.id", order_id)
            
            # This log will automatically include trace_id and span_id
            # enabling direct correlation in your observability backend
            logger.info(
                "processing_payment",
                order_id=order_id,
                amount=amount,
                # trace_id and span_id are injected automatically
            )
            
            try:
                result = await self._call_payment_gateway(amount)
                logger.info("payment_succeeded", order_id=order_id, transaction_id=result.id)
                return result
            except PaymentGatewayError as e:
                logger.error(
                    "payment_failed",
                    order_id=order_id,
                    error_code=e.code,
                    error_message=str(e)
                )
                raise

# Head-based sampling: decision made at trace start
# Fast, low overhead, but misses unexpected errors

# Tail-based sampling: decision made after trace completes
# Sees full trace, keeps errors/slow requests, better for debugging

# Recommended hybrid approach:

from opentelemetry.sdk.trace.sampling import (
    ParentBased,
    TraceIdRatioBased,
    ALWAYS_ON,
    ALWAYS_OFF
)

class AdaptiveSampler:
    """
    - Always sample errors
    - Always sample traces > 500ms
    - Sample 1% of healthy fast traces
    - Always sample traces from new deployments (first 5 min)
    """
    
    def __init__(self, base_rate: float = 0.01):
        self.base_rate = base_rate
        self.random_sampler = TraceIdRatioBased(base_rate)
    
    def should_sample(
        self,
        parent_context,
        trace_id: int,
        name: str,
        kind,
        attributes: dict,
        links: list
    ):
        # Always sample if explicitly flagged
        if attributes.get("sampling.force"):
            return ALWAYS_ON.should_sample(parent_context, trace_id, name, kind, attributes, links)
        
        # Defer to parent's sampling decision if exists
        if parent_context and parent_context.is_valid:
            return ParentBased(ALWAYS_ON).should_sample(
                parent_context, trace_id, name, kind, attributes, links
            )
        
        # Otherwise, apply base rate sampling
        return self.random_sampler.should_sample(
            parent_context, trace_id, name, kind, attributes, links
        )