OpenQoE

Open-Source Video Quality of Experience (QoE) Monitoring Platform

Production-grade video quality monitoring for web video players with comprehensive business and technical metrics, accurate percentile calculations, real-time alerting, and distributed tracing.

Guarantee of p90 request latency of <=30ms for event insgestion under any load

🎯 Overview

OpenQoE is a complete, production-ready observability platform for video streaming that helps you:

Monitor Quality: Track video startup time, rebuffering, errors, and playback quality
Understand Engagement: Measure watch time, completion rates, and viewer behavior
Optimize Performance: Identify bottlenecks with P50/P95/P99 percentile analysis
Alert Proactively: Get notified when quality degrades or business metrics drop
Scale Globally: Deploy on Cloudflare's edge network or self-host

What's Included

Component	Description	Status
JavaScript SDK	5 player adapters capturing 24+ event types	✅ Dash.js Ready / 🏗️ Others WIP
Go Worker	High-performance OTLP ingestion & processing	✅ Production Ready
Grafana Alloy	Edge telemetry collector & processor	✅ Production Ready
Grafana Dashboards	4 comprehensive dashboards (58 panels total)	✅ Production Ready
Recording Rules	25 pre-aggregated metrics for performance	✅ Production Ready
Alert Rules	18 production-ready alerts	✅ Production Ready
Distributed Tracing	End-to-end tracing with Grafana Tempo	✅ Production Ready
Docker Stack	Self-hosted Mimir + Loki + Tempo + Alloy	✅ Production Ready

✨ Features

SDK Capabilities

✅ Multi-Player Support: HTML5, Video.js, HLS.js, Dash.js, Shaka Player
✅ Dash.js Production Ready: Robust integration for MPEG-DASH
🏗️ WIP Adapters: Other players are in active development
✅ Comprehensive Events: 24+ event types with full context capture
✅ Privacy-First: SHA-256 hashing, configurable PII controls
✅ Lightweight: ~10KB gzipped per adapter
✅ TypeScript: Full type definitions included

Go Worker Features

✅ OTLP Ingestion: Native support for OpenTelemetry protocol
✅ High Concurrency: Built with Go for scalable event processing
✅ Cardinality Governance: Automatic high-cardinality dimension management
✅ Dual Destinations: Self-hosted or Grafana Cloud
✅ Health Monitoring: Integrated health and stats endpoints

Observability Stack

✅ Full OTLP Pipeline: Alloy -> Mimir/Loki/Tempo
✅ Distributed Tracing: End-to-end visibility with Tempo
✅ 4 Production Dashboards: VOD, Live, Quality, Impact Explorer
✅ 18 Alert Rules: Critical quality and performance alerts
✅ Self-Hosted: Complete Docker Compose stack (Mimir, Loki, Tempo, Alloy, Grafana)

🏗️ Architecture

graph TD
    subgraph "Your Application"
        SDK[OpenQoE SDK]
        P1["Dash.js,HLS.js, HTML5 - Ready"]
        P2["Others - WIP"]
        P1 -.-> SDK
        P2 -.-> SDK
    end

    SDK -- "HTTPS POST /v2/events" --> Worker[Go Worker]

    subgraph "Observability Pipeline"
        Worker -- "OTLP" --> Alloy[Grafana Alloy]
        Alloy -- "Metrics" --> Mimir[Grafana Mimir]
        Alloy -- "Logs" --> Loki[Grafana Loki]
        Alloy -- "Traces" --> Tempo[Grafana Tempo]
    end

    subgraph "Visualization"
        Mimir --- Grafana[Grafana]
        Loki --- Grafana
        Tempo --- Grafana
    end

Flow:

SDK captures events from video players (Dash.js production ready)
Events batched and sent to Go Worker (/v2/events)
Worker validates and forwards via OTLP to Grafana Alloy
Alloy routes data to Mimir (metrics), Loki (logs), and Tempo (traces)
Grafana visualizes with pre-built dashboards and unified observability

1. Clone Repository

git clone https://github.com/openqoe/openqoe-dev.git
cd openqoe-dev

2. Start Observability Stack

# Start Mimir, Loki, Tempo, Alloy, and Grafana
docker compose up -d

# Verify all services are healthy
docker compose ps

3. Start Go Worker

cd worker

# Install dependencies & build
go mod download
go build -o openqoe-worker

# Configure environment (OTEL_URL=http://localhost:4317)
cp .env.example .env

# Run the worker
./openqoe-worker
# Worker available at http://localhost:8788

