telemetryanalyticssdk

Real-Time Telemetry in React Native: From Event Capture to ClickHouse Insights

UUnknown

2026-02-28

11 min read

Tactical guide to instrument React Native for high-cardinality telemetry, batching, SDK design, and ingesting to ClickHouse in 2026.

Hook: Stop losing product insight because your mobile telemetry is slow or lossy

If you build React Native apps, you already know the pain: long feedback loops, inconsistent event capture across platforms, and telemetry pipelines that collapse under high cardinality. Teams ship blind — or worse, they collect data that’s expensive to store and nearly impossible to query. This tactical guide shows how to instrument React Native for high-cardinality event capture, design a resilient SDK, batch and compress smartly, and ingest efficiently to ClickHouse for interactive analytics in 2026.

Why ClickHouse (and why now)

ClickHouse is no longer a niche OLAP toy — as of late 2025 and into 2026, it’s a mainstream analytics backend used for telemetry, observability and product analytics. Big funding rounds and rapid feature development (improved Map/JSON support, better Kafka connectors, and native ingestion optimizations) mean ClickHouse is optimized for high-throughput, low-latency analytics. For mobile telemetry — where high-cardinality (device ids, screen names, user properties) collides with high volume — ClickHouse is a strong fit if you architect ingestion correctly.

Overview: From event capture to ClickHouse

Instrument events in the app with a minimal, non-blocking SDK.
Queue and persist events locally to survive crashes and network drops.
Batch intelligently using size/time constraints and adaptive strategies.
Compress and encode efficiently for mobile networks.
Retry with exponential backoff, jitter and circuit-breaker behavior.
Ingest into ClickHouse using an appropriate path: HTTP Native, Kafka bridge, or buffered proxy.
Model your ClickHouse schema and materialized views for fast queries.

Designing the React Native telemetry SDK

Your SDK is the most important part of the pipeline. Get it wrong and you'll either flood the backend or lose events.

Core principles

Non-blocking: Never block the JS main thread. Use background workers, native modules or off-main threads for heavy work.
Durable: Persist events to disk so crashes and offline periods don’t lose data.
Minimal payload: Keep event payloads small; trim unnecessary context and use a schema.
Privacy-first: Hash PII, provide opt-out toggles, and support consent APIs to comply with GDPR/CPRA rules tightened by 2025–2026 enforcement.

Recommended public API (TypeScript)

export type Event = {
  eventName: string;
  timestamp?: number;
  userId?: string | null;
  deviceId?: string;
  properties?: Record;
  tags?: Record; // small map of low-cardinality tags
  sampleRate?: number; // optional sampling
}

export interface TelemetryClient {
  capture(event: Event): Promise;
  flush(): Promise;
  setUserId(id: string | null): void;
  setContext(context: Record): void;
}

Keep the API small: a capture() function plus lifecycle methods. Let app teams add higher-level wrappers for product semantics.

Architecture sketch

In-memory queue with a persistent backing store: use MMKV (fast native key-value), SQLite, or file-backed queue.
Background worker to build batches and perform network sends. On iOS, use BackgroundTasks or silent pushes; on Android use WorkManager / Headless JS.
Compression and encoding step that runs off-main-thread (native module preferred for CPU efficiency).
Transport layer with retry/backoff and circuit breaker; expose metrics (queue size, dropped count).

Event batching strategies

Batching is the lever that controls cost, latency, and reliability. The right strategy adapts to signal importance and network conditions.

Bolt-on rules (simple, safe defaults)

maxBatchCount: 250 events
maxBatchBytes: 256KB compressed
flushInterval: 10 seconds on Wi‑Fi, 30–60 seconds on cellular
priorityImmediate: critical events (payments, crashes) skip batching and send immediately
sampleRate: sample high-frequency events (e.g., touches) at 1–5%

Adaptive batching

Make batching adaptive to network type and app state. Use heuristics:

If on Wi‑Fi & battery > 30%: increase maxBatchBytes and send more frequently for low latency.
If on cellular or metered: increase flushInterval and lower maxBatchBytes.
When the app goes to background, force a flush but respect a short timeout to avoid blocking shutdown.

Backpressure and queue limits

Set a hard queue limit (e.g., 100k events or 50MB) and implement eviction priorities: oldest low-value events are dropped first. Emit SDK metrics on drops so teams can act.

Transport: compression, encoding and retries

Mobile networks are lossy and expensive. Compress, batch and retry intelligently.

Encoding formats

JSONEachRow: human-friendly and good for small scale; higher overhead.
MessagePack / CBOR: more compact, widely supported in JS (msgpack-lite), good middle ground.
Protobuf: best for size and CPU on high-scale setups (requires schema management).
Native ClickHouse formats (Native/TabSeparated/Binary): fastest ingestion to ClickHouse server; requires custom client/proxy.

