# ❌ Without observability - debugging is painful
@app.post("/orders")
async def create_order(data: dict):
    # Why is this slow?
    # Which service failed?
    # How many orders per minute?
    # What's the error rate?
    order = await order_service.create(data)
    return order

# ✅ With observability - full visibility
from neuroglia.observability import Observability

builder = WebApplicationBuilder(app_settings)
Observability.configure(builder)  # Automatic instrumentation!

# Now you get:
# - Automatic request tracing
# - Response time metrics
# - Correlated logs with trace IDs
# - Service dependency maps
# - Error rate tracking
# - System metrics (CPU, memory)

orders_created_total = 1,247  # Counter
active_users = 32             # Gauge
request_duration_ms = [12, 45, 23, 67, ...]  # Histogram

from neuroglia.hosting.web import WebApplicationBuilder
from neuroglia.observability import Observability, ApplicationSettingsWithObservability

# Step 1: Use settings class with observability
class PizzeriaSettings(ApplicationSettingsWithObservability):
    # Your app settings
    database_url: str = Field(default="mongodb://localhost:27017")

    # Observability settings inherited:
    # - service_name, service_version, deployment_environment
    # - otel_enabled, otel_endpoint, tracing_enabled, metrics_enabled
    # - instrument_fastapi, instrument_httpx, instrument_logging

# Step 2: Configure observability
builder = WebApplicationBuilder(PizzeriaSettings())
Observability.configure(builder)  # Uses settings automatically

# Step 3: Build and run
app = builder.build()
app.run()

# 🎉 You now have:
# - /metrics endpoint with Prometheus metrics
# - /health endpoint with service health
# - Distributed tracing to OTLP collector
# - Structured logs with trace correlation

from neuroglia.observability import configure_opentelemetry

# Configure OpenTelemetry directly
configure_opentelemetry(
    service_name="mario-pizzeria",
    service_version="1.0.0",
    otlp_endpoint="http://otel-collector:4317",
    enable_console_export=False,  # Set True for debugging
    deployment_environment="production",

    # Instrumentation toggles
    enable_fastapi_instrumentation=True,
    enable_httpx_instrumentation=True,
    enable_logging_instrumentation=True,
    enable_system_metrics=True,

    # Performance tuning
    batch_span_processor_max_queue_size=2048,
    batch_span_processor_schedule_delay_millis=5000,
    metric_export_interval_millis=60000  # 1 minute
)

from neuroglia.observability import Observability

# Basic configuration
Observability.configure(builder)

# With overrides
Observability.configure(
    builder,
    tracing_enabled=True,      # Override from settings
    metrics_enabled=True,      # Override from settings
    logging_enabled=True       # Override from settings
)

from neuroglia.observability import trace_async, get_tracer, add_span_attributes

# Automatic tracing with decorator
@trace_async(name="create_order")  # Custom span name
async def create_order(order_data: dict):
    # Span automatically created and closed

    # Add custom attributes
    add_span_attributes({
        "order.id": order_data["id"],
        "order.total": order_data["total"],
        "customer.type": "premium"
    })

    # Call other services - trace propagates automatically
    await payment_service.charge(order_data["total"])
    await inventory_service.reserve(order_data["items"])

    return order

# Manual tracing for fine control
tracer = get_tracer(__name__)

async def process_payment(amount: float):
    with tracer.start_as_current_span("payment_processing") as span:
        span.set_attribute("payment.amount", amount)

        # Add events for important moments
        from neuroglia.observability import add_span_event
        add_span_event("payment_validated", {
            "validation_result": "approved"
        })

        result = await payment_gateway.charge(amount)
        span.set_attribute("payment.transaction_id", result.transaction_id)

        return result

from neuroglia.observability import get_meter, create_counter, create_histogram

# Get meter for your component
meter = get_meter(__name__)

# Create metrics
order_counter = create_counter(
    meter,
    name="orders_created_total",
    description="Total number of orders created",
    unit="orders"
)

order_value_histogram = create_histogram(
    meter,
    name="order_value",
    description="Distribution of order values",
    unit="USD"
)

