Valyrix DOCS
High-Velocity Telemetry Engine

Valyrix Developer Documentation

Comprehensive integration guides, client SDKs, real-time ingestion APIs, and high-throughput ClickHouse architecture specifications for modern engineering teams.

Quickstart v1.1.0

Get Started with Valyrix in 4 Minutes

Learn how to configure your Valyrix project, retrieve your API write key, and start dispatching high-throughput telemetry events in under four minutes.

1 Create a Project & Retrieve Your Write Key

To send telemetry events to Valyrix, you need an API Write Key associated with your project environment.

  1. Sign in to the Valyrix Console.
  2. Select or create your organization and project from the project switcher.
  3. Navigate to Project Settings → API & SDK Keys.
  4. Copy your client Write Key (formatted as SDK-proj_xxx-env_xxx-...).
Write-Only Ingestion Security Client write keys are write-only by design. They can ingest events and fetch cached feature flags, but cannot read raw analytics data or modify project configurations.

2 Install Your Preferred Client SDK

Choose your application platform to review tailored step-by-step setup guides:

3 Verify Ingestion in Real-Time

Once your application initializes the SDK and tracks an event, navigate to the Live Stream tab in the Valyrix Console. Events appear on the interactive 3D globe and telemetry terminal with sub-second edge latency.

Architecture Sub-5ms SLA

Architecture & Ingestion Pipeline

An overview of the Valyrix high-velocity distributed telemetry pipeline, from client-side persistent queues to the ClickHouse columnar storage engine.

1 Ingestion Edge Layer

The Valyrix edge ingestion layer runs on distributed Fly.io nodes. Ingestion requests (POST /v1/events/batch) undergo non-blocking schema validation, write-key verification, and rate limiting in under 5 milliseconds.

2 ClickHouse Columnar Storage Engine

Ingested events land in an optimized ClickHouse ReplacingMergeTree table (events_raw) partitioned by event date and indexed by organization, project, and event timestamp.

  • Throughput: Handles 100,000+ events per second with multi-core vectorized scans.
  • Materialized Views: events_daily_mv pre-aggregates time-series summaries for instant dashboard queries.
  • Cold Storage Compression: LZ4/ZSTD compression reduces raw telemetry byte size by up to 85%.

3 Real-Time WebSocket Telemetry Stream

Concurrently, incoming events publish to Redis Pub/Sub channels. The Live Stream WebSocket endpoint (/v1/events/stream) broadcasts sanitized payloads to connected console operators in under 150 milliseconds.

Maven Central Android API 21+ Kotlin 2.0+ v1.1.0

Valyrix Android SDK (Kotlin & Compose)

Comprehensive Android telemetry with Jetpack Compose support, persistent DataStore queueing, OkHttp exponential backoff, and crash reporting.

1 Add Dependency

Add the Valyrix Android SDK dependency in your module's build.gradle.kts:

dependencies {
    implementation("io.valyrix:valyrix-android-sdk:1.1.0")
}
dependencies {
    implementation 'io.valyrix:valyrix-android-sdk:1.1.0'
}

2 Initialize in Application Class

Initialize Valyrix inside your custom Application class or main ComponentActivity:

import android.app.Application
import io.valyrix.sdk.core.Valyrix
import io.valyrix.sdk.model.ValyrixLogLevel

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        Valyrix.initialize(
            context = applicationContext,
            writeKey = "SDK-your-project-id-write-key"
        ) {
            serverUrl = "https://valyrix-api.fly.dev"
            flushIntervalSeconds = 30
            flushQueueSize = 20
            enableCrashReporting = true
            logLevel = ValyrixLogLevel.INFO
        }
    }
}

3 Track Events & Identify Users

Record custom events and link authenticated users:

// Identify authenticated user
Valyrix.identify(
    userId = "usr_10284",
    traits = mapOf(
        "email" to "[email protected]",
        "tier" to "pro"
    )
)

// Track behavioral event
Valyrix.track(
    eventName = "checkout_completed",
    properties = mapOf(
        "amount" to 89.99,
        "currency" to "USD",
        "items" to 4
    )
)
SPM Compatible iOS 14.0+ Swift 5.9+ v1.1.0

Valyrix iOS SDK (Swift & SwiftUI)

High-performance native telemetry, automatic screen tracking, crash reporting, and real-time feature flags for iOS applications.

1 Installation via Swift Package Manager

Valyrix is distributed as an ABI-stable pre-compiled binary XCFramework via Swift Package Manager:

1. In Xcode, select File > Add Package Dependencies...
2. Enter the repository URL:
   https://github.com/valyrix-io/valyrix-ios-framework.git
