Documentation / Install

Install

Setup takes about ten minutes: install the app, map two resources, create the tables, grant the app access, and upload your first dump.

Marketplace listing coming soon. Until the public listing is live, email info@flying-village.com for early access — the steps below are the same.

Prerequisites

Unity Catalog enabled in your workspace
A serverless SQL warehouse you can grant the app access to
Databricks Apps enabled
Optional, for AI diagnosis: a pay-per-token Foundation Model API endpoint (e.g. a Claude, Llama, or GPT-OSS endpoint)
Permission to create a schema (or an admin who can) and to run GRANT

Step 1 — Install the app and map resources

Install WebRTC Quality Analytics from the Marketplace listing. During app setup you are asked to map the resources the app declares:

Resource	Select	Permission	Resource key
SQL warehouse	Your serverless SQL warehouse	Can use	`sql-warehouse`
Serving endpoint	A pay-per-token Foundation Model endpoint	Can query	`llm-endpoint`

The warehouse and endpoint permissions are granted to the app's service principal automatically through this mapping.

Step 2 — Choose the catalog and schema

The app reads its catalog/schema from two environment variables (visible in the app's configuration):

Environment variable	Default	Meaning
`WEBRTC_QOE_CATALOG`	`workspace`	Unity Catalog catalog holding the app's tables
`WEBRTC_QOE_SCHEMA`	`webrtc_qoe_dev`	Schema holding the app's tables

Keep the defaults or point them at a catalog/schema of your choice, then create the schema if it does not exist:

CREATE SCHEMA IF NOT EXISTS <catalog>.<schema>;

Step 3 — Create the tables

Run the bundled DDL (three files, in order) in the SQL editor. The statements use unqualified table names, so select your catalog/schema first:

USE CATALOG <catalog>;
USE SCHEMA <schema>;
-- then run, in order:
--   sql/ddl/001_bronze.sql   (upload ledger)
--   sql/ddl/002_silver.sql   (normalized W3C getStats tables)
--   sql/ddl/003_gold.sql     (QoE aggregates)

All statements are CREATE TABLE IF NOT EXISTS — re-running is safe. This creates 12 Delta tables (1 bronze, 6 silver, 5 gold).

Step 4 — Grant the app's service principal access

Find the app's service principal client ID on the app's page (or via databricks apps get <app-name> → service_principal_client_id), then:

GRANT USE CATALOG ON CATALOG <catalog> TO `<sp_client_id>`;
GRANT USE SCHEMA, SELECT, MODIFY ON SCHEMA <catalog>.<schema> TO `<sp_client_id>`;

Step 5 — Start the app and upload a dump

Start the app and open its URL.
Capture a dump during a call — see Capture a dump.
Drop the JSON file on the app's Upload dump page (Data section in the sidebar).

The upload runs the full pipeline (bronze → silver → gold) and the call appears in every view within seconds. Re-uploading the same file is detected by content hash and skipped.

Step 6 (optional) — AI/BI dashboard template

A Lakeview dashboard template (dashboards/webrtc_qoe_fleet.lvdash.json) is bundled for monitoring outside the app. Replace workspace.webrtc_qoe_dev in the file with your <catalog>.<schema>, import it in your workspace (Create → Import on a workspace folder), and assign your SQL warehouse.

Troubleshooting

Symptom	Fix
App shows `TABLE_OR_VIEW_NOT_FOUND`	Step 3 not run, or `WEBRTC_QOE_CATALOG` / `WEBRTC_QOE_SCHEMA` point elsewhere
`PERMISSION_DENIED` on queries	Step 4 grants missing for the app's service principal
Upload succeeds but views stay empty	Check the bronze ledger: `SELECT * FROM <catalog>.<schema>.bronze_uploads ORDER BY uploaded_at DESC` — `parse_status='failed'` rows include the parse error
AI diagnosis fails	The mapped serving endpoint must be a chat-capable pay-per-token endpoint with a non-zero rate limit; the app's service principal needs Can query (granted by the `llm-endpoint` mapping)
Slow first load of a view	Serverless warehouse cold start — subsequent queries are fast (the app caches and parallelizes its queries)

Data & privacy notes

The app makes no outbound network calls; all processing stays in your workspace.
TURN credentials are redacted and SDP bodies dropped at parse time.
Uploaded raw dumps are not retained as files; only the parsed rows and a SHA-256 content hash (for dedup) are stored in your tables.

Next: Capture a dump →