Observability Guide - B2B2C Ecommerce Platform

Related docs: System Architecture · API Documentation

1. Accessing Dashboards

Access your dashboards at Middleware Console.

• API Performance: Overview of request rates, error rates, and latency.
• Payment Success: Tracking transaction success rates by provider (Flutterwave, Mock).
• ZRA Compliance: Monitoring TPIN and NRC validation rates and failure causes.

2. Troubleshooting with Logs

All logs are structured as JSON and include traceId correlation.

Example Queries:

• Find all logs for a specific order: orderId: "123-456"
• View all errors for ZRA validation: level: "ERROR" AND spanName: "zra.validate"
• Trace a single transaction across services: Filter by traceId in the Middleware Trace Explorer.

3. Interpreting Traces

Custom spans have been added for critical flows:

• checkout.complete: Measures the end-to-end checkout process.
• payment.process: Measures gateway communication time.
• zra.validate: Measures compliance API response times.

Slow checkout? Look at the payment.process child span to see if the gateway is the bottleneck.

4. Custom Spans & Events

The platform utilizes custom instrumentation to track high-value business operations. Developers add spans to critical logic blocks to capture operation duration and success metrics, which are then fanned out to the Middleware.io dashboard.

5. Alert Response Runbook

Alert	Impact	Action
payment_error_rate > 5%	Customers cannot pay	Check payment.process logs. Verify gateway API status.
p95_latency_spike	Slow user experience	Check database and third-party API response times.
unhandled_exception	Potential platform crash	Identify the failing request via traceId.

6. System Toggle

Observability can be toggled via centralized environment configuration if required for maintenance or high-load events.