Table: epas_<shardId>

The worker writes player events to one table per shard in the default database. The table name is epas_ followed by the shardId of the event, or its host if no shardId is set. If the SDK sets neither, events go to epas_default. Run SHOW TABLES FROM default to see the tables in your pipeline, and replace epas_default in the examples below with your table name.

CREATE TABLE default.epas_default (
  event        String,        -- EPAS event name, e.g. 'playing', 'buffering'
  sessionId    String,        -- Unique session ID per viewer
  timestamp    DateTime64(3), -- Event timestamp (UTC)
  playhead     Float64,       -- Playback position in seconds
  duration     Float64,       -- Content duration in seconds
  live         Boolean,       -- From the event payload
  contentId    String,        -- From the event payload
  userId       String,        -- From the event payload
  deviceId     String,        -- From the event payload
  deviceModel  String,        -- From the event payload
  deviceType   String,        -- From the event payload
  payload      String,        -- Full event payload as a JSON string
  event_date   Date DEFAULT toDate(timestamp),
  event_hour   DateTime DEFAULT toStartOfHour(timestamp)
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(timestamp)
ORDER BY (sessionId, timestamp);

live, contentId, userId, deviceId, deviceModel and deviceType are copied from the payload of each individual event when the row is inserted. They are only set on events that carry those keys, which in practice is the metadata event, and only if your player reports them with reportMetadata(). The example queries therefore read these columns from the session's metadata event. Other values, such as bitrate and the error code, are not columns and are read from payload with JSONExtract* functions.

Event names follow the EPAS specification: init, metadata, heartbeat, loading, loaded, playing, paused, buffering, buffered, seeking, seeked, bitrate_changed, stopped, error and warning.

Average Startup Time by Device Type

Startup time is the time between the loading and loaded events of a session. Device type comes from the metadata event, so sessions without reported metadata are grouped under an empty device type. Target: under 2 seconds.

SELECT
  device,
  round(avg(startup_ms))                 AS avg_startup_ms,
  round(avg(startup_ms) / 1000, 2)       AS avg_startup_s,
  count()                                AS sessions
FROM (
  SELECT
    sessionId,
    anyIf(deviceType, event = 'metadata' AND deviceType != '') AS device,
    dateDiff('millisecond',
      minIf(timestamp, event = 'loading'),
      minIf(timestamp, event = 'loaded')) AS startup_ms
  FROM default.epas_default
  WHERE timestamp > now() - INTERVAL 7 DAY
  GROUP BY sessionId
  HAVING countIf(event = 'loading') > 0 AND countIf(event = 'loaded') > 0
)
GROUP BY device
ORDER BY avg_startup_ms DESC;

Buffering Events per Session

Count buffering events per day relative to the number of sessions. The pipeline does not store buffering duration or CDN, so this shows how often buffering occurs, not how long it lasts.

SELECT
  toDate(timestamp)                          AS day,
  countIf(event = 'buffering')               AS buffering_events,
  uniqExact(sessionId)                       AS sessions,
  round(buffering_events / sessions, 2)      AS buffering_per_session
FROM default.epas_default
WHERE timestamp > now() - INTERVAL 7 DAY
GROUP BY day
ORDER BY day DESC;

Error Rate by Content

Find which content items trigger the most playback errors. Content ID comes from the metadata event and the error code from the error event payload.

SELECT
  content,
  sum(errors)                      AS total_errors,
  countIf(errors > 0)              AS affected_sessions,
  topKArray(5)(error_codes)        AS top_error_codes
FROM (
  SELECT
    sessionId,
    anyIf(contentId, event = 'metadata' AND contentId != '') AS content,
    countIf(event = 'error')                                 AS errors,
    groupArrayIf(JSONExtractString(payload, 'code'), event = 'error') AS error_codes
  FROM default.epas_default
  WHERE timestamp > now() - INTERVAL 7 DAY
  GROUP BY sessionId
)
GROUP BY content
HAVING total_errors > 0
ORDER BY total_errors DESC
LIMIT 20;

Concurrent Viewers (Last Hour)

Approximate concurrent viewer count over the past hour in 5-minute buckets.

SELECT
  toStartOfFiveMinutes(timestamp) AS bucket,
  uniqExact(sessionId)            AS concurrent_viewers
FROM default.epas_default
WHERE event IN ('heartbeat', 'playing')
  AND timestamp > now() - INTERVAL 1 HOUR
GROUP BY bucket
ORDER BY bucket ASC;

Bitrate Distribution

Understand what quality levels your viewers are experiencing. Bitrate is only recorded if your player reports bitrate_changed events. The payload value is in Kbps, so dividing by 1000 gives Mbps.

SELECT
  round(JSONExtractFloat(payload, 'bitrate') / 1000, 1) AS bitrate_mbps,
  count()                                               AS event_count,
  uniqExact(sessionId)                                  AS sessions
FROM default.epas_default
WHERE event = 'bitrate_changed'
  AND JSONExtractFloat(payload, 'bitrate') > 0
  AND timestamp > now() - INTERVAL 7 DAY
GROUP BY bitrate_mbps
ORDER BY bitrate_mbps ASC;

Export to CSV (HTTP API)

Use the ClickHouse HTTP interface to download query results directly as CSV:

curl "https://{host}/?database=default&user={username}&password={password}" \
  --data "SELECT * FROM epas_default WHERE timestamp > NOW() - INTERVAL 1 DAY FORMAT CSV" \
  -o events.csv

Connect BI Tools

ClickHouse supports JDBC and ODBC drivers for connecting BI tools:

Connect AI Assistants to Your Analytics Database

Open Analytics is built on ClickHouse, the open-source analytics database, chosen for real-time analytics at any scale.

Open Analytics includes ClickHouse MCP (Model Context Protocol) support - AI assistants like Claude, Cursor, and GitHub Copilot can query your analytics database directly using natural language.

Your player analytics are already queryable by AI agents - no data warehouse to connect. Claude, Cursor, or GitHub Copilot can query session data, rebuffering events, and startup times directly via the pre-configured ClickHouse MCP.

What You Can Do

Setup: Local MCP Client (Claude Desktop / Cursor)

Add this to your Claude Desktop or Cursor MCP configuration. Replace the placeholders with your pipeline's connection credentials from the section above.

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST":     "{host}",
        "CLICKHOUSE_PORT":     "443",
        "CLICKHOUSE_USER":     "{username}",
        "CLICKHOUSE_PASSWORD": "{password}",
        "CLICKHOUSE_DATABASE": "default",
        "CLICKHOUSE_SECURE":   "true"
      }
    }
  }
}