3. Set Dependency Rule to "Up to Next Major Version" from 1.1.0
4. Link the "Valyrix" library to your app target
dependencies: [
    .package(url: "https://github.com/valyrix-io/valyrix-ios-framework.git", from: "1.1.0")
]

2 Initialize the SDK

Initialize Valyrix in your SwiftUI App entrypoint or UIKit AppDelegate:

import SwiftUI
import Valyrix

@main
struct MyApp: App {
    init() {
        let config = ValyrixConfig(
            writeKey: "SDK-your-project-id-write-key",
            serverUrl: "https://valyrix-api.fly.dev",
            flushIntervalSeconds: 30,
            trackLifecycleEvents: true,
            trackScreenViews: true,
            enableCrashReporting: true,
            enableFeatureFlags: true
        )
        Valyrix.initialize(config: config)
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
import UIKit
import Valyrix

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        let config = ValyrixConfig(
            writeKey: "SDK-your-project-id-write-key",
            serverUrl: "https://valyrix-api.fly.dev"
        )
        Valyrix.initialize(config: config)
        return true
    }
}

3 Identify Users

Bind anonymous device sessions to an authenticated user identity when a user logs in:

Valyrix.identify(userId: "usr_99812", traits: [
    "email": "[email protected]",
    "plan": "enterprise",
    "organization": "Acme Corp"
])

4 Track Custom Events

Dispatch behavioral and business telemetry with structured custom properties:

Valyrix.track("order_completed", properties: [
    "order_id": "ord_88219",
    "total_cents": 4999,
    "currency": "USD",
    "item_count": 3,
    "payment_method": "apple_pay"
])

5 Feature Flags & Remote Config

Check dynamic feature flags with sub-millisecond local cache evaluation:

if Valyrix.isFeatureEnabled("new_checkout_flow", defaultValue: false) {
    // Render upgraded checkout flow
} else {
    // Render standard checkout flow
}
Nitro Module RN 0.74+ Expo Ready

Valyrix React Native & Expo SDK

High-performance typed Nitro module for React Native and Expo applications with zero bridge serialization lag.

1 Installation

Install the package and required peer dependencies:

npm install @valyrix/react-native react-native-nitro-modules
cd ios && pod install
yarn add @valyrix/react-native react-native-nitro-modules
cd ios && pod install

2 Initialize SDK

import { Valyrix } from '@valyrix/react-native';

Valyrix.initialize({
  writeKey: 'SDK-your-project-id-write-key',
  enableCrashReporting: true,
  enableFeatureFlags: true,
});

// Track custom event
Valyrix.track('order_completed', {
  orderId: 'ord_12345',
  total: 49.99,
  currency: 'USD',
});
Multiplatform Android & iOS Compose Multiplatform

Valyrix Kotlin Multiplatform (KMP) SDK

Share 100% of your telemetry, screen tracking, and feature flagging logic across Android and iOS inside commonMain.

1 Add commonMain Dependency

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.valyrix:valyrix-kmp-core:1.1.0")
        }
    }
}
pub.dev Flutter 3.24+ Dart 3.5+ v1.1.0

Valyrix Flutter SDK (Dart)

Cross-platform mobile telemetry with automatic NavigatorObserver screen tracking, background isolate event flushing, and feature flags.

1 Add Dependency

Add valyrix_flutter to your pubspec.yaml:

dependencies:
  valyrix_flutter: ^1.1.0
flutter pub add valyrix_flutter

2 Initialize SDK in main.dart

import 'package:flutter/material.dart';
import 'package:valyrix_flutter/valyrix_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final sdk = await Valyrix.initialize(
    ValyrixConfig(
      writeKey: 'SDK-your-project-id-write-key',
      serverUrl: 'https://valyrix-api.fly.dev',
      trackScreenViews: true,
      enableCrashReporting: true,
    ),
  );
  runApp(MyApp(sdk: sdk));
}

class MyApp extends StatelessWidget {
  final Valyrix sdk;
  const MyApp({super.key, required this.sdk});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorObservers: [
        ValyrixNavigatorObserver(sdk: sdk),
      ],
      home: HomeScreen(sdk: sdk),
    );
  }
}
NPM Package 4 KB Gzip Zero Dependencies

Valyrix Web SDK (JavaScript / TypeScript)

Privacy-first, zero-dependency browser telemetry with multi-tab atomic queueing, automatic SPA page tracking, and dynamic feature flags.

1 Installation

npm install @valyrix/web-sdk
<script src="https://cdn.jsdelivr.net/npm/@valyrix/web-sdk/dist/bundle/valyrix.min.js"></script>

2 Usage in React / Next.js

import { Valyrix } from '@valyrix/web-sdk';

Valyrix.init({
    writeKey: 'SDK-your-project-id-write-key',
    autoTrackPageviews: true,
    autoTrackClicks: true,
});

