Telemetry
Telemetry documentation

From the first event to a production answer

Learn Telemetry from first event through production instrumentation, SDKs, APIs, structured-event design, DataFusion SQL, dashboards, alerts, and troubleshooting.

Reviewed by the Telemetry product team on . Documentation coverage, navigation, source references, and production boundaries. Review standards and ownership

Open quick startRun the SQL Lab

97

documentation pages

5

learning sections

HTML for people, Markdown for agents

Every documentation article has a canonical HTML page and a noindex raw Markdown representation.

Choose by goal

Start with the decision or implementation boundary

Monitor AI and agent workflows

Connect model usage, cost, latency, tools, retrieval quality, and reviewed product outcomes without storing raw prompts by default.

OpenAI cost trackingAI-assisted SQL

Troubleshoot a production path

Separate ingestion, schema, query, alert, and downstream delivery failures before changing instrumentation.

Event ingestionSQL queries

Getting started

Create a key, send and verify the first event, write SQL, and finish the initial production checklist.

Quick Start

Send a structured event, inspect its table, query it with SQL, and turn the result into a dashboard or alert.

Read page

Send Your First Structured Event

Create a write-scoped API key, send one synthetic structured event, and choose an event name and fields that remain useful in production.

Read page

Verify Event Ingestion and Schema

Confirm that a test event reached the expected table with the intended types, timestamp, identifiers, and privacy boundary before expanding instrumentation.

Read page

Write Your First Telemetry SQL Query

Query a verified structured-event table, calculate volume and error rate, inspect raw rows, and validate the result against a known synthetic fixture.

Read page

Create Your First Dashboard and Alert

Promote a validated query into a focused dashboard widget and a threshold alert with an explicit owner, time window, and response action.

Read page

Production Instrumentation Checklist

Review event ownership, schema stability, sensitive-data boundaries, credentials, failure behavior, retention, queries, dashboards, and alerts before production rollout.

Read page

API Keys and Authentication

Create, scope, store, rotate, and revoke Telemetry API keys without exposing ingestion or query access to untrusted clients.

Read page

Teams, Workspaces, Members, and Roles

Organize analysis into team workspaces, invite members, understand admin and member roles, and review access before sharing data.

Read page

Usage, Billing, and Plan Limits

Review storage and query-duration usage, understand free-plan enforcement, compare current pricing, and plan upgrades safely.

Read page

SDKs and HTTP

Use server-side JavaScript, Python, Rust, Go, Ruby, PHP, or cURL with explicit delivery and credential boundaries.

JavaScript and TypeScript SDK

Install the Telemetry JavaScript SDK, send structured events, run typed SQL queries, verify delivery, and handle production failure modes.

Read page

Python SDK

Use the synchronous and asynchronous Telemetry Python clients to send events, query data, batch rows, and handle production delivery safely.

Read page

Rust SDK

Initialize the blocking Telemetry Rust client, send structured JSON events, query SQL, and design safe production delivery behavior.

Read page

Go SDK

Initialize the Telemetry Go client, send structured events, query SQL, verify delivery, and design safe production timeouts and retries.

Read page

Ruby HTTP Integration

Send structured events, run SQL, configure Net::HTTP timeouts, verify schemas, and handle Telemetry API failures safely from Ruby.

Read page

PHP HTTP Integration

Send structured events, run SQL, configure cURL timeouts, verify schemas, and handle Telemetry API failures safely from PHP.

Read page

cURL and HTTP API Examples

Send events, inspect schemas, run SQL, export Parquet, and handle Telemetry HTTP failures safely with cURL.

Read page

Java HTTP Integration

Send structured Telemetry events and SQL queries from Java with a shared HttpClient, bounded timeouts, safe JSON, and explicit failure handling.

Read page

.NET HTTP Integration

Send structured Telemetry events and SQL queries from .NET with IHttpClientFactory, bounded timeouts, typed payloads, and explicit failure handling.

Read page

API reference

Review request and response contracts for ingestion, queries, dashboards, tables, deletion, rate limits, and errors.

Log

Ingest structured JSON events into Telemetry via the HTTP API.

Read page

Query