mcp-clickhouse runs read-only by default (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), but the SQL Access user has write grants, so do not enable write access in the MCP config.

When you build a Grafana-managed alert rule against your Open Analytics metrics, note that its DatasourceNoData and DatasourceError cases evaluate as independent alert instances with their own labels. Silences, mute timings, and notification policies applied to the primary rule may not apply to them. To be notified when the pipeline goes quiet (not just when a threshold breaches) configure routing for the No-Data / Error instances explicitly.

See Grafana’s create Grafana-managed alert rule and alert rule state and health docs.

Installation

npm install @eyevinn/player-analytics-client-sdk-web

Quick Start

The PlayerAnalyticsConnector automatically captures events from your HTML5 video element:

import { PlayerAnalyticsConnector } from "@eyevinn/player-analytics-client-sdk-web";

const analytics = new PlayerAnalyticsConnector("YOUR_EVENTSINK_URL");

await analytics.init({
  sessionId: crypto.randomUUID(),
  heartbeatInterval: 30000
});

analytics.reportMetadata({
  contentId: "YOUR_CONTENT_ID",
  contentTitle: "YOUR_CONTENT_TITLE",
  deviceType: /Mobi/i.test(navigator.userAgent) ? "mobile" : "desktop",
  timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
});

const videoElement = document.querySelector("video");
analytics.load(videoElement);

// When playback ends
analytics.reportStop();
analytics.destroy();

Device and content breakdowns need this call; the timeZone key fills the Country breakdown from the device time zone, since hosted pipelines get no client IP.

Features

Installation

Add JitPack repository and dependency:

// settings.gradle
maven { url 'https://jitpack.io' }

// build.gradle
implementation("com.github.Eyevinn:player-analytics-client-sdk-android:v1.1.2")

JitPack versions are the git tags (with the v prefix). For the latest, see the releases page.

Quick Start with ExoPlayer

val tracker = VideoAnalyticsTracker.Builder(context, exoPlayer)
    .setEventSinkUrl("YOUR_EVENTSINK_URL")
    .setContentTitle("Video Title")
    .setDeviceType("Android")
    .setHeartbeatInterval(30_000L)
    .build()

tracker.startTracking()
exoPlayer.play()

// In onDestroy()
tracker.stopTracking("user_exit")
tracker.release()

Device and content breakdowns need this call; country needs geo, which hosted pipelines do not collect yet.

Features

Installation (Swift Package Manager)

File → Swift Packages → Add Package Dependency...

https://github.com/Eyevinn/player-analytics-client-sdk-swift

Quick Start with AVPlayer

import VideoStreamTracker

class VideoPlayerViewController: UIViewController {
    var player: AVPlayer!
    var logger: AVPlayerEventLogger!

    override func viewDidLoad() {
        super.viewDidLoad()
        player = AVPlayer(url: videoURL)
        logger = AVPlayerEventLogger(
            player: player,
            eventSinkUrl: URL(string: "YOUR_EVENTSINK_URL")!
        )
    }
}

Features