Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

feat: send an anonymous daily instance snapshot (#35)

Croffbe68f4aa64d3
diff --git a/.env.example b/.env.example
index 1db8a95f..e9ece2f2 100644
--- a/.env.example
+++ b/.env.example
@@ -86,6 +86,11 @@ WORKER_INTERNAL_TOKEN=change-me-please-generate-a-real-secret
# defaults to the SMTP username. NOTIFICATIONS_EMAIL_FROM is read as a fallback.
# EMAIL_FROM=Its a Plan <[email protected]>
+# ── Anonymous telemetry (apps/worker) — see TELEMETRY.md ──
+# TELEMETRY_DISABLED=1 # opt out (any value but 0)
+# DO_NOT_TRACK=1 # opt out, cross-tool convention
+# TELEMETRY_DEBUG=1 # log the exact body before each send
+
# ── Web (Next.js) ──
# The browser bundle needs NEXT_PUBLIC_API_URL (= API_URL above) and the optional
# NEXT_PUBLIC_PRIVACY_URL / NEXT_PUBLIC_TERMS_URL (= PRIVACY_URL / TERMS_URL above),
diff --git a/TELEMETRY.md b/TELEMETRY.md
new file mode 100644
index 00000000..179f7543
--- /dev/null
+++ b/TELEMETRY.md
@@ -0,0 +1,72 @@
+# Telemetry
+
+A self-hosted instance sends one snapshot of itself a day. It tells the project which
+versions are still running, which features get used, and where deliveries fail on
+machines nobody reports from.
+
+Telemetry is on by default. Everything it sends is listed below.
+
+## When it is sent
+
+The first snapshot goes out when the worker starts, so an instance that is set up and
+removed the same hour is still counted once. After that each instance picks one minute
+of the day at random and keeps it, then reports once a day from that minute on. That
+spreads the traffic instead of every instance reporting at midnight UTC.
+
+A send that fails is retried with a growing delay for five attempts, then once an hour.
+The worker logs each failure and carries on with its other work.
+
+## Turning it off
+
+Set either variable in `.env`:
+
+```bash
+TELEMETRY_DISABLED=1
+# or the cross-tool convention, read the same way:
+DO_NOT_TRACK=1
+```
+
+Any value except `0` (and an empty one) turns telemetry off. Nothing is sent after
+that, and no instance id is generated.
+
+## Seeing what is sent
+
+```bash
+TELEMETRY_DEBUG=1
+```
+
+The worker logs the exact body before each send.
+
+## What is sent
+
+- A random id, generated once for this instance.
+- The day the instance was installed, taken from the timestamp of its first database
+ migration.
+- The running version.
+- The runtime: Bun version, OS and architecture, Postgres major version, whether it
+ runs in Docker.
+- How many users, projects and issues there are, plus how many users signed in and how
+ many issues were created in the last 30 days. All of it as size ranges (`6-20`,
+ `101-1000`), never exact numbers.
+- Which features are used at all, as yes/no: initiatives, note boards, dashboards,
+ saved views, custom fields, label groups, project actions, attachments.
+- Which integrations are set up and switched on, as yes/no: email, Google sign-in,
+ Telegram bot, webhooks, API keys, MCP, per-project integration credentials.
+- AI agents: how many, how many runs in the last 30 days (as ranges), whether
+ schedules are used.
+- The share of webhook deliveries and of agent runs that failed in the last 30 days.
+
+## What is never sent
+
+Names of anything. Project keys, issue titles, descriptions, comments. Email
+addresses, user names. Webhook URLs, agent prompts, credentials, environment
+variables, file contents, logs, error messages. Exact counts.
+
+The instance id is a random uuid stored in the database. It is not derived from your
+domain, your keys, or anything else in the instance.
+
+## Where it goes
+
+`https://telemetry.itsaplan.dev`, operated by the project. No third-party analytics
+service is involved. The address is fixed in the worker; there is no setting that
+points it somewhere else.
diff --git a/apps/worker/src/__tests__/unit/telemetry-payload.test.ts b/apps/worker/src/__tests__/unit/telemetry-payload.test.ts
new file mode 100644
index 00000000..bf28d611
--- /dev/null
+++ b/apps/worker/src/__tests__/unit/telemetry-payload.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'bun:test';
+import { bucket, buildPulse, failureRate, type InstanceCounts } from '../../telemetry-payload';
+
+describe('bucket', () => {
+ it('reports zero and one exactly', () => {
+ expect(bucket(0)).toBe('0');
+ expect(bucket(1)).toBe('1');
+ });
+
+ it('reports a range for anything larger', () => {
+ expect(bucket(2)).toBe('2-5');
+ expect(bucket(5)).toBe('2-5');
+ expect(bucket(6)).toBe('6-20');
+ expect(bucket(100)).toBe('21-100');
+ expect(bucket(101)).toBe('101-1000');
+ expect(bucket(10_000)).toBe('1001-10000');
+ });
+
+ it('caps at the overflow bucket', () => {
+ expect(bucket(10_001)).toBe('10000+');
+ expect(bucket(5_000_000)).toBe('10000+');
+ });
+
+ it('treats a negative count as zero', () => {
+ expect(bucket(-1)).toBe('0');
+ });
+});
+
+describe('failureRate', () => {
+ it('rounds to two decimals', () => {
+ expect(failureRate(1, 3)).toBe(0.33);
+ expect(failureRate(2, 8)).toBe(0.25);
+ });
+
+ it('is zero when nothing failed', () => {
+ expect(failureRate(0, 10)).toBe(0);
+ });
+
+ it('is null when nothing ran, not zero', () => {
+ expect(failureRate(0, 0)).toBeNull();
+ });
+});
+
+const counts: InstanceCounts = {
+ users: 7,
+ activeUsers30d: 3,
+ projects: 2,
+ issues: 412,
+ issuesCreated30d: 30,
+ agents: 1,
+ agentRuns30d: 20,
+ agentRunsFailed30d: 5,
+ webhookDeliveries30d: 0,
+ webhookDeliveriesFailed30d: 0,
+ hasInitiatives: true,
+ hasNoteBoards: false,
+ hasDashboards: true,
+ hasCustomViews: true,
+ hasCustomFields: false,
+ hasLabelGroups: true,
+ hasProjectActions: false,
+ hasAttachments: true,
+ hasAgentSchedules: false,
+ hasWebhooks: false,
+ hasApiKeys: false,
+ hasMcpProject: true,
+ hasEmail: true,
+ hasGoogleOauth: false,
+ hasTelegramBot: true,
+ hasProjectIntegrations: false,
+};
+
+const input = {
+ instanceId: '3f2504e0-4f89-11d3-9a0c-0305e82c3301',
+ day: '2026-07-27',
+ installedDay: '2026-07-10',
+ version: '0.5.0',
+ bunVersion: '1.3.14',
+ docker: true,
+ platform: 'linux/arm64',
+ postgresMajor: 17,
+ counts,
+};
+
+describe('buildPulse', () => {
+ it('reports counts as buckets, never as exact numbers', () => {
+ const pulse = buildPulse(input);
+ expect(pulse.scale).toEqual({
+ users: '6-20',
+ activeUsers30d: '2-5',
+ projects: '2-5',
+ issues: '101-1000',
+ issuesCreated30d: '21-100',
+ });
+ expect(JSON.stringify(pulse)).not.toContain('412');
+ });
+
+ it('carries the fields the collector stores in columns', () => {
+ const pulse = buildPulse(input);
+ expect(pulse.instanceId).toBe(input.instanceId);
+ expect(pulse.day).toBe('2026-07-27');
+ expect(pulse.version).toBe('0.5.0');
+ });
+
+ it('carries the install day, so an install is not inferred from the first pulse', () => {
+ const pulse = buildPulse(input);
+ expect(pulse.installedDay).toBe('2026-07-10');
+ expect(buildPulse({ ...input, installedDay: null }).installedDay).toBeNull();
+ });
+
+ it('reports a failure rate only for what actually ran', () => {
+ const pulse = buildPulse(input);
+ expect(pulse.health.agentRunFailureRate30d).toBe(0.25);
+ expect(pulse.health.webhookFailureRate30d).toBeNull();
+ });
+
+ it('reports features and integrations as booleans', () => {
+ const pulse = buildPulse(input);
+ expect(pulse.features.initiatives).toBe(true);
+ expect(pulse.features.noteBoards).toBe(false);
+ expect(pulse.integrations.telegramBot).toBe(true);
+ expect(pulse.integrations.webhooks).toBe(false);
+ });
+});
diff --git a/apps/worker/src/__tests__/unit/telemetry-schedule.test.ts b/apps/worker/src/__tests__/unit/telemetry-schedule.test.ts
new file mode 100644
index 00000000..a9821884
--- /dev/null
+++ b/apps/worker/src/__tests__/unit/telemetry-schedule.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'bun:test';
+import {
+ MINUTES_PER_DAY,
+ minuteOfDay,
+ randomSendMinute,
+ shouldSend,
+ utcDay,
+} from '../../telemetry-schedule';
+
+describe('utcDay', () => {
+ it('formats the UTC date', () => {
+ expect(utcDay(new Date('2026-07-27T23:59:59Z'))).toBe('2026-07-27');
+ expect(utcDay(new Date('2026-07-28T00:00:00Z'))).toBe('2026-07-28');
+ });
+});
+
+describe('minuteOfDay', () => {
+ it('counts minutes since midnight UTC', () => {
+ expect(minuteOfDay(new Date('2026-07-27T00:00:00Z'))).toBe(0);
+ expect(minuteOfDay(new Date('2026-07-27T13:37:00Z'))).toBe(817);
+ expect(minuteOfDay(new Date('2026-07-27T23:59:59Z'))).toBe(MINUTES_PER_DAY - 1);
+ });
+});
+
+describe('randomSendMinute', () => {
+ it('stays inside the day', () => {
+ for (let i = 0; i < 200; i++) {
+ const minute = randomSendMinute();
+ expect(minute).toBeGreaterThanOrEqual(0);
+ expect(minute).toBeLessThan(MINUTES_PER_DAY);
+ expect(Number.isInteger(minute)).toBe(true);
+ }
+ });
+});
+
+describe('shouldSend', () => {
+ it('sends the very first pulse immediately, whatever the slot', () => {
+ expect(
+ shouldSend({ day: '2026-07-27', lastSentDay: null, minuteOfDay: 0, sendMinute: 1400 }),
+ ).toBe(true);
+ });
+
+ it('does not send twice on the same day', () => {
+ expect(
+ shouldSend({
+ day: '2026-07-27',
+ lastSentDay: '2026-07-27',
+ minuteOfDay: 1439,
+ sendMinute: 10,
+ }),
+ ).toBe(false);
+ });
+
+ it('waits for the instance slot on later days', () => {
+ const before = {
+ day: '2026-07-28',
+ lastSentDay: '2026-07-27',
+ minuteOfDay: 599,
+ sendMinute: 600,
+ };
+ expect(shouldSend(before)).toBe(false);
+ expect(shouldSend({ ...before, minuteOfDay: 600 })).toBe(true);
+ expect(shouldSend({ ...before, minuteOfDay: 1439 })).toBe(true);
+ });
+
+ it('still sends after a gap of several days once the slot passes', () => {
+ expect(
+ shouldSend({
+ day: '2026-07-30',
+ lastSentDay: '2026-07-20',
+ minuteOfDay: 700,
+ sendMinute: 600,
+ }),
+ ).toBe(true);
+ });
+});
diff --git a/apps/worker/src/telemetry-payload.ts b/apps/worker/src/telemetry-payload.ts
new file mode 100644
index 00000000..5daa28f8
--- /dev/null
+++ b/apps/worker/src/telemetry-payload.ts
@@ -0,0 +1,128 @@
+// Shapes the daily telemetry snapshot. Pure, so the rules are unit-tested.
+//
+// Counts go out as buckets, never exact, and nothing here carries a name, key, title,
+// address or email. See TELEMETRY.md.
+
+export interface InstanceCounts {
+ users: number;
+ activeUsers30d: number;
+ projects: number;
+ issues: number;
+ issuesCreated30d: number;
+ agents: number;
+ agentRuns30d: number;
+ agentRunsFailed30d: number;
+ webhookDeliveries30d: number;
+ webhookDeliveriesFailed30d: number;
+ hasInitiatives: boolean;
+ hasNoteBoards: boolean;
+ hasDashboards: boolean;
+ hasCustomViews: boolean;
+ hasCustomFields: boolean;
+ hasLabelGroups: boolean;
+ hasProjectActions: boolean;
+ hasAttachments: boolean;
+ hasAgentSchedules: boolean;
+ hasWebhooks: boolean;
+ hasApiKeys: boolean;
+ hasMcpProject: boolean;
+ hasEmail: boolean;
+ hasGoogleOauth: boolean;
+ hasTelegramBot: boolean;
+ hasProjectIntegrations: boolean;
+}
+
+export interface PulseInput {
+ instanceId: string;
+ // Both 'YYYY-MM-DD' in UTC. installedDay is null when it cannot be read.
+ day: string;
+ installedDay: string | null;
+ version: string;
+ bunVersion: string;
+ docker: boolean;
+ // '<platform>/<arch>', e.g. 'linux/arm64'.
+ platform: string;
+ postgresMajor: number | null;
+ counts: InstanceCounts;
+}
+
+// Upper bound of each bucket paired with its label; above the last one, OVERFLOW.
+const BUCKETS: ReadonlyArray<readonly [number, string]> = [
+ [0, '0'],
+ [1, '1'],
+ [5, '2-5'],
+ [20, '6-20'],
+ [100, '21-100'],
+ [1000, '101-1000'],
+ [10_000, '1001-10000'],
+];
+
+const OVERFLOW_BUCKET = '10000+';
+
+export function bucket(count: number): string {
+ for (const [max, label] of BUCKETS) {
+ if (count <= max) return label;
+ }
+ return OVERFLOW_BUCKET;
+}
+
+// Null when nothing ran: reporting 0 there would hide broken instances behind idle
+// ones once the rates are averaged.
+export function failureRate(failed: number, total: number): number | null {
+ if (total <= 0) return null;
+ return Math.round((failed / total) * 100) / 100;
+}
+
+export function buildPulse(input: PulseInput) {
+ const c = input.counts;
+ return {
+ instanceId: input.instanceId,
+ day: input.day,
+ installedDay: input.installedDay,
+ version: input.version,
+ runtime: {
+ bun: input.bunVersion,
+ docker: input.docker,
+ platform: input.platform,
+ postgresMajor: input.postgresMajor,
+ },
+ scale: {
+ users: bucket(c.users),
+ activeUsers30d: bucket(c.activeUsers30d),
+ projects: bucket(c.projects),
+ issues: bucket(c.issues),
+ issuesCreated30d: bucket(c.issuesCreated30d),
+ },
+ // Roles and issue types are absent: every project is seeded with both, so their
+ // presence does not distinguish real use from the seed.
+ features: {
+ initiatives: c.hasInitiatives,
+ noteBoards: c.hasNoteBoards,
+ dashboards: c.hasDashboards,
+ customViews: c.hasCustomViews,
+ customFields: c.hasCustomFields,
+ labelGroups: c.hasLabelGroups,
+ projectActions: c.hasProjectActions,
+ attachments: c.hasAttachments,
+ },
+ // Which are configured, never any part of the configuration.
+ integrations: {
+ email: c.hasEmail,
+ googleOauth: c.hasGoogleOauth,
+ telegramBot: c.hasTelegramBot,
+ webhooks: c.hasWebhooks,
+ apiKeys: c.hasApiKeys,
+ mcp: c.hasMcpProject,
+ projectIntegrations: c.hasProjectIntegrations,
+ },
+ ai: {
+ agents: bucket(c.agents),
+ runs30d: bucket(c.agentRuns30d),
+ schedules: c.hasAgentSchedules,
+ },
+ health: {
+ webhookFailureRate30d: failureRate(c.webhookDeliveriesFailed30d, c.webhookDeliveries30d),
+ agentRunFailureRate30d: failureRate(c.agentRunsFailed30d, c.agentRuns30d),
+ },
+ };
+}
diff --git a/apps/worker/src/telemetry-schedule.ts b/apps/worker/src/telemetry-schedule.ts
new file mode 100644
index 00000000..ba75bfbe
--- /dev/null
+++ b/apps/worker/src/telemetry-schedule.ts
@@ -0,0 +1,32 @@
+// When a pulse is due. Pure, so the rules are unit-tested.
+
+export const MINUTES_PER_DAY = 24 * 60;
+
+export function utcDay(now: Date): string {
+ return now.toISOString().slice(0, 10);
+}
+
+export function minuteOfDay(now: Date): number {
+ return now.getUTCHours() * 60 + now.getUTCMinutes();
+}
+
+// Each instance keeps a slot of its own, so they do not all report at midnight UTC.
+export function randomSendMinute(): number {
+ return Math.floor(Math.random() * MINUTES_PER_DAY);
+}
+
+export interface SendDecision {
+ day: string;
+ // Null when no pulse was ever accepted.
+ lastSentDay: string | null;
+ minuteOfDay: number;
+ sendMinute: number;
+}
+
+export function shouldSend(d: SendDecision): boolean {
+ if (d.lastSentDay === d.day) return false;
+ // The first pulse ignores the slot: an instance installed and removed within the
+ // hour would otherwise never be seen at all.
+ if (d.lastSentDay === null) return true;
+ return d.minuteOfDay >= d.sendMinute;
+}
diff --git a/apps/worker/src/telemetry.ts b/apps/worker/src/telemetry.ts
new file mode 100644
index 00000000..77a63fa9
--- /dev/null
+++ b/apps/worker/src/telemetry.ts
@@ -0,0 +1,218 @@
+import { existsSync } from 'node:fs';
+import { db, getOrCreateSetting, getSetting, setSetting } from '@repo/db';
+import { sql } from 'drizzle-orm';
+import { equalJitterBackoffMs } from './backoff';
+import { buildPulse, type InstanceCounts } from './telemetry-payload';
+import {
+ minuteOfDay,
+ randomSendMinute,
+ shouldSend,
+ utcDay,
+ MINUTES_PER_DAY,
+} from './telemetry-schedule';
+import pkg from '../../../package.json';
+
+// Sends one anonymous snapshot of this instance a day. TELEMETRY.md documents what
+// goes out and how to turn it off (TELEMETRY_DISABLED=1 / DO_NOT_TRACK=1).
+
+const ENDPOINT = 'https://telemetry.itsaplan.dev/v1/telemetry';
+const TIMEOUT_MS = 10_000;
+
+// Retried with a growing delay for this many attempts, then once an hour.
+const MAX_ATTEMPTS = 5;
+const RETRY_AFTER_MAX_MS = 60 * 60_000;
+
+// ~1min at the worker's 2s poll interval, matching the minute the slot is expressed in.
+export const TELEMETRY_CHECK_EVERY_TICKS = 30;
+
+const INSTANCE_ID_KEY = 'telemetry.instance_id';
+const LAST_SENT_KEY = 'telemetry.last_sent_day';
+const SEND_MINUTE_KEY = 'telemetry.send_minute';
+
+interface State {
+ instanceId: string;
+ sendMinute: number;
+ lastSentDay: string | null;
+}
+
+// Read once per process, then kept in memory. Replicas each hold their own copy and
+// each send; the collector keys rows on (instance_id, day), so that costs N requests
+// a day, not N rows.
+let state: State | null = null;
+
+// In memory only: a restart costs one extra attempt.
+let failures = 0;
+let retryAfterMs = 0;
+
+// Any value but '' and '0' opts out; compose passes an unset variable through as ''.
+function optedOut(value: string | undefined): boolean {
+ return value !== undefined && value !== '' && value !== '0';
+}
+
+function telemetryEnabled(): boolean {
+ return !optedOut(process.env.TELEMETRY_DISABLED) && !optedOut(process.env.DO_NOT_TRACK);
+}
+
+async function instanceId(): Promise<string> {
+ const stored = await getSetting<string>(INSTANCE_ID_KEY);
+ if (typeof stored === 'string' && stored.length > 0) return stored;
+ // Insert-if-absent: replicas racing on the first start settle on one id.
+ const id = await getOrCreateSetting(INSTANCE_ID_KEY, crypto.randomUUID());
+ // Printed once ever, so an operator who never reads the docs still finds out.
+ console.log(
+ '[telemetry] this instance now sends one anonymous snapshot a day. ' +
+ 'It carries no names, no content and no exact counts — see TELEMETRY.md. ' +
+ 'Turn it off with TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1.',
+ );
+ return id;
+}
+
+async function sendMinute(): Promise<number> {
+ const stored = await getSetting<number>(SEND_MINUTE_KEY);
+ if (typeof stored === 'number' && stored >= 0 && stored < MINUTES_PER_DAY) return stored;
+ return await getOrCreateSetting(SEND_MINUTE_KEY, randomSendMinute());
+}
+
+async function loadState(): Promise<State> {
+ return {
+ instanceId: await instanceId(),
+ sendMinute: await sendMinute(),
+ lastSentDay: (await getSetting<string>(LAST_SENT_KEY)) ?? null,
+ };
+}
+
+// ::int because postgres-js returns bigint as a string, which would bucket as NaN.
+async function readCounts(): Promise<InstanceCounts> {
+ const rows = await db.execute(sql`
+ SELECT
+ (SELECT count(*)::int FROM "user") AS "users",
+ (SELECT count(DISTINCT user_id)::int FROM "session"
+ WHERE created_at > now() - interval '30 days') AS "activeUsers30d",
+ (SELECT count(*)::int FROM project) AS "projects",
+ (SELECT count(*)::int FROM issue) AS "issues",
+ (SELECT count(*)::int FROM issue
+ WHERE created_at > now() - interval '30 days') AS "issuesCreated30d",
+ (SELECT count(*)::int FROM ai_agent) AS "agents",
+ (SELECT count(*)::int FROM agent_run
+ WHERE created_at > now() - interval '30 days') AS "agentRuns30d",
+ (SELECT count(*)::int FROM agent_run
+ WHERE created_at > now() - interval '30 days'
+ AND status = 'failed') AS "agentRunsFailed30d",
+ (SELECT count(*)::int FROM webhook_delivery
+ WHERE created_at > now() - interval '30 days') AS "webhookDeliveries30d",
+ (SELECT count(*)::int FROM webhook_delivery
+ WHERE created_at > now() - interval '30 days'
+ AND status = 'failed') AS "webhookDeliveriesFailed30d",
+ EXISTS(SELECT 1 FROM initiative) AS "hasInitiatives",
+ EXISTS(SELECT 1 FROM note_board) AS "hasNoteBoards",
+ EXISTS(SELECT 1 FROM project_dashboard) AS "hasDashboards",
+ EXISTS(SELECT 1 FROM project_view) AS "hasCustomViews",
+ EXISTS(SELECT 1 FROM custom_field) AS "hasCustomFields",
+ EXISTS(SELECT 1 FROM label_group) AS "hasLabelGroups",
+ EXISTS(SELECT 1 FROM project_action) AS "hasProjectActions",
+ EXISTS(SELECT 1 FROM issue_attachment) AS "hasAttachments",
+ EXISTS(SELECT 1 FROM agent_schedule) AS "hasAgentSchedules",
+ EXISTS(SELECT 1 FROM webhook) AS "hasWebhooks",
+ EXISTS(SELECT 1 FROM apikey) AS "hasApiKeys",
+ EXISTS(SELECT 1 FROM project WHERE mcp_enabled) AS "hasMcpProject",
+ -- The app_secret row appears on any save, so read the plaintext mirror of the
+ -- config: same conditions as hasEmailProvider, isGoogleUsable, isInstanceBotUsable.
+ EXISTS(SELECT 1 FROM app_secret WHERE key = 'auth.email'
+ AND (((redacted->'smtp'->>'enabled')::boolean AND redacted->'smtp'->>'host' <> '')
+ OR ((redacted->'resend'->>'enabled')::boolean
+ AND (redacted->'resend'->>'hasApiKey')::boolean))) AS "hasEmail",
+ EXISTS(SELECT 1 FROM app_secret WHERE key = 'auth.google'
+ AND (redacted->>'enabled')::boolean
+ AND redacted->>'clientId' <> ''
+ AND (redacted->>'hasClientSecret')::boolean) AS "hasGoogleOauth",
+ EXISTS(SELECT 1 FROM app_secret WHERE key = 'telegram.bot'
+ AND (redacted->>'enabled')::boolean
+ AND (redacted->>'hasBotToken')::boolean) AS "hasTelegramBot",
+ EXISTS(SELECT 1 FROM integration_credential) AS "hasProjectIntegrations"
+ `);
+ return (rows as unknown as InstanceCounts[])[0];
+}
+
+async function postgresMajor(): Promise<number | null> {
+ const rows = await db.execute(
+ sql`SELECT (current_setting('server_version_num')::int / 10000) AS "major"`,
+ );
+ const major = (rows as unknown as { major: number }[])[0]?.major;
+ return typeof major === 'number' ? major : null;
+}
+
+// The first migration timestamp is the install date: nothing has to be recorded for
+// it, and unlike the first pulse it holds for an instance that ran with telemetry off.
+async function installedDay(): Promise<string | null> {
+ try {
+ const rows = await db.execute(sql`
+ SELECT to_char(to_timestamp(min(created_at) / 1000) AT TIME ZONE 'UTC', 'YYYY-MM-DD')
+ AS "day"
+ FROM drizzle.__drizzle_migrations
+ `);
+ return (rows as unknown as { day: string | null }[])[0]?.day ?? null;
+ } catch (error) {
+ console.error('[telemetry] install date unreadable:', error);
+ return null;
+ }
+}
+
+// The stored day is advanced only after the collector accepted the body, so a failed
+// send is retried rather than lost for the day.
+export async function processTelemetry(): Promise<void> {
+ if (!telemetryEnabled()) return;
+
+ const now = new Date();
+ if (now.getTime() < retryAfterMs) return;
+
+ state ??= await loadState();
+
+ const day = utcDay(now);
+ const due = shouldSend({
+ day,
+ lastSentDay: state.lastSentDay,
+ minuteOfDay: minuteOfDay(now),
+ sendMinute: state.sendMinute,
+ });
+ if (!due) return;
+
+ const pulse = buildPulse({
+ instanceId: state.instanceId,
+ day,
+ installedDay: await installedDay(),
+ version: pkg.version,
+ bunVersion: Bun.version,
+ docker: existsSync('/.dockerenv'),
+ platform: `${process.platform}/${process.arch}`,
+ postgresMajor: await postgresMajor(),
+ counts: await readCounts(),
+ });
+
+ const body = JSON.stringify(pulse);
+ if (process.env.TELEMETRY_DEBUG === '1') {
+ console.log('[telemetry] sending:', body);
+ }
+
+ try {
+ const response = await fetch(ENDPOINT, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body,
+ signal: AbortSignal.timeout(TIMEOUT_MS),
+ });
+ if (!response.ok) {
+ throw new Error(`collector returned ${response.status}`);
+ }
+ } catch (error) {
+ failures++;
+ retryAfterMs =
+ now.getTime() +
+ (failures >= MAX_ATTEMPTS ? RETRY_AFTER_MAX_MS : equalJitterBackoffMs(failures));
+ throw error;
+ }
+
+ failures = 0;
+ retryAfterMs = 0;
+ state.lastSentDay = day;
+ await setSetting(LAST_SENT_KEY, day);
+}
diff --git a/apps/worker/src/worker.ts b/apps/worker/src/worker.ts
index d422d89f..e587edca 100644
--- a/apps/worker/src/worker.ts
+++ b/apps/worker/src/worker.ts
@@ -3,6 +3,7 @@ import { deliver } from './delivery';
import { processNotificationDeliveries } from './notification-delivery';
import { equalJitterBackoffMs } from './backoff';
import { startPollLoop, type WorkerHandle } from './poll-loop';
+import { TELEMETRY_CHECK_EVERY_TICKS, processTelemetry } from './telemetry';
import {
type ClaimedDelivery,
claimDueDeliveries,
@@ -16,14 +17,16 @@ import {
let ticksSinceCleanup = 0;
let ticksSinceAutoArchive = 0;
+// Starts due, so an install is visible even if the instance is removed minutes later.
+let ticksSinceTelemetry = TELEMETRY_CHECK_EVERY_TICKS;
export function startWorker(): WorkerHandle {
return startPollLoop('worker', tick, () => workerConfig().pollIntervalMs);
}
// One poll: claim a batch of due deliveries, send them concurrently, record each
-// outcome, then run the delivery cleanup and the auto-archive sweep on their own
-// tick intervals.
+// outcome, then run the delivery cleanup, the auto-archive sweep and the telemetry
+// check on their own tick intervals.
async function tick(): Promise<void> {
const cfg = workerConfig();
const claimed = await claimDueDeliveries();
@@ -41,6 +44,15 @@ async function tick(): Promise<void> {
const archived = await archiveStaleIssues();
if (archived > 0) console.log(`[worker] auto-archived ${archived} stale issues`);
}
+ if (++ticksSinceTelemetry >= TELEMETRY_CHECK_EVERY_TICKS) {
+ ticksSinceTelemetry = 0;
+ // An unreachable collector must not read as a failed tick.
+ try {
+ await processTelemetry();
+ } catch (error) {
+ console.error('[worker] telemetry send failed:', error);
+ }
+ }
}
async function processDelivery(d: ClaimedDelivery): Promise<void> {
diff --git a/docker-compose.coolify.yml b/docker-compose.coolify.yml
index 6203a667..e1c5d5c0 100644
--- a/docker-compose.coolify.yml
+++ b/docker-compose.coolify.yml
@@ -110,6 +110,11 @@ services:
DATABASE_URL: postgres://${POSTGRES_USER:-itsaplan}:${SERVICE_PASSWORD_POSTGRES}@postgres:5432/${POSTGRES_DB:-itsaplan}
SERVICE_URL_API: ${SERVICE_URL_API:-http://api:3000}
WORKER_INTERNAL_TOKEN: ${SERVICE_PASSWORD_64_WORKER}
+ # Anonymous telemetry (TELEMETRY.md). Either variable, set to anything but 0,
+ # turns it off.
+ TELEMETRY_DISABLED: ${TELEMETRY_DISABLED:-}
+ DO_NOT_TRACK: ${DO_NOT_TRACK:-}
+ TELEMETRY_DEBUG: ${TELEMETRY_DEBUG:-}
# Optional tuning — defaults live in apps/worker/src/config.ts:
# WEBHOOK_POLL_INTERVAL_MS, WEBHOOK_BATCH_SIZE, WEBHOOK_TIMEOUT_MS,
# WEBHOOK_MAX_ATTEMPTS, WEBHOOK_DISABLE_THRESHOLD, WEBHOOK_LEASE_SECONDS,
diff --git a/docker-compose.yml b/docker-compose.yml
index a8fefbc1..ef7bd9b4 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -118,6 +118,11 @@ services:
DATABASE_URL: postgres://${POSTGRES_USER:-itsaplan}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-itsaplan}
SERVICE_URL_API: http://api:3000
WORKER_INTERNAL_TOKEN: ${WORKER_INTERNAL_TOKEN}
+ # Anonymous telemetry (TELEMETRY.md). Either variable, set to anything but 0,
+ # turns it off.
+ TELEMETRY_DISABLED: ${TELEMETRY_DISABLED:-}
+ DO_NOT_TRACK: ${DO_NOT_TRACK:-}
+ TELEMETRY_DEBUG: ${TELEMETRY_DEBUG:-}
# Optional tuning lives in apps/worker/src/config.ts.
# Telegram bot: long polling for the instance bot, completing the account links
diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts
index b1639e8b..776e1951 100644
--- a/packages/db/src/index.ts
+++ b/packages/db/src/index.ts
@@ -1,3 +1,3 @@
export { db } from './client';
export * from './schema';
-export { getSetting, setSetting } from './settings';
+export { getSetting, getOrCreateSetting, setSetting } from './settings';
diff --git a/packages/db/src/settings.ts b/packages/db/src/settings.ts
index ee086a47..0c24c410 100644
--- a/packages/db/src/settings.ts
+++ b/packages/db/src/settings.ts
@@ -15,6 +15,18 @@ export async function getSetting<T>(key: string): Promise<T | null> {
return rows[0] ? (rows[0].value as T) : null;
}
+// Stores `value` only when the key is free, and returns what the key holds afterwards.
+// The conflict branch rewrites the row with its own value so RETURNING yields the
+// stored one, which makes processes racing on a first write settle on the same result.
+export async function getOrCreateSetting<T>(key: string, value: T): Promise<T> {
+ const rows = await db
+ .insert(appSetting)
+ .values({ key, value })
+ .onConflictDoUpdate({ target: appSetting.key, set: { value: sql`${appSetting.value}` } })
+ .returning({ value: appSetting.value });
+ return rows[0]!.value as T;
+}
+
export async function setSetting(key: string, value: unknown): Promise<void> {
await db
.insert(appSetting)