4. Integrate SDK (Dash.js Example)

<script type="module">
  import { OpenQoE } from "./sdk/dist/index.js";

  const qoe = new OpenQoE({
    orgId: "my-org",
    playerId: "my-website",
    endpointUrl: "http://localhost:8788/v2/events",
  });

  const player = dashjs.MediaPlayer().create();
  player.initialize(videoElement, url, true);

  qoe.attachPlayer("dashjs", player, {
    videoId: "video-123",
    videoTitle: "Production Stream",
  });
</script>

5. View Dashboards & Traces

Open Grafana: localhost:3000 (admin/admin)
Navigate to Dashboards → OpenQoE folder
Explore VOD Monitoring or Impact Explorer
Use the Explore tab to view distributed traces in Tempo

OpenQoE v2 is ready! 🚀

📚 Documentation

Getting Started

Document	Description
Deployment Guide	Go Worker and Alloy Setup and deployment
API Reference	V2 Event Schemas and OTLP details
SDK Integration	Dash.js, HLS.js, HTML5 focus (other players WIP)
Architecture	Distributed observability pipeline
Production Ready	Production readiness report (Dash.js, HLS.js, HTML5)

Open VOD Monitoring dashboard
Play a video and watch metrics appear in real-time!

That's it! Your video QoE monitoring is now live. 🎉

Architecture & Design

Document	Description
Architecture Overview	System architecture and component design
Technical Specification	Detailed technical specifications
Data Model	Event schemas and data structures
Production Ready Status	Complete production readiness report

Observability

Document	Description
Observability README	Stack overview, metrics, queries, troubleshooting
Dashboard Documentation	Dashboard specifications and panel details
Recording Rules	25 pre-aggregated metrics
Alert Rules	18 production alerts

Component READMEs

Component	README
SDK	sdk/README.md
Worker	worker/README.md
Examples	examples/README.md

🌍 Deployment Options

Option 1: Self-Hosted (Docker)

Best for: On-premise deployments, full control, data sovereignty

# Start complete stack
docker compose up -d

# Configure worker for localhost
cd worker && npm run dev

Includes: Mimir (metrics), Loki (logs), Grafana (dashboards)

Docs: Self-Hosted Deployment

Option 2: Grafana Cloud

Best for: Managed service, zero infrastructure, global scale

# Configure worker in .env
DESTINATION_TYPE=GrafanaCloud
GRAFANA_CLOUD_INSTANCE_ID=123456
GRAFANA_CLOUD_API_KEY=your-api-key

# Run worker
./openqoe-worker

Docs: Grafana Cloud Deployment

Option 3: Hybrid (Self-Hosted + Managed Worker)

Best for: Distributed ingestion with on-premise storage

Combine regional Go workers for global ingestion with a central self-hosted observability stack.

Docs: Hybrid Deployment

📊 Metrics & Dashboards

Dashboard Overview

Dashboard	Panels	Purpose	Key Metrics
VOD Monitoring	21	Real-time VOD quality	VST, rebuffering, completion, quartiles
Live Streaming	11	Live event monitoring	Concurrent viewers, join time, geographic
Quality & Delivery	12	Technical deep-dive	Seek latency, dropped frames, ABR
Impact Explorer	14	Business analysis	Watch time, engagement, revenue

Key Metrics Captured

Business Metrics:

Total views, completion rate, watch time
Revenue impact calculations
Engagement by quartile (25/50/75/100%)
Content performance comparison

Technical Metrics:

Video Startup Time (P50/P95/P99 via histograms)
Rebuffer rate, duration, and frequency
Seek latency and performance
Error rates by type and family
Bitrate distribution and ABR behavior
Dropped frames and rendering quality
Resolution distribution (360p-8K)
Buffer health

Live Streaming:

Concurrent viewers (real-time)
Join time (P95)
Geographic distribution
Viewer drop detection

Histogram Metrics

OpenQoE uses true histograms (not gauges) for accurate percentile calculations:

# Accurate P95 Video Startup Time
histogram_quantile(0.95,
  sum(rate(openqoe_video_startup_seconds_bucket[5m])) by (le)
)

# Using pre-aggregated recording rule (10-50x faster)
openqoe:video_startup_seconds:p95

Histogram buckets configured:

VST: [0.5, 1, 2, 3, 5, 10, 15, 30] seconds
Rebuffer Duration: [0.5, 1, 2, 3, 5, 10, 30] seconds
Seek Latency: [0.1, 0.25, 0.5, 1, 2, 5] seconds