# Record metrics
def record_order_created(order: Order):
    order_counter.add(1, {
        "order.type": order.order_type,
        "customer.segment": order.customer_segment
    })

    order_value_histogram.record(order.total_amount, {
        "order.type": order.order_type
    })

from neuroglia.observability import get_logger_with_trace_context, log_with_trace
import logging

# Get logger with automatic trace correlation
logger = get_logger_with_trace_context(__name__)

async def process_order(order_id: str):
    # Logs automatically include trace_id and span_id
    logger.info(f"Processing order: {order_id}")

    try:
        result = await order_service.process(order_id)
        logger.info(f"Order processed successfully: {order_id}")
        return result
    except Exception as e:
        # Exception automatically recorded in current span
        logger.error(f"Order processing failed: {order_id}", exc_info=True)

        # Record exception in span
        from neuroglia.observability import record_exception
        record_exception(e)
        raise

# Manual trace correlation
log_with_trace(
    logger.info,
    "Custom log message",
    extra_attributes={"custom.field": "value"}
)

from neuroglia.mvc import ControllerBase
from neuroglia.observability import add_span_attributes, add_span_event
from classy_fastapi.decorators import post

class OrdersController(ControllerBase):

    @post("/", response_model=OrderDto, status_code=201)
    async def create_order(self, dto: CreateOrderDto) -> OrderDto:
        """Create order - automatically traced by FastAPI instrumentation"""

        # Add custom attributes to the current HTTP span
        add_span_attributes({
            "order.total_amount": dto.total_amount,
            "order.item_count": len(dto.items),
            "customer.type": dto.customer_type,
            "http.route.template": "/api/orders"
        })

        # Record important events
        add_span_event("order_validation_started", {
            "validation.rules": ["amount", "items", "customer"]
        })

        # Delegate to mediator (automatically creates child spans)
        command = self.mapper.map(dto, CreateOrderCommand)
        result = await self.mediator.execute_async(command)

        add_span_event("order_created", {
            "order.id": result.data.id
        })

        return self.process(result)

from neuroglia.mediation import CommandHandler
from neuroglia.observability import trace_async, get_meter, add_span_attributes

class CreateOrderHandler(CommandHandler[CreateOrderCommand, OperationResult[OrderDto]]):

    def __init__(self, order_repository, payment_service, inventory_service):
        self.order_repository = order_repository
        self.payment_service = payment_service
        self.inventory_service = inventory_service

        # Create metrics for this handler
        meter = get_meter(__name__)
        self.orders_created = meter.create_counter(
            "orders_created_total",
            description="Total orders created",
            unit="orders"
        )
        self.order_value = meter.create_histogram(
            "order_value_usd",
            description="Order value distribution",
            unit="USD"
        )

    @trace_async(name="create_order_handler")
    async def handle_async(self, command: CreateOrderCommand) -> OperationResult[OrderDto]:
        """Handle order creation with full observability"""

        # Add command details to span
        add_span_attributes({
            "command.type": "CreateOrderCommand",
            "order.customer_id": command.customer_id,
            "order.total": command.total_amount
        })

        try:
            # Each of these creates child spans automatically
            await self._validate_order(command)
            await self._check_inventory(command)
            await self._process_payment(command)

            # Create order entity
            order = Order(
                customer_id=command.customer_id,
                items=command.items,
                total_amount=command.total_amount
            )

            # Save (repository creates its own span)
            await self.order_repository.save_async(order)

            # Record metrics
            self.orders_created.add(1, {
                "customer.type": command.customer_type,
                "order.channel": "web"
            })
            self.order_value.record(command.total_amount, {
                "customer.type": command.customer_type
            })

            return self.created(self.mapper.map(order, OrderDto))

        except PaymentError as e:
            add_span_attributes({"error": True, "error.type": "payment_failed"})
            return self.bad_request(f"Payment failed: {str(e)}")

    @trace_async(name="validate_order")
    async def _validate_order(self, command: CreateOrderCommand):
        """Validation logic with its own span"""
        add_span_attributes({"validation.rules_count": 3})
        # Validation logic...

    @trace_async(name="check_inventory")
    async def _check_inventory(self, command: CreateOrderCommand):
        """Inventory check with its own span"""
        # Inventory logic...

    @trace_async(name="process_payment")
    async def _process_payment(self, command: CreateOrderCommand):
        """Payment processing with its own span"""
        # Payment logic...