For RN SDKs I recommend MessagePack + gzip (or brotli if available) for an excellent tradeoff between size and implementation complexity.

Compression tips

Use native compression modules where possible. pako works on JS but is CPU-heavy on the JS thread; prefer a small native module that compresses off the main thread.
Set Content-Encoding: gzip or br appropriately. On the server side, tell ClickHouse to accept compressed HTTP bodies.
Prefer ZSTD or LZ4 for server storage; ClickHouse will compress on disk with configured codecs (ZSTD is common in 2026).

Retry and backoff strategy

Use exponential backoff with full jitter. Keep a retry cap per batch and a global circuit breaker to avoid hammering the client network during outages.

// pseudo-code: exponential backoff with jitter
const base = 500; // ms
const cap = 60_000;
function backoff(attempt) {
  const raw = Math.min(cap, base * Math.pow(2, attempt));
  return Math.random() * raw; // full jitter
}

Retryable errors: network timeouts, 5xx, connection resets.
Non-retryable: 4xx that indicate bad payload (log & drop).
On repeated 5xx or high error rates, open a circuit for a cooldown window and persist queues to disk.

Ingesting into ClickHouse: practical options

There are three pragmatic ingestion topologies depending on scale and operational preferences.

1) Direct HTTP inserts (small-to-medium scale)

Apps POST batches directly to ClickHouse HTTP endpoint using format=JSONEachRow or Binary. This is simplest but has limitations on concurrency and connection overhead.

// Example: send JSONEachRow batch
fetch('https://clickhouse.example.com/?query=INSERT%20INTO%20telemetry%20FORMAT%20JSONEachRow', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Content-Encoding': 'gzip' },
  body: compressedPayload
});

Pros: simple. Cons: limited throughput, exposes ClickHouse to the internet unless you use a secure proxy.

2) Buffered proxy / gateway (recommended)

Run a lightweight collector (K8s, autoscaling service, or CDN edge function) that accepts mobile batches, validates, and forwards to ClickHouse or to Kafka. This decouples mobile clients from ClickHouse and lets you add auth, rate limits and per-tenant routing.

3) Kafka / streaming bridge (high volume)

Publish events to Kafka (or managed streaming like Redpanda) from the proxy and use ClickHouse's Kafka engine or Materialized Views to ingest. This is the most robust for peak scale and backpressure handling. In 2025–2026 ClickHouse Kafka integrations improved significantly, making this pattern more appealing.

ClickHouse schema & modeling for high-cardinality telemetry

Design tables for fast queries and reasonable storage cost.

Core DDL example

CREATE TABLE telemetry (
  ts DateTime64(3) DEFAULT now(),
  event_name String,
  user_id String,
  device_id String,
  props String, -- JSON string for ad-hoc properties
  tags Map(String, String),
  sdk_version String,
  sample_rate Float32
) ENGINE = MergeTree()
PARTITION BY toYYYYMMDD(ts)
ORDER BY (event_name, device_id, ts);

Notes:

Partition by date (toYYYYMMDD) to make TTL and drops efficient.
Use Map for small tag maps; ClickHouse's Map type performance improved significantly by 2025.
Store free-form properties as a JSON string; create materialized views to extract the most common properties as columns.
Use LowCardinality(String) only for truly low-cardinality columns (country, platform); avoid for user_id/device_id.

Materialized views for column extraction

Extract frequent properties to columns on insert for faster aggregation and lower CPU at query time:

CREATE MATERIALIZED VIEW telemetry_mv TO telemetry_flat AS
SELECT
  ts,
  event_name,
  user_id,
  device_id,
  JSONExtractString(props, 'screen') AS screen,
  JSONExtractFloat(props, 'duration') AS duration,
  sdk_version,
  sample_rate
FROM telemetry_raw;

Handling high-cardinality tags

High-cardinality values (e.g., full email addresses, long URLs) should not be used as grouping keys. Strategies:

Hash the value and store the hash in a column, keeping a separate lookup store when you need to reverse-lookup (and only for authorized internal queries).
Use probabilistic structures for distinct counts (HyperLogLog / uniqExact) for heavy cardinality metrics.
Store raw high-cardinality properties in object store+pointer if needed for audit, not as primary columns.

Operational tips: CI/CD, testing and migrations

Telemetery pipelines must be reproducible and testable before they hit prod.

Local dev and CI

Run ClickHouse locally with docker-compose during development and CI to validate schemas and ingestion queries.
Include schema checks and query performance smoke tests in CI. Use a synthetic load generator to validate end-to-end ingestion latency.
Use contract tests for your SDK's payload format.

Schema migrations

Use declarative DDL in your repo. Apply migrations under change control and keep old columns accessible until apps migrate (grace period).
When removing columns, prefer a staged approach: mark deprecated → stop producing → drop after retention window.

Observability of the telemetry pipeline itself

Your telemetry SDK must emit telemetry about itself. Track:

