Understand the Framework

This article describes the troubleshooting framework built into the documentation, giving you a consistent way of thinking about the system—not just a list of commands.

Setting the stage: Before diving into specifics, here's a quick snapshot.

"Kubernetes-based platform with 60+ microservices that collects telemetry from sensors, processes it through a streaming pipeline, and serves insights via web UI and APIs."

The healthy state in one sentence:

• All pods running ✓
• Data flows sensor-to-UI in ~10 seconds ✓
• Users can log in and see current metrics ✓

Three Questions Framework

The diagnostic starting point: Use these three questions to quickly isolate the problem domain.

The logic:

• If login fails → Focus on Presentation Plane (Zitadel, PostgreSQL)
• If data is missing → Focus on Data Plane (Kafka, Ignite, Druid)
• If pods are down → Focus on Infrastructure (resources, PVCs, configs)

Three Planes Architecture

Organizing 60+ services: Services are organized into three logical planes to make the system comprehensible.

Presentation Plane (User-Facing)

This is what you and your users interact with directly. When a user reports they "can't access the system" or "the UI is broken," start here. These services handle authentication, serve the web interface, and expose APIs.

Data Plane (Telemetry Processing)

This is where the real work happens. Sensor data flows through these services to be ingested, processed, and stored. When users report "missing data," "stale metrics," or "dashboards not updating," investigate this plane.

Control Plane (Configuration)

These services manage how the platform is configured and how sensors are orchestrated. Issues here are often more subtle—sensors failing to register, configuration changes not taking effect, or tenant-specific problems. Check this plane when the system is "running" but not behaving as expected.

Data Flow Visualization

Tracing the happy path: The following diagram shows how data moves through the system, so you can trace backwards when something breaks.

Sensor → Sensor Collector → Fedex ⚠️ → Kafka → Ignite → Druid → Gather → UI

Key insight: When data is missing, trace backwards:

1. Is Druid ingesting? (Check supervisor status)
2. Is Kafka flowing? (Check consumer lag)
3. Is Sensor Collector receiving? (Check pod logs)
4. Is the sensor connected? (Check sensor status)

Expected latency: ~10 seconds end-to-end

Common Scenarios Mapping

Quick lookup: The following table maps common symptoms to likely causes and first checks.

Reference: Full Documentation Set

The following guides provide detailed procedures for each area covered in this overview. Use them as your go-to references when you need step-by-step instructions or deeper technical detail.