Monitoring & Operations

Monibuca V6 includes a comprehensive monitoring and operational analytics system, covering everything from real-time bitrate and framerate observation on individual streams to site-wide operational dashboards. No third-party monitoring tools required — it works out of the box.

Capabilities Overview

Dimension	Capability	Description
Stream-level	Real-time bitrate / framerate / GOP visualization	Per-frame waveforms + historical trend charts
Room-level	Sender ↔ Receiver pair analysis	Bitrate, freeze, packet loss, resolution — all dimensions
Live Operations	Site-wide real-time overview + 7-day trends	Sessions, audience, peak concurrent, revenue at a glance
Alerting	Anomaly detection + risk classification	Zero-viewer detection, freeze rate, packet loss spikes
Export	CSV export + JSON API	Integration with BI systems and custom analytics

Three-Tier Reporting System

Monibuca V6’s data collection is organized into three tiers, each serving a different purpose:

graph LR
    subgraph Client["Client SDK"]
        HB["HeartbeatReport<br/>(periodic)"]
        LR["LeaveRoomReport<br/>(on leave)"]
        KV["KVReport<br/>(event-driven)"]
    end

    subgraph Server["Room Service"]
        RS["ReportStorage"]
        DB["SQLx Database"]
        MEM["In-Memory Fallback"]
    end

    HB -->|every few seconds| RS
    LR -->|on leave| RS
    KV -->|event trigger| RS
    RS --> DB
    RS -.->|DB unavailable| MEM

1. Heartbeat Reports

Clients continuously report while in a room — the core source of quality data:

Category	Collected Data
Video	Bitrate (bps), frame rate (fps), resolution (W×H), codec, processed/dropped frames, freeze count & duration
Audio	Bitrate (bps), sample rate, channels, codec, volume level
Network	RTT (round-trip time), bitrate, packet loss rate
Device	Terminal type, device name, OS version, network type (WiFi/4G/5G)

Each heartbeat contains:

Upstream: Publisher’s own audio/video metrics
Downstream array: Per-subscriber receive metrics

Stored in report_heartbeats + report_heartbeat_downstream tables with time-range query support.

2. Leave Room Reports

Submitted when a user leaves the room — a complete session snapshot:

Room ID, User ID
Session start/end times, duration (joining_duration_ms)
Join request state, exit command timing
SDK version, device info
ClientJoinInfo context snapshot at join time

Stored in report_leave_rooms for session-level retrospective analysis.

3. KV Reports

Record standardized event counts as key-value pairs, covering 15+ critical operations:

Event Group	Tracked Data
`ENTER_ROOM` / `EXIT_ROOM`	Success rate, duration
`PUBLISH` / `SUBSCRIBE`	Success rate, duration
`START_AUDIO` / `START_VIDEO`	Audio/video enable success rate
`ICE_CONNECT`	WebRTC ICE connection success rate
`SIGNAL_CHANNEL_SETUP`	Signaling channel setup duration
`START_MICROPHONE` / `START_CAMERA`	Device access success rate
`PING`	Heartbeat round-trip time

Each event group includes: attempt count, success rate, and average cost (ms).

Stream-Level Real-Time Monitoring (Stream Detail)

The Admin console’s Stream Detail page provides deep real-time observation of individual streams — the primary tool for diagnosing audio/video quality issues.

Dual Display Modes

Mode	Use Case	Data Source
Historical Stats	Retrospective trend analysis	Periodic sampling, ECharts line charts
Real-time Waveform	Per-frame investigation	SSE live push, SVG waveform

Stats Mode Charts

Audio bitrate + frame rate: kbps line overlaid with fps curve
Video bitrate + frame rate: kbps line overlaid with fps curve
Video GOP trends: Group of Pictures size changes
Downstream bitrate distribution: Aggregate downstream bitrate across all subscribers

Real-time Waveform Mode

Real-time mode pushes per-frame data via SSE (Server-Sent Events), rendered as SVG bar charts:

🔴 Red bars: Video keyframes (I-frames), bar height proportional to frame size
🔵 Blue bars: Regular video frames (P/B frames)
Pause/resume SSE stream to capture specific time periods

Subscriber Snapshots

Displays real-time status for each subscriber:

Metric	Description
Plugin & type	Pull protocol source
Sync mode	Audio/video sync strategy
Buffer time	Playback buffer depth
Processed frames	Cumulative audio/video frame count
Dropped frames	Number of dropped frames
Late frames	Number of late-arriving frames

Typical Troubleshooting Scenarios

Issue	How to Observe
Insufficient publisher bitrate	Video bitrate consistently below expected levels
Excessive keyframe interval	Abnormal spikes in GOP trend chart
Subscriber stuttering	Subscriber dropped frame count growing
Encoder anomaly	Consecutive small frames or missing I-frames in waveform