🎨 Supported Players

Player	Adapter	Status
Dash.js	`DashJsAdapter`	✅ Production Ready
HTML5	`HTML5Adapter`	🏗️ Work In Progress
Video.js	`VideoJsAdapter`	🏗️ Work In Progress
HLS.js	`HlsJsAdapter`	🏗️ Work In Progress
Shaka Player	`ShakaAdapter`	🏗️ Work In Progress

*HTML5 doesn't support quality_change events (no native ABR)

Events Tracked (24+ Total)

Event	Description	Business Value
`playerready`	Player initialized	Time to interactive
`viewstart`	Video load started	View funnel entry
`playing`	Playback started	Video Startup Time (VST)
`pause`	User paused	Engagement analysis
`seek`	User scrubbed	Navigation behavior
`stall_start`	Buffering started	Rebuffering detection
`stall_end`	Buffering ended	Rebuffer duration
`ended`	Video completed	Completion rate
`error`	Playback error	Error tracking
`quartile`	25/50/75/100% reached	Drop-off analysis
`heartbeat`	Periodic update (10s)	Watch time tracking
`quality_change`	ABR switch	Bitrate adaptation

🛠️ Development

Project Structure

openqoe/
├── build
│   ├── build.ninja
│   ├── CMakeCache.txt
│   ├── CMakeFiles
│   │   ├── 3.28.3
│   │   │   ├── CMakeCXXCompiler.cmake
│   │   │   ├── CMakeDetermineCompilerABI_CXX.bin
│   │   │   ├── CMakeSystem.cmake
│   │   │   └── CompilerIdCXX
│   │   │       ├── a.out
│   │   │       ├── CMakeCXXCompilerId.cpp
│   │   │       └── tmp
│   │   ├── cmake.check_cache
│   │   ├── CMakeConfigureLog.yaml
│   │   ├── OpenQoEWorker.dir
│   │   │   └── src
│   │   ├── pkgRedirects
│   │   ├── rules.ninja
│   │   └── TargetDirectories.txt
│   ├── cmake_install.cmake
│   ├── compile_commands.json
│   └── OpenQoEWorker
├── compose.yaml
├── docs
│   ├── api-reference.md
│   ├── architecture.md
│   ├── contributing.md
│   ├── data-model.md
│   ├── deployment-checklist.md
│   ├── deployment-guide.md
│   ├── observability
│   │   ├── dashboards.md
│   │   └── README.md
│   ├── production-ready.md
│   ├── sdk-integration.md
│   └── technical-spec.md
├── examples
│   ├── dashjs-demo
│   │   └── index.html
│   ├── DEMO_TEMPLATE.md
│   ├── hlsjs-demo
│   │   └── index.html
│   ├── html5-demo
│   │   └── index.html
│   ├── README.md
│   ├── shaka-demo
│   │   └── index.html
│   └── videojs-demo
│       └── index.html
├── LICENSE
├── observability
│   ├── alloy
│   │   └── config.alloy
│   ├── dashboards
│   │   ├── impact-explorer.json
│   │   ├── live-streaming.json
│   │   ├── quality-delivery.json
│   │   └── vod-monitoring.json
│   ├── grafana
│   │   └── provisioning
│   │       ├── dashboards
│   │       │   └── dashboards.yml
│   │       └── datasources
│   │           └── datasources.yml
│   ├── GRAFANA_DASHBOARDS.md
│   ├── loki
│   │   └── loki-config.yaml
│   ├── mimir
│   │   ├── mimir-config.yml
│   │   └── runtime.yml
│   ├── prometheus
│   │   ├── prometheus.yml
│   │   └── rules
│   │       ├── load-rules.sh
│   │       ├── openqoe-alert-rules.yml
│   │       └── openqoe-recording-rules.yml
│   ├── README.md
│   └── tempo
│       └── tempo-config.yaml
├── openqoe-dev.code-workspace
├── README.md
├── sdk
│   ├── jest.config.js
│   ├── package.json
│   ├── package-lock.json
│   ├── README.md
│   ├── rollup.config.js
│   ├── src
│   │   ├── adapters
│   │   │   ├── DashJsAdapter.ts
│   │   │   ├── HlsJsAdapter.ts
│   │   │   ├── HTML5Adapter.ts
│   │   │   ├── ShakaAdapter.ts
│   │   │   └── VideoJsAdapter.ts
│   │   ├── core
│   │   │   ├── BatchManager.ts
│   │   │   ├── EventCollector.ts
│   │   │   ├── QueueManager.ts
│   │   │   ├── RetryManager.ts
│   │   │   ├── SessionManager.ts
│   │   │   └── Transport.ts
│   │   ├── index.ts
│   │   ├── OpenQoE.ts
│   │   ├── types.ts
│   │   └── utils
│   │       ├── device.ts
│   │       ├── logger.ts
│   │       └── privacy.ts
│   ├── tests
│   │   ├── core
│   │   │   ├── BatchManager.test.ts
│   │   │   └── SessionManager.test.ts
│   │   └── utils
│   │       └── privacy.test.ts
│   └── tsconfig.json
├── sonar-project.properties
├── test
│   ├── dashjs-test
│   │   └── index.html
│   ├── hlsjs-test
│   │   └── index.html
│   ├── html5-test
│   │   └── index.html
│   ├── shaka-test
│   │   └── index.html
│   └── videojs-test
│       └── index.html
└── worker
    ├── compute
    │   ├── events.go
    │   ├── helpers.go
    │   ├── metrics.go
    │   ├── system_metrics.go
    │   └── types.go
    ├── config
    │   ├── auth.go
    │   ├── cardinality.go
    │   ├── config.go
    │   ├── destination.go
    │   ├── env.go
    │   └── redis.go
    ├── data_structure
    │   ├── pair.go
    │   └── set.go
    ├── Dockerfile
    ├── go.mod
    ├── go.sum
    ├── main.go
    ├── middlewares
    │   ├── auth.go
    │   └── headers.go
    ├── otelservice
    │   ├── setup.go
    │   ├── tracer.go
    │   └── types.go
    ├── pool
    │   └── worker.go
    ├── README.md
    └── requesthandlers
        ├── controller.go
        ├── markdevice.go
        ├── requestvalidation.go
        └── types.go