from neuroglia.data import AggregateRoot, DomainEvent
from neuroglia.observability import trace_async, add_span_attributes, add_span_event

class Order(AggregateRoot):
    """Order aggregate with observability"""

    def __init__(self, customer_id: str, items: list, total_amount: float):
        super().__init__()
        self.customer_id = customer_id
        self.items = items
        self.total_amount = total_amount
        self.status = "pending"

        # Raise domain event
        self.raise_event(OrderCreatedEvent(
            order_id=self.id,
            customer_id=customer_id,
            total_amount=total_amount
        ))

    @trace_async(name="order.validate")
    def validate(self):
        """Complex validation logic"""
        add_span_attributes({
            "order.items_count": len(self.items),
            "order.total": self.total_amount
        })

        if self.total_amount < 10:
            add_span_event("validation_failed", {
                "reason": "minimum_amount_not_met"
            })
            raise ValueError("Minimum order amount is $10")

        add_span_event("validation_passed")

    @trace_async(name="order.calculate_tax")
    def calculate_tax(self, tax_rate: float) -> float:
        """Tax calculation"""
        tax = self.total_amount * tax_rate
        add_span_attributes({
            "tax.rate": tax_rate,
            "tax.amount": tax
        })
        return tax

from neuroglia.data import Repository
from neuroglia.observability import trace_async, add_span_attributes
from motor.motor_asyncio import AsyncIOMotorClient

class MongoOrderRepository(Repository[Order, str]):

    def __init__(self, mongo_client: AsyncIOMotorClient):
        self.collection = mongo_client.pizzeria.orders

    @trace_async(name="repository.save_order")
    async def save_async(self, order: Order) -> None:
        """Save order with tracing"""
        add_span_attributes({
            "db.system": "mongodb",
            "db.operation": "insert",
            "db.collection": "orders",
            "order.id": order.id
        })

        document = self._to_document(order)
        result = await self.collection.insert_one(document)

        add_span_attributes({
            "db.inserted_id": str(result.inserted_id),
            "db.success": result.acknowledged
        })

    @trace_async(name="repository.get_order")
    async def get_by_id_async(self, order_id: str) -> Optional[Order]:
        """Get order by ID with tracing"""
        add_span_attributes({
            "db.system": "mongodb",
            "db.operation": "findOne",
            "db.collection": "orders",
            "order.id": order_id
        })

        document = await self.collection.find_one({"_id": order_id})

        add_span_attributes({
            "db.found": document is not None
        })

        return self._from_document(document) if document else None

from neuroglia.integration import HttpServiceClient
from neuroglia.observability import add_span_attributes

class PaymentServiceClient:

    def __init__(self, http_client: HttpServiceClient):
        self.client = http_client

    async def process_payment(self, amount: float, card_token: str) -> PaymentResult:
        """Process payment - HTTPX automatically creates spans"""

        # HTTPX instrumentation will create a span automatically
        # But we can add context to the current span
        add_span_attributes({
            "payment.amount": amount,
            "payment.provider": "stripe"
        })

        response = await self.client.post(
            "/api/payments",
            json={
                "amount": amount,
                "card_token": card_token
            }
        )

        add_span_attributes({
            "payment.transaction_id": response.json()["transaction_id"],
            "payment.status": response.json()["status"]
        })

        return PaymentResult.from_json(response.json())

from neuroglia.observability import get_meter

meter = get_meter(__name__)

# Create counter
orders_total = meter.create_counter(
    "orders_created_total",
    description="Total number of orders created since start",
    unit="orders"
)

# Increment counter
orders_total.add(1, {
    "customer.type": "premium",
    "payment.method": "credit_card"
})

