The OpenTelemetry model

EXOS uses the OpenTelemetry (OTel) data model end-to-end. Three nested concepts map directly onto ClickHouse columns:

Properties — segmenting by ServiceName

Every span carries a ServiceName. EXOS groups services into properties — the distinct products and sites that report telemetry to the same store. Scope any view to a single property by passing ?workspace=<ServiceName>; /api/workspaces lists the properties currently reporting data.

The default product-analytics views scope to EXOS + Portal — ServiceName LIKE 'exos-%' OR ServiceName = 'clickstack-portal' (defined once in functions/api/_shared.js as SERVICE_FILTER). Other properties are queryable explicitly via the workspace parameter.

Core tables

Telemetry lands in the default database (raw OTel, collector-owned); EXOS process-mining derivations live in the exos database. Row counts are from a live read of the backing ClickHouse instance on 2026-06-23.

default — OpenTelemetry + session replay

exos — process mining + platform reference

Only default and exos are reachable from any portal surface. See Access & Auth for how isolation is enforced.

Data Flow

graph TD
    A[Browser SDK HyperDX] -->|DOM snapshots
rrweb format, video replay| B[hyperdx_sessions
~415K events]
    A -->|User events
clicks, HTTP, page loads, domain events| C[otel_traces
~792K spans]
    A -->|Console output
log, warn, error, debug| D[otel_logs
~21K logs]

    classDef default fill:#1e1e2e,stroke:#333,color:#d4d4d4;
    classDef edgeLabel fill:#1e1e2e,color:#d4d4d4,stroke:none;
          

All joined by: ResourceAttributes['rum.sessionId']

otel_traces

Every user interaction, HTTP request, page load, performance event, and domain event. This is the primary analytics table.

Key columns

SpanName taxonomy

Example query

SELECT SpanName, count() as cnt FROM otel_traces WHERE Timestamp >= now() - INTERVAL 7 DAY GROUP BY SpanName ORDER BY cnt DESC LIMIT 20

Used by: Operator Patterns, Order Lifecycle, Product Analytics, Session Replay drill-down tabs

hyperdx_sessions

Full DOM recording data captured by rrweb. Each row contains a batch of rrweb events for a session, enabling pixel-perfect video replay.

Key columns

Example query

SELECT session_id, count() as batches, min(timestamp) as started FROM hyperdx_sessions WHERE timestamp >= now() - INTERVAL 7 DAY GROUP BY session_id ORDER BY started DESC LIMIT 10

Used by: Session Replay player, activity heatbar

otel_logs

Console output captured from the browser. Every console.log(), console.warn(), console.error(), and console.debug() call is recorded.

Key columns

Example query

SELECT SeverityText, count() as cnt FROM otel_logs WHERE Timestamp >= now() - INTERVAL 7 DAY GROUP BY SeverityText ORDER BY cnt DESC

Used by: Session Replay Console tab, Site Health error groups

Visitor Enrichment

On every page load, the portal calls /api/visitor to resolve the user's IP into geo, device, and network attributes via HyperDX.setGlobalAttributes().

How rrweb Records

The HyperDX SDK uses rrweb (v2.0.0-alpha.4) to capture the DOM. Three event types matter:

How the Replayer Works

The rrweb Replayer reconstructs the page inside a sandboxed <iframe>. It deserializes the full snapshot (type 2) to build the initial DOM, then applies incremental events (type 3) in timestamp order. Compiled Tailwind CSS is injected so the replay retains original styling.

Seek-to-Time Mapping

When you click a row in any drill-down tab, the player jumps to that moment:

offset_ms = otel_traces.Timestamp - rrweb_first_event.timestamp

The absolute timestamp from otel_traces is converted to a millisecond offset from the first rrweb event. Implemented in seekToAbsTime().

Activity Heatbar

48px SVG waveform below the replay video showing activity density.

Drill-Down Tabs

Five tabs, each querying a different slice. Every row has a clickable timestamp that seeks the replay.

Natural Language Examples

Operator Patterns