Build SDK

cd sdk
npm install
npm run build
npm test

Run Worker Locally

cd worker
go build .
./worker
# Available at http://localhost:8788

Run Examples

# while in root level
npm install -g http-server
http-server
# Open http://localhost:8080

🤝 Contributing

We welcome contributions! Whether it's:

🐛 Bug reports
✨ Feature requests
📝 Documentation improvements
🔧 Code contributions

Please read our Contributing Guide for guidelines.

Quick Contribution Steps

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Commit with clear messages (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright 2026-27 OpenQoE Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

💬 Support

Community Support

🌐 Website: https://openqoe.dev
📖 Documentation: Start with docs/deployment-guide.md
🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions
💬 Questions: GitHub Discussions Q&A

Getting Help

🌟 Acknowledgments

OpenQoE is built with:

TypeScript - Type safe development
Go - Low Latency highly concurrent native application with strict type safety
Grafana Alloy - Open Telemetry collector for Observability Signals
Grafana Mimir - Prometheus-compatible metrics storage
Grafana Loki - Log aggregation
Grafana Tempo - Trace Correleation
Grafana - Visualization platform
Docker - Containerization

Inspired by commercial QoE monitoring solutions for continuous improvement and industry best practices.

📈 Project Status

Current Version: 2.0.0 Status: ✅ Dash.js, HLS.js, HTML5 Ready / 🏗️ Core v2 In Beta Last Updated: January 2026

See docs/production-ready.md for complete production readiness report.

What's Production Ready

✅ SDK for all 5 major web players
✅ Low Latency
✅ 4 comprehensive Grafana dashboards (58 panels)
✅ 25 recording rules for performance
✅ 18 production-ready alerts
✅ Self-hosted Docker stack
✅ Grafana Cloud support
✅ Complete documentation

Roadmap

Phase 2 (Optional):

Worker Health Dashboard (pipeline monitoring)
Advanced cardinality analytics
Custom metric extensions
Load testing framework

🙏 Star Us!

If you find OpenQoE useful, please consider giving us a star ⭐ on GitHub. It helps others discover the project!

Made with ❤️ by the OpenQoE Community

Name		Name	Last commit message	Last commit date
Latest commit History 190 Commits
.github/workflows		.github/workflows
docs		docs
examples		examples
observability		observability
sdk		sdk
test		test
worker		worker
.coderabbit.yaml		.coderabbit.yaml
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
compose.yaml		compose.yaml
contributing.md		contributing.md
openqoe-dev.code-workspace		openqoe-dev.code-workspace
sonar-project.properties		sonar-project.properties

License

openqoe/openqoe-dev

Folders and files

Latest commit

History

Repository files navigation