# Create gauge
active_orders = meter.create_up_down_counter(
    "active_orders_current",
    description="Number of orders currently being processed",
    unit="orders"
)

# Increase when order starts
active_orders.add(1, {"kitchen.station": "pizza"})

# Decrease when order completes
active_orders.add(-1, {"kitchen.station": "pizza"})

# Create histogram
order_value_histogram = meter.create_histogram(
    "order_value_usd",
    description="Distribution of order values",
    unit="USD"
)

# Record observations
order_value_histogram.record(45.99, {"customer.type": "regular"})
order_value_histogram.record(125.50, {"customer.type": "premium"})
order_value_histogram.record(22.00, {"customer.type": "regular"})

from neuroglia.observability import get_meter

meter = get_meter("mario.pizzeria")

# Counter: Track total pizzas made
pizzas_made = meter.create_counter(
    "pizzas_made_total",
    description="Total pizzas prepared",
    unit="pizzas"
)
pizzas_made.add(1, {"type": "margherita", "size": "large"})

# Gauge: Track current oven temperature
oven_temp = meter.create_up_down_counter(
    "oven_temperature_celsius",
    description="Current oven temperature",
    unit="celsius"
)
oven_temp.add(25, {})  # Heating up
oven_temp.add(-5, {})  # Cooling down

# Histogram: Track pizza prep time
prep_time = meter.create_histogram(
    "pizza_prep_duration_seconds",
    description="Time to prepare a pizza",
    unit="seconds"
)
prep_time.record(180, {"type": "margherita"})  # 3 minutes
prep_time.record(420, {"type": "suprema"})     # 7 minutes

# In your application code
from neuroglia.observability import trace_async, get_meter

@trace_async(name="process_order")
async def process_order(order_id: str):
    # Creates a span
    meter = get_meter(__name__)
    counter = meter.create_counter("orders_processed")
    counter.add(1)  # Records a metric
    logger.info(f"Processing {order_id}")  # Writes a log

# Configured in neuroglia.observability
configure_opentelemetry(
    batch_span_processor_max_queue_size=2048,
    batch_span_processor_schedule_delay_millis=5000,  # Export every 5s
    metric_export_interval_millis=60000  # Export every 60s
)

# settings.py
from neuroglia.observability import ApplicationSettingsWithObservability
from pydantic import Field

class PizzeriaSettings(ApplicationSettingsWithObservability):
    # Application settings
    database_url: str = Field(default="mongodb://localhost:27017")
    redis_url: str = Field(default="redis://localhost:6379")

    # Observability settings (inherited):
    # service_name: str = "mario-pizzeria"
    # service_version: str = "1.0.0"
    # otel_enabled: bool = True
    # otel_endpoint: str = "http://otel-collector:4317"
    # tracing_enabled: bool = True
    # metrics_enabled: bool = True
    # logging_enabled: bool = True

# main.py
from neuroglia.hosting.web import WebApplicationBuilder
from neuroglia.observability import Observability

def create_app():
    # Load settings from environment
    settings = PizzeriaSettings()

    # Create builder with observability-enabled settings
    builder = WebApplicationBuilder(settings)

    # Configure core services
    Mediator.configure(builder, ["application.commands", "application.queries"])
    Mapper.configure(builder, ["application.mapping", "api.dtos"])

    # Register application services
    builder.services.add_scoped(IOrderRepository, MongoOrderRepository)
    builder.services.add_scoped(OrderService)

    # Configure observability (automatic!)
    Observability.configure(builder)

    # Add SubApp with controllers
    builder.add_sub_app(
        SubAppConfig(
            path="/api",
            name="api",
            controllers=["api.controllers"]
        )
    )

    # Build application
    app = builder.build_app_with_lifespan(
        title="Mario's Pizzeria API",
        version="1.0.0"
    )

from neuroglia.observability import configure_opentelemetry

configure_opentelemetry(
    service_name="mario-pizzeria",
    service_version="1.0.0",
    additional_resource_attributes={
        "deployment.region": "us-east-1",
        "deployment.zone": "zone-a",
        "environment": "production",
        "team": "backend",
        "cost_center": "engineering"
    }
)

