This page is for developers who run their own Shipvo control plane. You will get your release telemetry as Parquet files in your own R2 bucket, and SQL queries that answer "did this release help or hurt?".
The control plane can copy release telemetry to your own R2 bucket as Apache Parquet files. Any tool that reads Parquet can query them: DuckDB, Spark, pyarrow, or an agent that runs SQL. No Shipvo API is in the way.
Turn it on
One setting: bind an R2 bucket named EXPORT_BUCKET in services/control-plane/wrangler.toml.
cd services/control-plane
npx wrangler r2 bucket create shipvo-telemetry
npx wrangler d1 migrations apply shipvo --remote # adds the telemetry_export tableUncomment the [[r2_buckets]] block at the end of wrangler.toml and run npx wrangler deploy. A cron runs at minute 17 of every hour. Without the binding it does nothing.
What is written
telemetry/v1/app=<app_id>/day=<YYYY-MM-DD>/part-<first id>.parquet- One file per app, per day, per batch. A run writes up to 10 batches of 5000 rows per app; a larger backlog drains over the next runs.
- The file is named by its first row id. A retry after a failure starts after the same mark, so it writes the same key and overwrites the file. It never duplicates rows.
- If one app fails (for example an R2 error), the error is logged with the app id and the other apps still export.
appanddayare partitions in the path. DuckDB reads them as columns withhive_partitioning.- The columns are defined in
@shipvo/schema(TELEMETRY_EXPORT_COLUMNS, versionTELEMETRY_EXPORT_VERSION). The version is also in the path (v1) and in each file's metadata. A rename, removal or type change bumps the version; a new nullable column at the end does not.
| Column | Type | Meaning |
|---|---|---|
id | int64 | Row id, increasing |
received_at | string | UTC time, ISO 8601 |
app_id | string | App id |
release | int64 | Release number |
event | string | applied, rolled_back, crash_loop_revert, download_failed, verify_failed, ... |
cold_start_ms | double, null | Cold start time |
bytes_downloaded | int64, null | Bytes downloaded |
apply_ms | double, null | Time to apply the update |
device_class | string, null | low, mid, high |
published_at | string, null | When the release was published |
device_model | string, null | Device model |
android_api | int64, null | Android API level |
via | string, null | patch or full |
No personal data. The control plane stores no device id, user id or IP address with telemetry, so the export has none. Use device_class to group devices.
Query with DuckDB
The three queries below were run with DuckDB 2.0.0 against a local directory laid out like the export keys, with the files written by the export code.
Create an R2 API token (S3 compatible) and read through the S3 endpoint:
INSTALL httpfs; LOAD httpfs;
CREATE SECRET r2 (
TYPE r2, KEY_ID '<access key id>', SECRET '<secret access key>', ACCOUNT_ID '<cloudflare account id>'
);
CREATE VIEW telemetry AS
SELECT * FROM read_parquet('r2://shipvo-telemetry/telemetry/v1/*/*/*.parquet', hive_partitioning = true);Adoption by device class for one app:
SELECT release, device_class,
count(*) FILTER (WHERE event = 'applied') AS applied,
count(*) FILTER (WHERE event IN ('rolled_back', 'crash_loop_revert')) AS reverted
FROM telemetry WHERE app = 'tide'
GROUP BY release, device_class ORDER BY release, device_class;Crash-loop reverts per release:
SELECT release, count(*) AS crash_loop_reverts
FROM telemetry WHERE event = 'crash_loop_revert'
GROUP BY release ORDER BY release;Cold start p50 and p95 by release:
SELECT release,
quantile_cont(cold_start_ms, 0.5) AS p50_ms,
quantile_cont(cold_start_ms, 0.95) AS p95_ms,
count(cold_start_ms) AS samples
FROM telemetry WHERE cold_start_ms IS NOT NULL
GROUP BY release ORDER BY release;Query from an agent
Give the agent the DuckDB CLI (or any DuckDB MCP server) with the view above and read-only R2 credentials, and tell it the column table. Agents write these queries well because the schema is plain SQL types. Keep the token read-only and scoped to this bucket.
Check a file without R2
Any Parquet reader opens a file you downloaded:
python3 -c "import pyarrow.parquet as pq; print(pq.read_table('part-000000000001.parquet').to_pandas())"Troubleshooting
- No files appear in the bucket: the export runs hourly. Check the R2 binding named in Turn it on and wait for the next hour.
- DuckDB cannot read a file: confirm the file with the pyarrow check above first.
- Nothing is written and no error shows: the export does nothing without the
EXPORT_BUCKETbinding. Runnpx wrangler deployagain after you uncomment the[[r2_buckets]]block. - Errors mention
telemetry_export: the migration is missing. Runnpx wrangler d1 migrations apply shipvo --remote. - A query returns no rows for an app: the path partition is
app=<app_id>. Filter onapp, and read withhive_partitioning = true. - Access denied from DuckDB: the R2 token needs read access to this bucket.
Release alerts
To get a call when devices revert a release, set an alert webhook. See Revert alerts.
Next steps
- Self-hosting: deploy the control plane that writes these files.
- Revert alerts: get a call when devices revert a release.
- CLI guide:
shipvo statusshows release health without SQL.