Run SQL queries and async exports against your Telemetry data.

Read page

Dashboard

List, create, update, and delete Telemetry dashboards with the HTTP API.

Read page

Tables

Inspect Telemetry tables and configure retention and partition columns through the HTTP API.

Read page

Delete

Delete rows or whole tables through Telemetry's legacy delete endpoint.

Read page

Rate Limits and API Errors

Handle Telemetry HTTP errors, throttling, retries, idempotency, and partial failures safely in ingestion and query clients.

Read page

OpenAPI Specification

Download and validate Telemetry's OpenAPI 3.1 specification for event ingestion, SQL queries, tables, dashboards, and deletion.

Read page

Concepts and SQL patterns

Design stable event contracts, control schema and cardinality, and use reusable DataFusion SQL patterns.

Telemetry architecture

See how Telemetry validates and buffers events, stores Parquet in S3, and combines fresh and historical data for SQL queries.

Read page

Creating Dashboards

Build focused Telemetry dashboards from Explore and SQL query results, then arrange widgets for fast operational decisions.

Read page

Schema Evolution

Learn how Telemetry adapts as event fields are added or change type, and how to evolve schemas without breaking analysis.

Read page

Choosing Partition Columns

Use partition columns to make selective Telemetry queries scan less data.

Read page

Querying Nested JSON

Query top-level and nested JSON fields in Telemetry using stable dotted column names.

Read page

Working with Timestamps

Store timestamps consistently and use SQL to extract, bucket, compare, and measure time intervals.

Read page

CamelCase vs snake_case

Understand why snake_case produces simpler, more portable SQL column names for Telemetry event data.

Read page

Structured Events vs Text Logs

Compare structured events and text logs, including when to use each, how they differ in SQL, and how to avoid duplicating telemetry.

Read page

Logs, Metrics, Traces, and Structured Events

Choose the right observability signal for debugging, trends, request paths, and business workflows without collecting redundant data.

Read page

Designing an Event Schema

Create stable event names and typed fields for reliable SQL, dashboards, alerts, and schema evolution.

Read page

High-Cardinality Fields

Use user IDs, request IDs, URLs, and other high-cardinality event fields deliberately in SQL, dashboards, and partitions.

Read page

Correlation IDs for Structured Events

Connect requests, jobs, webhooks, and traces with safe correlation identifiers while avoiding sensitive data and unstable joins.

Read page

Redacting Sensitive Data from Events

Prevent secrets, personal data, and raw customer content from entering structured events with allowlists and boundary-level controls.

Read page

DataFusion SQL Reference for Telemetry

Write practical DataFusion SQL for Telemetry event tables using time filters, conditional aggregates, percentiles, windows, joins, and safe ratios.

Read page

Event Delivery, Idempotency, and Duplicate Handling

Design structured-event producers for retries, duplicate delivery, stable event identity, and measurable ingestion failures.

Read page

Batching, Backpressure, and Graceful Shutdown

Choose safe batch sizes, bound telemetry queues, handle overload, and flush or persist pending events during application shutdown.

Read page

Event Sampling Strategies for Structured Telemetry

Reduce telemetry volume without invalidating rates, percentiles, incident investigations, or customer-impact analysis.

Read page

Multi-Tenant Identity Modeling for Event Analytics

Model accounts, users, sessions, anonymous visitors, and tenant boundaries without mixing identity semantics or exposing personal data.

Read page

Alerts

Create understandable threshold alerts from single-series time charts in Explore and query results.

Read page

Event Data Types and Nullability

Choose stable string, numeric, boolean, timestamp, and nested event fields so schemas evolve without breaking SQL.

Read page

Data Retention and Deletion

Plan table retention, selective deletion, whole-table removal, and verification for structured event data.

Read page

Canonical Wide Events

Design canonical wide events that capture one completed unit of work with the context needed for SQL, debugging, dashboards, and agent analysis.

Read page

SQL Conditional Aggregation

Use CASE expressions with COUNT, SUM, and AVG to calculate rates, segments, and operational outcomes from structured event data.

Read page

SQL Time Bucketing for Event Data