The Operator Patterns page ranks operators by activity volume, task distribution, and automation opportunity.

Order Lifecycle

Three analysis modes:

ClickHouse Primitives

Seven functions power the analysis. The /api/insights endpoint self-documents every primitive.

HyperDX Browser SDK

Every page includes the HyperDX SDK for DOM replay, console, network, and interaction traces.

<script src="https://www.unpkg.com/@hyperdx/browser@0.22.0/build/index.js"></script>
<script>
  window.HyperDX && window.HyperDX.init({
    apiKey: 'H06oX4xamF3QHsFN0hJn', service: 'clickstack-portal',
    url: 'https://collector.exos-demo.com',
    consoleCapture: true, advancedNetworkCapture: true,
    disableReplay: false, maskAllText: false, maskAllInputs: true,
  });
</script>

Visitor Enrichment

On page load, fetches visitor metadata and attaches to all spans:

fetch('/api/visitor').then(r => r.json()).then(v => {
  window.HyperDX && window.HyperDX.setGlobalAttributes({
    'visitor.country': v.geo?.country || '',
    'visitor.city':    v.geo?.city || '',
    'visitor.org':     v.network?.asOrganization || '',
    'visitor.browser': v.device?.browser || '',
    // ... (15 attributes total, see Data Architecture)
  });
});

Firebase Auth Identity Flow

Auth module attaches identity to all subsequent telemetry:

// auth.js onAuthStateChanged:
if (window.HyperDX) {
  window.HyperDX.setGlobalAttributes({
    'user.email': userData.email,
    'user.name':  userData.displayName,
    'user.uid':   userData.uid,
  });
}

Custom Domain Events

Logged via HyperDX.addAction(), appearing as spans in otel_traces:

HyperDX.addAction('rage_click', { element: 'button#submit', count: 6 });
HyperDX.addAction('email.sent', { order_id: '12345', template: 'scheduling_confirmation' });

Why OCPM?

Case-centric mining sees one order at a time. OCPM reveals cross-object patterns:

Object Categories

Eight object categories derived from SpanName prefixes -- no schema changes needed:

ClickHouse Primitives for OCPM

Five SQL queries power the OCPM dashboard, using eight ClickHouse primitives:

Example: Object Interaction Query

SELECT c1 AS category_a, c2 AS category_b,
  count() AS co_occurrence_count
FROM (
  SELECT oid,
    arrayJoin(categories) AS c1,
    arrayJoin(categories) AS c2
  FROM (
    SELECT SpanAttributes['order.id'] AS oid,
      arrayDistinct(groupArray(
        CASE WHEN SpanName LIKE 'email.%' THEN 'Communication'
             WHEN SpanName LIKE 'page.%' THEN 'Portal'
             WHEN SpanName LIKE 'action.%' THEN 'System Action'
        END
      )) AS categories
    FROM otel_traces
    WHERE SpanAttributes['order.id'] != ''
    GROUP BY oid
    HAVING length(categories) >= 2
  )
) WHERE c1 < c2
GROUP BY c1, c2
ORDER BY co_occurrence_count DESC

Uses arrayJoin() to create a cross-product of categories within each order, then counts co-occurrences.

Conventions

Product analytics & metrics

Sessions & replay

Process mining

AI & SQL

Both AI/SQL paths enforce an allowlist of { default, exos } and reject any reference to system or personal databases — see Access & Auth.

Sign-in (Firebase Auth)

Sign-in is handled by Firebase Authentication with two OAuth providers:

On a successful sign-in the user's identity (user.email, user.name, user.uid) is attached to subsequent telemetry via HyperDX.setGlobalAttributes(), and cached in localStorage (exos_auth_user) to avoid a login flash on navigation. Signing out clears the cache and restores the gate.

Demo access mode (?skipauth=true)

Appending ?skipauth=true to any URL (also skipAuth / skip_auth) bypasses the front-end sign-in overlay so reviewers and test automation can browse without a credential:

https://exos-demo.com/sessions?skipauth=true