⭐️⭐️⭐️ 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.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
feat: send an anonymous daily instance snapshot (#35)
Croffbe68f4aa64d3
diff --git a/.env.example b/.env.exampleindex 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.mdnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.ymlindex 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.ymlindex 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:3000WORKER_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 linksdiff --git a/packages/db/src/index.ts b/packages/db/src/index.tsindex 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.tsindex 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)