# All traces, metrics, and logs now include these attributes

from neuroglia.observability import get_tracer, trace_sync

tracer = get_tracer(__name__)

# Async function tracing
@trace_async(name="complex_calculation")
async def complex_calculation(data: list):
    with tracer.start_as_current_span("data_validation"):
        validated = validate_data(data)

    with tracer.start_as_current_span("processing"):
        result = await process_data(validated)

    with tracer.start_as_current_span("persistence"):
        await save_result(result)

    return result

# Sync function tracing
@trace_sync(name="legacy_sync_function")
def legacy_function(x: int) -> int:
    return x * 2

from neuroglia.observability import configure_opentelemetry

configure_opentelemetry(
    service_name="high-throughput-service",

    # Increase queue size for high request volume
    batch_span_processor_max_queue_size=8192,  # Default: 2048

    # Export more frequently
    batch_span_processor_schedule_delay_millis=2000,  # Default: 5000 (5s)

    # Larger export batches
    batch_span_processor_max_export_batch_size=1024,  # Default: 512

    # Metrics export every 30 seconds instead of 60
    metric_export_interval_millis=30000,
    metric_export_timeout_millis=15000
)

from neuroglia.observability import add_baggage, get_baggage
import httpx

async def call_external_service():
    # Add baggage (propagates with trace)
    add_baggage("user.id", "user_123")
    add_baggage("request.priority", "high")

    # HTTPx automatically includes trace headers
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://other-service/api/process",
            json={"data": "value"}
        )
        # Trace context automatically propagated!

# In the other service:
async def process_request():
    # Retrieve baggage
    user_id = get_baggage("user.id")  # "user_123"
    priority = get_baggage("request.priority")  # "high"

from pydantic import Field

class PizzeriaSettings(ApplicationSettingsWithObservability):
    # Fine-grained control over instrumentation
    otel_instrument_fastapi: bool = Field(default=True)
    otel_instrument_httpx: bool = Field(default=True)
    otel_instrument_logging: bool = Field(default=True)
    otel_instrument_system_metrics: bool = Field(default=False)  # Disable for serverless

builder = WebApplicationBuilder(settings)
Observability.configure(builder)  # Respects instrumentation flags

import pytest
from neuroglia.observability import configure_opentelemetry, get_tracer, get_meter

@pytest.fixture
def observability_configured():
    """Configure observability for tests"""
    configure_opentelemetry(
        service_name="mario-pizzeria-test",
        service_version="test",
        enable_console_export=True,  # See traces in test output
        otlp_endpoint="http://localhost:4317"
    )
    yield

    from neuroglia.observability import shutdown_opentelemetry
    shutdown_opentelemetry()

@pytest.mark.asyncio
async def test_order_handler_creates_span(observability_configured):
    """Test that handler creates trace span"""
    tracer = get_tracer(__name__)

    # Execute handler
    handler = CreateOrderHandler(mock_repository, mock_payment)
    command = CreateOrderCommand(customer_id="123", items=[], total_amount=50.0)

    with tracer.start_as_current_span("test_span") as span:
        result = await handler.handle_async(command)

        # Verify span created
        assert span.is_recording()
        assert result.is_success

@pytest.mark.asyncio
async def test_metrics_recorded():
    """Test that metrics are recorded correctly"""
    meter = get_meter(__name__)
    counter = meter.create_counter("test_counter")

    # Record metric
    counter.add(1, {"test": "value"})

    # Verify (in real tests, you'd check Prometheus endpoint)
    # In tests, just verify no exceptions
    assert True

# ❌ Wrong - observability not configured
app = FastAPI()
uvicorn.run(app)  # No traces, no metrics

# ✅ Correct - configure during app setup
builder = WebApplicationBuilder(settings)
Observability.configure(builder)
app = builder.build()
uvicorn.run(app)  # Full observability!

# ❌ Wrong - duplicate instrumentation
from neuroglia.observability import instrument_fastapi_app