Group structured events into complete UTC intervals with date_trunc or date_bin, then compare rates and volume without partial-bucket mistakes.

Read page

SQL Percentiles for Latency and Distributions

Calculate approximate p50, p95, and p99 values in DataFusion SQL and interpret tail latency without hiding volume or distribution shape.

Read page

SQL Window Functions for Event Analysis

Use LAG, ROW_NUMBER, and framed aggregates to compare periods, deduplicate events, and calculate rolling baselines without losing row detail.

Read page

SQL Deduplication for Structured Events

Define event identity and use ROW_NUMBER to remove duplicate deliveries without accidentally collapsing valid retries or repeated user actions.

Read page

SQL Funnel Analysis

Build account-level product funnels with conditional milestones, explicit ordering, a cohort window, and conversion denominators that remain reviewable.

Read page

SQL Cohort Retention Analysis

Measure whether users or accounts return after a starting milestone while keeping cohort dates, activity windows, identities, and incomplete periods explicit.

Read page

Production guides

Implement complete product, reliability, AI, billing, database, security, and reporting workflows.

Structured Logging Guide

Design structured application events that are safe to collect, easy to query with SQL, and useful for dashboards, debugging, and product decisions.

Read page

Application Telemetry: A Practical Guide

Design application telemetry that connects structured events, logs, metrics, and traces to reliable SQL, dashboards, and alerts.

Read page

OpenAI API Cost Tracking by Model and Feature

Track OpenAI API costs by model, feature, team, and outcome. Copy a production-ready event shape and SQL query, then reconcile estimates to your invoice.

Read page

Evaluate AI Agents with Structured Events and SQL

Design AI agent evaluation events, join quality with cost and reliability, and compare releases with reviewable SQL and explicit denominators.

Read page

AI Agent Security Monitoring with Structured Events

Monitor agent tool authorization, policy denials, human approvals, and terminal outcomes with bounded events and reviewable SQL.

Read page

Connect OpenTelemetry GenAI Traces to Outcome Events

Correlate OpenTelemetry generative AI traces with compact Telemetry outcome events without copying prompts, tool payloads, or full spans.

Read page

Revenue A/B Tests

Compare revenue per exposed visitor across experiment variants and quantify lift without being misled by unequal traffic.

Read page

Monitoring Website Uptime

Log scheduled heartbeat checks to measure uptime, investigate incidents, and alert on repeated failures.

Read page

Queue Worker Observability

Monitor queue depth and tail latency together to detect backlogs, stuck workers, and user-visible processing delays.

Read page

Visualizing Distributions

Use percentiles to reveal typical values, long tails, and high-value customer segments that a single average can hide.

Read page

Measuring Conversion Rates with SQL

Instrument funnel milestones and calculate user-level conversion rates so you can locate drop-off without double-counting repeated events.

Read page

Analyzing Webserver Errors

Capture status, route, release, and request context so error spikes lead to a specific regression instead of a generic count.

Read page

Profiling Code Execution

Log step durations and execution context to find bottlenecks, compare runs, and prioritize performance work.

Read page

Exporting Query Results

Choose synchronous JSON or asynchronous JSON and Parquet exports, poll safely, and preserve query context for downstream reporting.

Read page

Alert Delivery and Troubleshooting

Verify Telemetry alert queries, time buckets, thresholds, recipients, evaluation history, and email delivery without creating noisy pages.

Read page

Troubleshooting Event Ingestion

Diagnose missing or rejected Telemetry events by checking HTTP responses, API-key scope, payload shape, table normalization, timestamps, schemas, retries, and freshness.

Read page

Troubleshooting SQL Queries

Debug Telemetry SQL systematically by checking the API response, table schema, DataFusion syntax, field types, time windows, joins, rates, and async export status.

Read page

Incident Response with SQL

Use a repeatable SQL workflow to scope an incident, identify affected routes and releases, build a timeline, and verify recovery from structured events.

Read page

Database Reliability Monitoring with SQL

Instrument safe application-level database events and use SQL to investigate slow query fingerprints, pool contention, rollbacks, locks, replication lag, and migrations.

Read page

Migrate from Ad Hoc Logs to Structured Events and SQL