Queue length
Dropped event count and reasons
Average batch size and latency
Transport error rates and HTTP status distribution

Ship these internal metrics to ClickHouse or a dedicated monitoring system. Visualize the 95th/99th latency and dropped events to catch regressions quickly.

Example: Minimal RN SDK implementation (send + persistence sketch)

This example shows a simplified JS-side queue with MMKV and a background flush worker. In production, move compression/offloading to native modules.

import MMKVStorage from 'react-native-mmkv-storage';
import msgpack from 'msgpack-lite';
import pako from 'pako';

const storage = new MMKVStorage.Loader().initialize();
const QUEUE_KEY = 'telemetry_queue_v1';

async function enqueue(event) {
  const q = await storage.getStringAsync(QUEUE_KEY) || '[]';
  const arr = JSON.parse(q);
  arr.push({ ...event, ts: Date.now() });
  // keep queue size bounded
  if (arr.length > 100000) arr.splice(0, arr.length - 100000);
  await storage.setStringAsync(QUEUE_KEY, JSON.stringify(arr));
}

async function buildBatch() {
  const q = JSON.parse(await storage.getStringAsync(QUEUE_KEY) || '[]');
  const batch = q.splice(0, 250);
  await storage.setStringAsync(QUEUE_KEY, JSON.stringify(q));
  return batch;
}

async function sendBatch(batch) {
  const encoded = msgpack.encode(batch);
  const compressed = pako.gzip(encoded);
  const res = await fetch('https://collector.example.com/ingest', {
    method: 'POST',
    headers: { 'Content-Type': 'application/msgpack', 'Content-Encoding': 'gzip' },
    body: compressed
  });
  if (!res.ok) throw new Error('Send failed');
}

// background loop
setInterval(async () => {
  try {
    const batch = await buildBatch();
    if (batch.length) await sendBatch(batch);
  } catch (err) {
    console.warn('telemetry send error', err);
    // re-enqueue batch or increment retry counts
  }
}, 10000);

Performance and cost optimization tips

Prefer binary formats (MessagePack/Protobuf) to reduce bytes and CPU transfer times.
Avoid shipping heavyweight context for every event. Use session or context-once semantics.
Aggregate simple counters on-device for ultra-high-frequency events and flush aggregated deltas periodically.
Use TTL and partitions in ClickHouse aggressively to control storage costs.
Use materialized views to pre-aggregate common queries and reduce query-time CPU.

Security, privacy and compliance

By 2026 regulatory scrutiny is higher. Best practices:

Provide SDK APIs to remove user data (right to be forgotten).
Do not store raw PII in ClickHouse unless encrypted and access-controlled. Hash or tokenize user identifiers.
Document data retention and use-purpose in your developer portal and consent flows.

Common pitfalls and how to avoid them

Blocking UI: Never perform compression or file IO on the main thread. Use native workers.
Excessive cardinality: Don’t index or group by user_id/device_id directly; use hashed columns or separate lookup stores.
Unbounded growth: Set queue limits and ClickHouse TTLs up front.
No observability on the pipeline: Track SDK metrics and alert before dashboards go blank.

Future directions & 2026 trends to watch

In 2026 the telemetry landscape is moving toward: edge ingestion (collector edge functions), richer ClickHouse streaming connectors, and native mobile compression offload. Expect better managed ClickHouse services and lower operational overhead, and adapt SDKs to expose streaming-friendly payloads (Kafka-friendly binary formats). Privacy-preserving analytics (client-side aggregation, local differential privacy) will become standard for consumer apps.

Actionable checklist

Start by instrumenting critical events with a minimal SDK API that persists to disk.
Implement batching: count, size and time strategies with adaptive rules for network type.
Compress using a binary format and gzip/zstd for transport; prefer native compression modules.
Use a buffered proxy or Kafka bridge before ClickHouse for production-scale ingestion.
Model ClickHouse tables with partitions, materialized views and JSON props for flexibility.
Measure SDK health (queue length, drops, latency) and add CI tests for ingestion paths.

Conclusion & call-to-action

High-cardinality, low-latency telemetry from React Native apps is achievable in 2026 — but only if you design the SDK and ingestion pipeline to respect mobile constraints, privacy, and ClickHouse best practices. Start small, measure relentlessly, and iterate: durable queues, adaptive batching, native compression, and a buffered ingestion layer will get you to reliable, queryable product telemetry.

Ready to instrument with confidence? Try building the pattern above in a staging environment, run synthetic loads against a local ClickHouse, and iterate on batching and schema until query SLAs meet your product needs.

Next step: Clone a reference RN telemetry SDK and ClickHouse schema from our GitHub starter repo (recommended) — run the included Docker Compose stack to validate ingestion locally and in CI. Want the repo link and a migration checklist? Subscribe to our newsletter or drop a comment below and we’ll share a hardened starter kit for teams.

Unknown

Contributor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.