app = FastAPI()
api_app = FastAPI()
app.mount("/api", api_app)

instrument_fastapi_app(app, "main")
instrument_fastapi_app(api_app, "api")  # Causes warnings!

# ✅ Correct - only instrument main app
instrument_fastapi_app(app, "main")  # Captures all endpoints

# ❌ Wrong - no observability settings
class MySettings(ApplicationSettings):
    database_url: str

builder = WebApplicationBuilder(MySettings())
Observability.configure(builder)  # Raises ValueError!

# ✅ Correct - inherit from ApplicationSettingsWithObservability
class MySettings(ApplicationSettingsWithObservability):
    database_url: str

builder = WebApplicationBuilder(MySettings())
Observability.configure(builder)  # Works!

# Consider lightweight alternatives:
# - CloudWatch Logs only
# - X-Ray for tracing
# - Custom metrics to CloudWatch

# Consider:
# - Sampling traces (only 1% of requests)
# - Tail-based sampling
# - Metrics-only observability
# - Custom lightweight instrumentation

# Simple logging may be sufficient:
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
logger.info("Order created")

@classmethod
def configure(
    cls,
    builder: WebApplicationBuilder,
    **overrides
) -> None:
    """
    Configure comprehensive observability for the application.

    Args:
        builder: WebApplicationBuilder with app_settings
        **overrides: Optional configuration overrides
                     (tracing_enabled, metrics_enabled, logging_enabled)

    Raises:
        ValueError: If app_settings doesn't have observability configuration
    """

def configure_opentelemetry(
    service_name: str,
    service_version: str = "unknown",
    otlp_endpoint: str = "http://localhost:4317",
    enable_console_export: bool = False,
    deployment_environment: str = "development",
    additional_resource_attributes: Optional[dict[str, str]] = None,
    enable_fastapi_instrumentation: bool = True,
    enable_httpx_instrumentation: bool = True,
    enable_logging_instrumentation: bool = True,
    enable_system_metrics: bool = False,
    batch_span_processor_max_queue_size: int = 2048,
    batch_span_processor_schedule_delay_millis: int = 5000,
    batch_span_processor_max_export_batch_size: int = 512,
    metric_export_interval_millis: int = 60000,
    metric_export_timeout_millis: int = 30000
) -> None:
    """
    Configure OpenTelemetry SDK with comprehensive observability setup.

    Initializes tracing, metrics, logging, and instrumentation.
    """

def trace_async(name: Optional[str] = None) -> Callable:
    """
    Decorator for automatic async function tracing.

    Args:
        name: Optional span name (defaults to function name)

    Returns:
        Decorator function
    """

def trace_sync(name: Optional[str] = None) -> Callable:
    """
    Decorator for automatic sync function tracing.

    Args:
        name: Optional span name (defaults to function name)

    Returns:
        Decorator function
    """

def get_tracer(name: str) -> Tracer:
    """
    Get a tracer instance for manual instrumentation.

    Args:
        name: Tracer name (typically __name__)

    Returns:
        OpenTelemetry Tracer instance
    """

def get_meter(name: str) -> Meter:
    """
    Get a meter instance for creating metrics.

    Args:
        name: Meter name (typically __name__)

    Returns:
        OpenTelemetry Meter instance
    """

class ApplicationSettingsWithObservability(ApplicationSettings, ObservabilitySettingsMixin):
    """
    Base settings class with built-in observability configuration.

    Attributes:
        service_name: str = Field(default="neuroglia-service")
        service_version: str = Field(default="1.0.0")
        deployment_environment: str = Field(default="development")
        otel_enabled: bool = Field(default=True)
        otel_endpoint: str = Field(default="http://localhost:4317")
        otel_console_export: bool = Field(default=False)
        tracing_enabled: bool = Field(default=True)
        metrics_enabled: bool = Field(default=True)
        logging_enabled: bool = Field(default=True)
        instrument_fastapi: bool = Field(default=True)
        instrument_httpx: bool = Field(default=True)
        instrument_logging: bool = Field(default=True)
        instrument_system_metrics: bool = Field(default=True)
    """