Move a production workflow from free-form log search to bounded structured events, tested SQL, dashboards, and alerts without requiring a risky all-at-once cutover.

Read page

Frontend Reliability Monitoring with SQL

Instrument typed browser performance events and use SQL to compare Core Web Vitals by route and release without collecting raw page content.

Read page

Browser Telemetry Proxy and Core Web Vitals

Collect privacy-conscious browser events and Core Web Vitals through a rate-limited server proxy without exposing a Telemetry API key.

Read page

Event Tracking Plan and Governance

Create an event tracking plan with explicit grain, ownership, fields, privacy, validation, retention, and downstream SQL dependencies.

Read page

Test Telemetry Instrumentation in CI

Test structured-event contracts, privacy boundaries, delivery failures, and SQL results in CI without sending production data or depending on a live API.

Read page

Use Telemetry with OpenTelemetry

Use Telemetry outcome events beside OpenTelemetry traces, metrics, and logs with safe correlation IDs and explicit signal boundaries.

Read page

Kubernetes Reliability Monitoring with SQL

Use structured Kubernetes workload events and SQL to investigate container restarts, readiness loss, rollout changes, and application impact.

Read page

Security Audit Analytics with SQL

Design bounded privileged-action events and use SQL to review denials, failures, and human-review queues without exposing secrets.

Read page

Product Journey Analysis with SQL

Model ordered product milestones and use SQL to measure session journey completion and step-to-step drop-off with explicit counting rules.

Read page

Telemetry Cost and Volume Management

Measure event count, payload bytes, rejection rate, retention, and cardinality before changing a telemetry collection contract.

Read page

Customer Impact Analysis with SQL

Connect incidents to privacy-safe account impact events and use SQL to count affected accounts, affected share, and impact duration by plan.

Read page

RAG Evaluation with SQL

Version RAG evaluation events and use SQL to compare retrieval relevance, grounded answers, latency, and cost across pipeline releases.

Read page

Feature Rollout Analysis with SQL

Compare control and rollout cohorts with SQL using stable feature assignment, release context, request volume, errors, and latency.

Read page

SQL for Observability and Event Analytics

Learn how structured events become SQL-ready observability data, which event contracts work, how to query them, and where SQL should complement logs, metrics, and traces.

Read page

Send Scheduled SQL Reports to Slack

Run a Telemetry SQL query on a schedule, format the result as a concise Slack message, protect webhook credentials, and make delivery failures observable.

Read page

Migrate LogQL, KQL, and SPL Queries to SQL

Translate common LogQL, Kusto Query Language, and Splunk SPL analysis patterns into reviewable SQL without assuming the languages or data models are identical.

Read page

End-to-End SaaS Observability Demo

Run a small Node.js SaaS workflow that emits structured events, query the resulting table with SQL, and turn one event contract into reliability, product, and cost views.

Read page

Benchmark Telemetry Ingestion and Query Performance

Run a reproducible, bounded Telemetry API benchmark, separate client timing from service behavior, publish the test conditions, and avoid unsupported performance claims.

Read page

SLI, SLO, and Error Budget Monitoring with SQL

Define request-based service indicators, calculate SLO compliance and error-budget burn, and build reviewable reliability alerts with SQL.

Read page

Explore Structured Events Without Starting from SQL

Inspect event samples, apply typed filters, aggregate fields, build charts, and promote a reviewed Explore result into a dashboard or alert.

Read page

AI-Assisted SQL: Generate, Review, and Validate Queries

Turn a focused event question into editable DataFusion SQL, then review schema assumptions, counting logic, privacy boundaries, and result validity.

Read page

Saved Queries, History, Favorites, and Collaboration

Organize reviewed SQL in team workspaces, preserve query history, use personal favorites, and promote stable results into shared dashboards and alerts.

Read page

Secure Mobile Telemetry Proxy

Route React Native, Swift, Kotlin, and Flutter events through an authenticated server proxy that keeps ingestion keys out of app binaries.

Read page

How Telemetry Evaluates SQL Alerts

See how Telemetry evaluates saved SQL, selects points, aggregates values, records state transitions, and attempts email delivery.

Read page