Valyrix.track('signup_completed', { plan: 'enterprise' });
Feature Flags Sub-Millisecond

Feature Flags & Remote Config

Real-time flag evaluation, percentage rollouts, cohort targeting rules, and instant kill switches without app store redeployments.

1 Overview & Local Cache Architecture

Valyrix feature flags evaluate locally against a persistent snapshot cached on device. Flag evaluations execute synchronously in <0.2 milliseconds without waiting for network roundtrips.

2 Evaluating Flags in Code

let isEnabled = Valyrix.isFeatureEnabled("ai_recommendations_v2", defaultValue: false)
val isEnabled = Valyrix.isFeatureEnabled("ai_recommendations_v2", defaultValue = false)
const isEnabled = Valyrix.isFeatureEnabled('ai_recommendations_v2', false);
Crash Reporting dSYM & ProGuard

Crash Reporting & Symbolication

Automated capture of uncaught exceptions, native signals (SIGSEGV, SIGABRT), stack trace symbolication, and user journey breadcrumbs.

1 Automated Crash Capture

Valyrix hooks into platform exception handlers (Mach exception ports on iOS, Thread.UncaughtExceptionHandler on Android). Unhandled crashes persist immediately to flash storage before app termination and flush on next restart.

2 iOS dSYM Symbolication

Upload your Xcode dSYM archives to demangle C++ and Swift function signatures:

npx valyrix-cli upload-dsym \
  --project-id proj_d35 \
  --api-key VALYRIX_ADMIN_KEY \
  --path ./build/MyApp.app.dSYM.zip
Privacy First GDPR & CCPA

Privacy, PII Masking & Compliance

Zero-trust data sanitization, automatic client-side redacting of URL tokens, DOM masking, and user opt-out compliance.

1 Automatic Token Redaction

Valyrix SDKs automatically redact sensitive query strings (such as token, password, secret, session_id) and replace them with [REDACTED] prior to transmission over the network.

2 User Opt-Out Support

Honor user telemetry consent toggles with instant local queue purging:

Valyrix.setOptOut(true)
Valyrix.setOptOut(true)
Session Replay Wireframe Reconstruction Zero Screenshot Overhead

Mobile Session Replay

Visual telemetry reconstruction of user journeys with sub-second playback, native privacy masking, and negligible battery overhead.

1 How It Works

Unlike legacy session replay tools that capture periodic JPEG/PNG screenshots (which consume heavy bandwidth and drain user battery), Valyrix reconstructs UI hierarchy changes via a vectorized DOM/View tree wireframe protocol.

  • Bandwidth: Average stream bandwidth under 15 KB/minute over mobile cellular.
  • Battery Impact: Less than 0.5% CPU overhead during active interactions.
  • Instant Scrubbing: Time-synchronized with crash breadcrumbs and funnel steps.

2 Automated Masking & Exclusion

All text inputs, payment forms, and elements marked with data-valyrix-mask or .valyrix-sensitive are masked locally on the device prior to compression.

REST API HTTP / 2 POST /v1/events/batch

Batch Event Ingestion API

High-velocity HTTP endpoint for ingesting structured telemetry batches directly from servers, IoT devices, or custom clients.

1 Endpoint Specification

POST https://valyrix-api.fly.dev/v1/events/batch

Headers

  • Content-Type: application/json
  • X-Valyrix-Write-Key: SDK-your-project-id-write-key

2 Sample curl Request

curl -X POST https://valyrix-api.fly.dev/v1/events/batch \
  -H "Content-Type: application/json" \
  -H "X-Valyrix-Write-Key: SDK-proj_d35-env_b436d382-fa9-yj5GmOugJtTWIbreG3IrZA" \
  -d '{
    "batch": [
      {
        "eventId": "evt_99812480",
        "eventName": "purchase_completed",
        "timestamp": "2026-11-19T08:00:00Z",
        "userId": "usr_99812",
        "properties": {
          "total_amount": 149.00,
          "currency": "USD"
        }
      }
    ]
  }'

3 HTTP Response Codes

  • 200 OK — Batch accepted and queued for ClickHouse insertion.
  • 400 Bad Request — Malformed JSON payload or missing required fields.
  • 401 Unauthorized — Invalid or suspended API Write Key.
  • 429 Too Many Requests — Rate limit exceeded; inspect the Retry-After response header.
Support & SLA 99.99% Uptime

Developer Support & SLA Commitments

Direct engineering support channels, cluster uptime guarantees, and enterprise incident response workflows.

1 Official Channels

2 Enterprise SLA Commitments

Valyrix guarantees 99.99% monthly ingestion uptime and a P99 ingestion latency under 5 milliseconds.