[chamikaJ]

Summary by CodeRabbit

• New Features
  • Self-hosted installations now send periodic heartbeats by default, including an installation identifier and product version. Set WORKLENZ_TELEMETRY_ENABLED=false to disable them. Cloud deployments do not send heartbeats.
• Documentation
  • Added information about the heartbeat’s reported data, destination, timing, retention, deletion requests, and estimated dashboard counts. Disabling heartbeats does not remove data already received.

[coderabbitai]

No actionable comments were generated in the recent review.

Walkthrough

The backend adds a self-hosted installation heartbeat, enabled by default and controlled by an environment setting. It stores attempt state, schedules sends after server startup, and posts an installation ID and package version. The change also adds configuration and telemetry documentation, plus tests.

Changes: Self-hosted heartbeat

Layer / File(s)	Summary
Telemetry configuration and state .env.example, worklenz-backend/.env.template, worklenz-backend/database/pg-migrations/*, README.md, TELEMETRY.md	Both environment templates set telemetry to true by default and describe the opt-out. The migration creates a singleton state table. The documentation describes the configuration, payload, schedule, failure handling, retention, deletion, and reporting limitations.
Heartbeat scheduling and delivery worklenz-backend/src/services/telemetry-heartbeat.ts, worklenz-backend/src/bin/www.ts, worklenz-backend/src/tests/telemetry-heartbeat.spec.ts	The sender checks the telemetry setting and deployment mode, reserves an attempt when eligible, and posts the installation ID and package version. Startup schedules an initial randomized send and hourly sends. Tests cover configuration gates, reservation, request options, and network failure.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant ServerStartup
  participant startTelemetryHeartbeat
  participant sendTelemetryHeartbeat
  participant TelemetryStateDB
  participant TelemetryEndpoint
  ServerStartup->>startTelemetryHeartbeat: Start after server begins listening
  startTelemetryHeartbeat->>sendTelemetryHeartbeat: Invoke after random delay and hourly
  sendTelemetryHeartbeat->>TelemetryStateDB: Reserve attempt when eligible
  TelemetryStateDB-->>sendTelemetryHeartbeat: Return installation ID or no row
  sendTelemetryHeartbeat->>TelemetryEndpoint: Post installation ID and package version

Loading

Possibly related issues

• Worklenz/worklenz issue 754 — Adds an opt-out for the self-hosted heartbeat. The changes do not remove the existing third-party trackers described by the issue.

Merge Risk: Minimal · up to 18195

This adds a self-hosted installation heartbeat that is on by default and can be disabled with WORKLENZ_TELEMETRY_ENABLED=false. The opt-out is documented and reaches the backend in the Docker setup. No merge-blocking issue was found. The PR title says "opt-in" while the behavior is opt-out, so the title or the default should be reconciled.

Pre-merge checks: 4

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title "feat: add opt-in installation telemetry" matches the main change. The changeset adds a self-hosted installation heartbeat service, a migration, tests, and docs. However, the title says "opt…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title "feat: add opt-in installation telemetry" matches the main change. The changeset adds a self-hosted installation heartbeat service, a migration, tests, and docs. However, the title says "opt-in", while the changes enable telemetry by default unless WORKLENZ_TELEMETRY_ENABLED=false is set. The title is therefore related to the main change but misstates its default behavior. The title is concise, specific, and follows conventional commit style.

Finishing Touches

Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

Recent review info

Run configuration

• Source mode: Auto
• Repository: Worklenz/worklenz
• Branch: main
• File: .coderabbit.yaml
• Commit: c0115ed
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: c259c954-3f39-4297-ad88-7fbbfc040a7f

Commits

Reviewing files that changed from the base of the PR and between 8e83880 and 1819598.

Files selected for processing: 6

• .env.example
• README.md
• TELEMETRY.md
• worklenz-backend/.env.template
• worklenz-backend/src/services/telemetry-heartbeat.ts
• worklenz-backend/src/tests/telemetry-heartbeat.spec.ts

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.