Room-Level Quality Analysis (Room Report)

The Admin console’s Room Report page is designed for QoS troubleshooting and user experience analysis, supporting deep retrospective analysis of completed sessions.

Session Discovery & Filtering

Automatically discovers sessions by merging leave_reports + heartbeat_reports
Supports keyword search, user count range, and date range filtering
Export session lists to CSV

Intelligent User Role Detection

Automatically identifies user roles based on heartbeat patterns:

Role	Detection Criteria
🎙 Broadcaster	Has upstream publishing data
👁 Viewer	Only downstream data
🎧 Agent	Operator in customer service scenarios
👤 Guest	User in customer service scenarios

Bitrate Analysis Panel

UserBitratePanel provides two perspectives:

Sender view: User’s upstream bitrate over time
Receiver view: Downstream bitrate from each sender to this user
Toggle: All metrics / Video only / Audio only

Sender ↔ Receiver Pair Analysis

The most powerful troubleshooting tool — PairDetailView shows the complete transmission link between a sender and receiver:

Analysis Dimension	Sender Metrics	Receiver Metrics
Video	Capture frame rate, encode bitrate	Playback frame rate, decode bitrate
Video Quality	Resolution (W×H)	Freeze count/duration, packet loss
Audio	Capture volume, sample rate	Playback volume, channels
Network	Upload bitrate	RTT, total bitrate, packet loss

All charts are linked via ECharts Group Sync — dragging the timeline on any chart synchronizes all others for cross-comparison.

Event Timeline

Key events overlaid on bitrate charts:

User join/leave
Publish start/stop
Role changes

Live Operations Dashboard

The Admin console’s Live Dashboard is designed for operations staff and managers, providing site-wide real-time overview and trend analysis.

Real-Time Overview

Metric	Description
Total rooms	All rooms (including ended)
Currently live	Rooms with Living status
Total audience	Sum of all room audiences
Total likes	Current accumulated likes
Gift revenue	Current accumulated gift value

Today’s Statistics

Metric	Description
Sessions today	New live sessions started today
Rooms today	Deduplicated room count today
Users today	Deduplicated user count today
Peak concurrent	Highest simultaneous online count today
Total duration	Accumulated live streaming duration

7-Day Trend Charts

Daily granularity trends for:

📈 Session count trend
📈 Accumulated user trend
📈 Peak concurrent user trend

Data sourced from pre-aggregated report_live_daily_stats table.

Three Analysis Perspectives

Operations View

Live room list: status (Preparing/Living/Paused/Ended), viewer count, engagement data
Popularity ranking: based on (viewers × 3 + likes) formula
Room status distribution

Risk View

Anomaly detection: automatically identifies problematic rooms
Risk classification: High / Medium / Low / Normal
Risk reason annotations: abnormal freeze rate, bitrate drops, zero viewers
Filter by risk level

System View

Monitoring coverage: percentage of rooms being monitored
Health rate: stream availability health score
Zero-viewer detection: rooms that are live but have no audience
Data retention policy: current retention configuration

Auto-Refresh

The dashboard polls at 10-second intervals, supporting both silent refresh (background data update) and full refresh (UI update) modes.

Data Storage & Retention

Storage Architecture

Primary: SQLx async database for persistent storage with time-range queries
Fallback: Automatic switch to in-memory HashMap when database is unavailable
Write operations use async mpsc channels to avoid blocking the main business thread

Retention Policy

room:
  live:
    report_retention_days: 15   # Keep last 15 days (0 = keep forever)

Background cleanup tasks automatically delete expired records. Admin date pickers automatically disable out-of-range dates.

Integration with External Systems

JSON API

All monitoring data is accessible via HTTP JSON API for integration with external BI, alerting, and analytics systems:

Endpoint	Description
`GET /room_stats/{room_id}`	Detailed room statistics (supports time range)
`GET /all_room_stats`	Site-wide aggregate statistics
`GET /daily_stats`	Daily trend data
`POST /submit_report`	External service reporting endpoint

CSV Export

The Admin console supports exporting session lists to CSV files for offline analysis and reporting.

Best Practices

Troubleshooting Workflow

Discover issues: Find anomalous rooms in the Live Dashboard risk view
Locate room: Enter Room Report to view user list and roles
Compare bitrates: Use the bitrate analysis panel to compare sender and receiver data
Pair analysis: Select specific sender-receiver pairs for full-dimension metrics
Confirm root cause: Use the event timeline to correlate with the issue timestamp

Operational Decision Support

7-day trends to assess growth trajectory and campaign effectiveness
Peak concurrent for capacity planning and scaling decisions
Popularity ranking to discover top performers and optimize recommendations
Zero-viewer detection to promptly remove unwatched streams and optimize resources