Skip to content

Modern Docker Management, Designed for Everyone

fix: analytics job managed interally without a fixed cron schedule (#2028)

Kyle Mendell045303c57bc5
diff --git a/backend/internal/bootstrap/jobs_bootstrap.go b/backend/internal/bootstrap/jobs_bootstrap.go
index f426270bd..53f6ae030 100644
--- a/backend/internal/bootstrap/jobs_bootstrap.go
+++ b/backend/internal/bootstrap/jobs_bootstrap.go
@@ -23,7 +23,7 @@ func registerJobs(appCtx context.Context, newScheduler *pkg_scheduler.JobSchedul
newScheduler.RegisterJob(environmentHealthJob)
}
- analyticsJob := pkg_scheduler.NewAnalyticsJob(appServices.Settings, nil, appConfig)
+ analyticsJob := pkg_scheduler.NewAnalyticsJob(appServices.Settings, appServices.KV, nil, appConfig)
newScheduler.RegisterJob(analyticsJob)
// Send initial heartbeat on startup without blocking bootstrap.
go analyticsJob.Run(appCtx)
@@ -56,7 +56,6 @@ func registerJobs(appCtx context.Context, newScheduler *pkg_scheduler.JobSchedul
imagePollingJob,
autoUpdateJob,
environmentHealthJob,
- analyticsJob,
eventCleanupJob,
scheduledPruneJob,
gitOpsSyncJob,
@@ -74,7 +73,6 @@ func setupJobScheduleCallbacks(
imagePollingJob *pkg_scheduler.ImagePollingJob,
autoUpdateJob *pkg_scheduler.AutoUpdateJob,
environmentHealthJob *pkg_scheduler.EnvironmentHealthJob,
- analyticsJob *pkg_scheduler.AnalyticsJob,
eventCleanupJob *pkg_scheduler.EventCleanupJob,
scheduledPruneJob *pkg_scheduler.ScheduledPruneJob,
gitOpsSyncJob *pkg_scheduler.GitOpsSyncJob,
@@ -96,7 +94,6 @@ func setupJobScheduleCallbacks(
imagePollingJob,
autoUpdateJob,
environmentHealthJob,
- analyticsJob,
eventCleanupJob,
scheduledPruneJob,
gitOpsSyncJob,
@@ -115,7 +112,6 @@ func handleJobScheduleChangeInternal(
imagePollingJob *pkg_scheduler.ImagePollingJob,
autoUpdateJob *pkg_scheduler.AutoUpdateJob,
environmentHealthJob *pkg_scheduler.EnvironmentHealthJob,
- analyticsJob *pkg_scheduler.AnalyticsJob,
eventCleanupJob *pkg_scheduler.EventCleanupJob,
scheduledPruneJob *pkg_scheduler.ScheduledPruneJob,
gitOpsSyncJob *pkg_scheduler.GitOpsSyncJob,
@@ -138,10 +134,6 @@ func handleJobScheduleChangeInternal(
if err := newScheduler.RescheduleJob(ctx, environmentHealthJob); err != nil {
slog.WarnContext(ctx, "Failed to reschedule environment-health job", "error", err)
}
- case "analyticsHeartbeatInterval":
- if err := newScheduler.RescheduleJob(ctx, analyticsJob); err != nil {
- slog.WarnContext(ctx, "Failed to reschedule analytics heartbeat job", "error", err)
- }
case "eventCleanupInterval":
if err := newScheduler.RescheduleJob(ctx, eventCleanupJob); err != nil {
slog.WarnContext(ctx, "Failed to reschedule event cleanup job", "error", err)
diff --git a/backend/internal/bootstrap/services_bootstrap.go b/backend/internal/bootstrap/services_bootstrap.go
index 0ccaca7a6..a426ce004 100644
--- a/backend/internal/bootstrap/services_bootstrap.go
+++ b/backend/internal/bootstrap/services_bootstrap.go
@@ -17,6 +17,7 @@ type Services struct {
Project *services.ProjectService
Environment *services.EnvironmentService
Settings *services.SettingsService
+ KV *services.KVService
JobSchedule *services.JobService
SettingsSearch *services.SettingsSearchService
CustomizeSearch *services.CustomizeSearchService
@@ -55,6 +56,7 @@ func initializeServices(ctx context.Context, db *database.DB, cfg *config.Config
if err != nil {
return nil, nil, fmt.Errorf("failed to settings service: %w", err)
}
+ svcs.KV = services.NewKVService(db)
svcs.JobSchedule = services.NewJobService(db, svcs.Settings, cfg)
svcs.SettingsSearch = services.NewSettingsSearchService()
svcs.CustomizeSearch = services.NewCustomizeSearchService()
diff --git a/backend/internal/models/kv.go b/backend/internal/models/kv.go
new file mode 100644
index 000000000..dbc41d5a3
--- /dev/null
+++ b/backend/internal/models/kv.go
@@ -0,0 +1,15 @@
+package models
+
+import "time"
+
+// KVEntry stores lightweight application state as arbitrary key/value pairs.
+type KVEntry struct {
+ Key string `gorm:"column:key;primaryKey"`
+ Value string `gorm:"column:value"`
+ CreatedAt time.Time `gorm:"column:created_at;autoCreateTime"`
+ UpdatedAt *time.Time `gorm:"column:updated_at;autoUpdateTime"`
+}
+
+func (KVEntry) TableName() string {
+ return "kv"
+}
diff --git a/backend/internal/models/settings.go b/backend/internal/models/settings.go
index b324ca228..e98522fb1 100644
--- a/backend/internal/models/settings.go
+++ b/backend/internal/models/settings.go
@@ -60,7 +60,6 @@ type Settings struct {
PollingEnabled SettingVariable `key:"pollingEnabled" meta:"label=Enable Polling;type=boolean;keywords=polling,check,monitor,watch,scan,detection,automatic;category=internal;description=Enable automatic checking for image updates"`
PollingInterval SettingVariable `key:"pollingInterval" meta:"label=Polling Interval;type=cron;keywords=interval,frequency,schedule,time,minutes,period,delay;category=internal;description=How often to check for image updates (cron expression)"`
EventCleanupInterval SettingVariable `key:"eventCleanupInterval" meta:"label=Event Cleanup Interval;type=cron;keywords=events,cleanup,retention,interval,frequency,schedule,history,logs,jobs;description=How often to delete old events (cron expression)"`
- AnalyticsHeartbeatInterval SettingVariable `key:"analyticsHeartbeatInterval" meta:"label=Analytics Heartbeat Interval;type=cron;keywords=analytics,heartbeat,interval,frequency,schedule,telemetry,jobs;description=How often to send the anonymous analytics heartbeat (cron expression)"`
AutoInjectEnv SettingVariable `key:"autoInjectEnv" meta:"label=Auto Inject Env Variables;type=boolean;keywords=auto,inject,env,environment,variables,interpolation;category=internal;description=Automatically inject project .env variables into all containers (default: false)"`
PruneMode SettingVariable `key:"dockerPruneMode" meta:"label=Docker Prune Action;type=select;keywords=prune,cleanup,clean,remove,delete,unused,dangling,space,disk;category=internal;description=Configure how unused Docker images are cleaned up"`
DefaultDeployPullPolicy SettingVariable `key:"defaultDeployPullPolicy" meta:"label=Default Deploy Pull Policy;type=select;keywords=deploy,pull,policy,compose,up,missing,always;category=internal;description=Default image pull policy when deploying projects"`
diff --git a/backend/internal/services/job_service.go b/backend/internal/services/job_service.go
index 78fad813e..7eebe21d4 100644
--- a/backend/internal/services/job_service.go
+++ b/backend/internal/services/job_service.go
@@ -54,15 +54,14 @@ func (s *JobService) SetScheduler(scheduler JobRunner) {
func (s *JobService) GetJobSchedules(ctx context.Context) jobschedule.Config {
// Use SettingsService cache for fast reads.
return jobschedule.Config{
- EnvironmentHealthInterval: s.settings.GetStringSetting(ctx, "environmentHealthInterval", "0 */2 * * * *"),
- EventCleanupInterval: s.settings.GetStringSetting(ctx, "eventCleanupInterval", "0 0 */6 * * *"),
- AnalyticsHeartbeatInterval: s.settings.GetStringSetting(ctx, "analyticsHeartbeatInterval", "0 0 0 * * *"),
- AutoUpdateInterval: s.settings.GetStringSetting(ctx, "autoUpdateInterval", "0 0 0 * * *"),
- PollingInterval: s.settings.GetStringSetting(ctx, "pollingInterval", "0 */15 * * * *"),
- ScheduledPruneInterval: s.settings.GetStringSetting(ctx, "scheduledPruneInterval", "0 0 0 * * *"),
- GitopsSyncInterval: s.settings.GetStringSetting(ctx, "gitopsSyncInterval", "0 */1 * * * *"),
- VulnerabilityScanInterval: s.settings.GetStringSetting(ctx, "vulnerabilityScanInterval", "0 0 0 * * *"),
- AutoHealInterval: s.settings.GetStringSetting(ctx, "autoHealInterval", "*/30 * * * * *"),
+ EnvironmentHealthInterval: s.settings.GetStringSetting(ctx, "environmentHealthInterval", "0 */2 * * * *"),
+ EventCleanupInterval: s.settings.GetStringSetting(ctx, "eventCleanupInterval", "0 0 */6 * * *"),
+ AutoUpdateInterval: s.settings.GetStringSetting(ctx, "autoUpdateInterval", "0 0 0 * * *"),
+ PollingInterval: s.settings.GetStringSetting(ctx, "pollingInterval", "0 */15 * * * *"),
+ ScheduledPruneInterval: s.settings.GetStringSetting(ctx, "scheduledPruneInterval", "0 0 0 * * *"),
+ GitopsSyncInterval: s.settings.GetStringSetting(ctx, "gitopsSyncInterval", "0 */1 * * * *"),
+ VulnerabilityScanInterval: s.settings.GetStringSetting(ctx, "vulnerabilityScanInterval", "0 0 0 * * *"),
+ AutoHealInterval: s.settings.GetStringSetting(ctx, "autoHealInterval", "*/30 * * * * *"),
}
}
@@ -83,7 +82,6 @@ func (s *JobService) UpdateJobSchedules(ctx context.Context, updates jobschedule
}{
{key: "environmentHealthInterval", current: current.EnvironmentHealthInterval, update: updates.EnvironmentHealthInterval},
{key: "eventCleanupInterval", current: current.EventCleanupInterval, update: updates.EventCleanupInterval},
- {key: "analyticsHeartbeatInterval", current: current.AnalyticsHeartbeatInterval, update: updates.AnalyticsHeartbeatInterval},
{key: "autoUpdateInterval", current: current.AutoUpdateInterval, update: updates.AutoUpdateInterval},
{key: "pollingInterval", current: current.PollingInterval, update: updates.PollingInterval},
{key: "scheduledPruneInterval", current: current.ScheduledPruneInterval, update: updates.ScheduledPruneInterval},
@@ -217,20 +215,23 @@ func (s *JobService) getJobScheduleInternal(ctx context.Context, meta meta.JobMe
return "continuous"
}
+ if meta.ID == "analytics-heartbeat" {
+ return "automatic (checked hourly; sent once per 24h)"
+ }
+
if meta.SettingsKey == "" {
return ""
}
defaultSchedules := map[string]string{
- "environmentHealthInterval": "0 */2 * * * *",
- "eventCleanupInterval": "0 0 */6 * * *",
- "analyticsHeartbeatInterval": "0 0 0 * * *",
- "autoUpdateInterval": "0 0 0 * * *",
- "pollingInterval": "0 */15 * * * *",
- "scheduledPruneInterval": "0 0 0 * * *",
- "gitopsSyncInterval": "0 */1 * * * *",
- "vulnerabilityScanInterval": "0 0 0 * * *",
- "autoHealInterval": "*/30 * * * * *",
+ "environmentHealthInterval": "0 */2 * * * *",
+ "eventCleanupInterval": "0 0 */6 * * *",
+ "autoUpdateInterval": "0 0 0 * * *",
+ "pollingInterval": "0 */15 * * * *",
+ "scheduledPruneInterval": "0 0 0 * * *",
+ "gitopsSyncInterval": "0 */1 * * * *",
+ "vulnerabilityScanInterval": "0 0 0 * * *",
+ "autoHealInterval": "*/30 * * * * *",
}
defaultSchedule := defaultSchedules[meta.SettingsKey]
diff --git a/backend/internal/services/job_service_test.go b/backend/internal/services/job_service_test.go
index a12e34284..11bc5bd88 100644
--- a/backend/internal/services/job_service_test.go
+++ b/backend/internal/services/job_service_test.go
@@ -5,6 +5,7 @@ import (
"testing"
"github.com/getarcaneapp/arcane/backend/internal/config"
+ "github.com/getarcaneapp/arcane/types/jobschedule"
"github.com/stretchr/testify/require"
)
@@ -20,3 +21,35 @@ func TestJobService_GetJobSchedules_DefaultGitOpsInterval(t *testing.T) {
require.Equal(t, "0 */1 * * * *", cfg.GitopsSyncInterval)
}
+
+func TestJobService_ListJobs_AnalyticsHeartbeatIsManagedInternally(t *testing.T) {
+ ctx := context.Background()
+ db := setupSettingsTestDB(t)
+
+ settingsSvc, err := NewSettingsService(ctx, db)
+ require.NoError(t, err)
+
+ jobSvc := NewJobService(db, settingsSvc, &config.Config{})
+ jobs, err := jobSvc.ListJobs(ctx)
+ require.NoError(t, err)
+
+ analyticsJob := findJobStatusByIDInternal(t, jobs.Jobs, "analytics-heartbeat")
+ require.Equal(t, "automatic (checked hourly; sent once per 24h)", analyticsJob.Schedule)
+ require.Empty(t, analyticsJob.SettingsKey)
+ require.Nil(t, analyticsJob.NextRun)
+ require.True(t, analyticsJob.CanRunManually)
+ require.False(t, analyticsJob.IsContinuous)
+}
+
+func findJobStatusByIDInternal(t *testing.T, jobs []jobschedule.JobStatus, id string) jobschedule.JobStatus {
+ t.Helper()
+
+ for _, job := range jobs {
+ if job.ID == id {
+ return job
+ }
+ }
+
+ t.Fatalf("job %q not found", id)
+ return jobschedule.JobStatus{}
+}
diff --git a/backend/internal/services/kv_service.go b/backend/internal/services/kv_service.go
new file mode 100644
index 000000000..3962be1cc
--- /dev/null
+++ b/backend/internal/services/kv_service.go
@@ -0,0 +1,49 @@
+package services
+
+import (
+ "context"
+ "errors"
+ "fmt"
+
+ "github.com/getarcaneapp/arcane/backend/internal/database"
+ "github.com/getarcaneapp/arcane/backend/internal/models"
+ "gorm.io/gorm"
+ "gorm.io/gorm/clause"
+)
+
+// KVService persists lightweight application state in the kv table.
+type KVService struct {
+ db *database.DB
+}
+
+func NewKVService(db *database.DB) *KVService {
+ return &KVService{db: db}
+}
+
+func (s *KVService) Get(ctx context.Context, key string) (string, bool, error) {
+ var entry models.KVEntry
+ err := s.db.WithContext(ctx).Where("key = ?", key).First(&entry).Error
+ if errors.Is(err, gorm.ErrRecordNotFound) {
+ return "", false, nil
+ }
+ if err != nil {
+ return "", false, fmt.Errorf("failed to load kv entry %q: %w", key, err)
+ }
+
+ return entry.Value, true, nil
+}
+
+func (s *KVService) Set(ctx context.Context, key, value string) error {
+ entry := models.KVEntry{Key: key, Value: value}
+ err := s.db.WithContext(ctx).
+ Clauses(clause.OnConflict{
+ Columns: []clause.Column{{Name: "key"}},
+ DoUpdates: clause.AssignmentColumns([]string{"value", "updated_at"}),
+ }).
+ Create(&entry).Error
+ if err != nil {
+ return fmt.Errorf("failed to upsert kv entry %q: %w", key, err)
+ }
+
+ return nil
+}
diff --git a/backend/internal/services/kv_service_test.go b/backend/internal/services/kv_service_test.go
new file mode 100644
index 000000000..64687d24f
--- /dev/null
+++ b/backend/internal/services/kv_service_test.go
@@ -0,0 +1,47 @@
+package services
+
+import (
+ "context"
+ "testing"
+
+ "github.com/getarcaneapp/arcane/backend/internal/models"
+ "github.com/stretchr/testify/require"
+)
+
+func setupKVServiceInternal(t *testing.T) *KVService {
+ t.Helper()
+
+ db := setupSettingsTestDB(t)
+ require.NoError(t, db.AutoMigrate(&models.KVEntry{}))
+
+ return NewKVService(db)
+}
+
+func TestKVService_Get_MissingKey(t *testing.T) {
+ ctx := context.Background()
+ svc := setupKVServiceInternal(t)
+
+ value, ok, err := svc.Get(ctx, "missing")
+ require.NoError(t, err)
+ require.False(t, ok)
+ require.Empty(t, value)
+}
+
+func TestKVService_Set_UpsertsValue(t *testing.T) {
+ ctx := context.Background()
+ svc := setupKVServiceInternal(t)
+
+ require.NoError(t, svc.Set(ctx, "analytics.heartbeat.last_attempt_at", "2026-03-10T00:00:00Z"))
+
+ value, ok, err := svc.Get(ctx, "analytics.heartbeat.last_attempt_at")
+ require.NoError(t, err)
+ require.True(t, ok)
+ require.Equal(t, "2026-03-10T00:00:00Z", value)
+
+ require.NoError(t, svc.Set(ctx, "analytics.heartbeat.last_attempt_at", "2026-03-11T00:00:00Z"))
+
+ updatedValue, updatedOK, err := svc.Get(ctx, "analytics.heartbeat.last_attempt_at")
+ require.NoError(t, err)
+ require.True(t, updatedOK)
+ require.Equal(t, "2026-03-11T00:00:00Z", updatedValue)
+}
diff --git a/backend/internal/services/settings_service.go b/backend/internal/services/settings_service.go
index 6123bd0a6..9a59daecf 100644
--- a/backend/internal/services/settings_service.go
+++ b/backend/internal/services/settings_service.go
@@ -94,7 +94,6 @@ func (s *SettingsService) getDefaultSettings() *models.Settings {
PollingEnabled: models.SettingVariable{Value: "true"},
PollingInterval: models.SettingVariable{Value: "0 0 * * * *"},
EventCleanupInterval: models.SettingVariable{Value: "0 0 */6 * * *"},
- AnalyticsHeartbeatInterval: models.SettingVariable{Value: "0 0 0 * * *"},
AutoInjectEnv: models.SettingVariable{Value: "false"},
PruneMode: models.SettingVariable{Value: "dangling"},
DefaultDeployPullPolicy: models.SettingVariable{Value: "missing"},
diff --git a/backend/internal/utils/bootstrap_util.go b/backend/internal/utils/bootstrap_util.go
index 304a57025..cd1e78a4e 100644
--- a/backend/internal/utils/bootstrap_util.go
+++ b/backend/internal/utils/bootstrap_util.go
@@ -126,7 +126,6 @@ func MigrateSchedulerCronValues(
{key: "scheduledPruneInterval", defaultUnit: time.Minute},
{key: "environmentHealthInterval", defaultUnit: time.Minute},
{key: "eventCleanupInterval", defaultUnit: time.Minute},
- {key: "analyticsHeartbeatInterval", defaultUnit: time.Minute},
}
changed := false
diff --git a/backend/pkg/libarcane/settings.go b/backend/pkg/libarcane/settings.go
index f6815f687..0b5368c44 100644
--- a/backend/pkg/libarcane/settings.go
+++ b/backend/pkg/libarcane/settings.go
@@ -38,7 +38,6 @@ var cronSettingKeys = []string{
"pollingInterval",
"environmentHealthInterval",
"eventCleanupInterval",
- "analyticsHeartbeatInterval",
"vulnerabilityScanInterval",
}
diff --git a/backend/pkg/scheduler/analytics_job.go b/backend/pkg/scheduler/analytics_job.go
index 5fb73fcc3..12b0a2f60 100644
--- a/backend/pkg/scheduler/analytics_job.go
+++ b/backend/pkg/scheduler/analytics_job.go
@@ -8,8 +8,8 @@ import (
"io"
"log/slog"
"net/http"
- "strconv"
"strings"
+ "sync"
"time"
backoff "github.com/cenkalti/backoff/v5"
@@ -18,20 +18,27 @@ import (
)
const (
- AnalyticsJobName = "analytics-heartbeat"
- defaultHeartbeatEndpoint = "https://checkin.getarcane.app/heartbeat"
- devHeartbeatEndpoint = "http://localhost:8080/heartbeat"
+ AnalyticsJobName = "analytics-heartbeat"
+ defaultHeartbeatEndpoint = "https://checkin.getarcane.app/heartbeat"
+ devHeartbeatEndpoint = "http://localhost:8080/heartbeat"
+ analyticsHeartbeatLastAttemptKey = "analytics.heartbeat.last_attempt_at"
+ analyticsHeartbeatDedupeWindow = 24 * time.Hour
+ analyticsHeartbeatCheckSchedule = "0 0 * * * *"
)
type AnalyticsJob struct {
settingsService *services.SettingsService
+ kvService *services.KVService
httpClient *http.Client
heartbeatURL string
cfg *config.Config
+ runMu sync.Mutex
+ now func() time.Time
}
func NewAnalyticsJob(
settingsService *services.SettingsService,
+ kvService *services.KVService,
httpClient *http.Client,
cfg *config.Config,
) *AnalyticsJob {
@@ -44,9 +51,11 @@ func NewAnalyticsJob(
}
return &AnalyticsJob{
settingsService: settingsService,
+ kvService: kvService,
httpClient: httpClient,
heartbeatURL: heartbeatURL,
cfg: cfg,
+ now: time.Now,
}
}
@@ -54,27 +63,8 @@ func (j *AnalyticsJob) Name() string {
return AnalyticsJobName
}
-func (j *AnalyticsJob) Schedule(ctx context.Context) string {
- s := j.settingsService.GetStringSetting(ctx, "analyticsHeartbeatInterval", "0 0 0 * * *")
- if s == "" {
- return "0 0 0 * * *"
- }
-
- // Handle legacy straight int if it somehow didn't get migrated
- if i, err := strconv.Atoi(s); err == nil {
- if i <= 0 {
- i = 1440
- }
- if i%1440 == 0 {
- return fmt.Sprintf("0 0 0 */%d * *", i/1440)
- }
- if i%60 == 0 {
- return fmt.Sprintf("0 0 */%d * * *", i/60)
- }
- return fmt.Sprintf("0 */%d * * * *", i)
- }
-
- return s
+func (j *AnalyticsJob) Schedule(_ context.Context) string {
+ return analyticsHeartbeatCheckSchedule
}
func (j *AnalyticsJob) Run(ctx context.Context) {
@@ -87,6 +77,15 @@ func (j *AnalyticsJob) Run(ctx context.Context) {
return
}
+ allowed, err := j.claimHeartbeatAttemptWindowInternal(ctx)
+ if err != nil {
+ slog.ErrorContext(ctx, "failed to acquire analytics heartbeat send window", "error", err)
+ return
+ }
+ if !allowed {
+ return
+ }
+
instanceID := j.settingsService.GetStringSetting(ctx, "instanceId", "")
payload := struct {
@@ -188,10 +187,65 @@ func (j *AnalyticsJob) Run(ctx context.Context) {
}
func (j *AnalyticsJob) Reschedule(ctx context.Context) error {
- slog.InfoContext(ctx, "rescheduling analytics heartbeat job in new scheduler; currently requires restart")
+ slog.InfoContext(ctx, "analytics heartbeat schedule is fixed and managed internally", "schedule", analyticsHeartbeatCheckSchedule)
return nil
}
+func (j *AnalyticsJob) claimHeartbeatAttemptWindowInternal(ctx context.Context) (bool, error) {
+ if j.kvService == nil {
+ return false, fmt.Errorf("analytics heartbeat kv service is not configured")
+ }
+
+ j.runMu.Lock()
+ defer j.runMu.Unlock()
+
+ now := j.now().UTC()
+ rawLastAttemptAt, ok, err := j.kvService.Get(ctx, analyticsHeartbeatLastAttemptKey)
+ if err != nil {
+ return false, fmt.Errorf("failed to load analytics heartbeat attempt state: %w", err)
+ }
+
+ if ok {
+ lastAttemptAt, parseErr := time.Parse(time.RFC3339Nano, rawLastAttemptAt)
+ if parseErr != nil {
+ slog.WarnContext(
+ ctx,
+ "invalid analytics heartbeat attempt timestamp; resetting dedupe window",
+ "key",
+ analyticsHeartbeatLastAttemptKey,
+ "value",
+ rawLastAttemptAt,
+ "error",
+ parseErr,
+ )
+ } else {
+ nextEligibleAt := lastAttemptAt.Add(analyticsHeartbeatDedupeWindow)
+ if now.Before(nextEligibleAt) {
+ slog.InfoContext(
+ ctx,
+ "skipping analytics heartbeat; already attempted within dedupe window",
+ "jobName",
+ AnalyticsJobName,
+ "lastAttemptAt",
+ lastAttemptAt,
+ "nextEligibleAt",
+ nextEligibleAt,
+ )
+ return false, nil
+ }
+ }
+ }
+
+ // Persist the attempt window before sending on purpose: the product behavior is
+ // best-effort at-most-once-per-24h check-ins, which avoids duplicate heartbeats
+ // after restarts or partially completed outbound requests.
+ if err := j.kvService.Set(ctx, analyticsHeartbeatLastAttemptKey, now.Format(time.RFC3339Nano)); err != nil {
+ return false, fmt.Errorf("failed to persist analytics heartbeat attempt state: %w", err)
+ }
+
+ return true, nil
+}
+
func (j *AnalyticsJob) getServerType() string {
if j.cfg.AgentMode {
return "agent"
diff --git a/backend/pkg/scheduler/analytics_job_test.go b/backend/pkg/scheduler/analytics_job_test.go
index 5159d8d8c..1c19473ae 100644
--- a/backend/pkg/scheduler/analytics_job_test.go
+++ b/backend/pkg/scheduler/analytics_job_test.go
@@ -6,7 +6,10 @@ import (
"io"
"net/http"
"net/http/httptest"
+ "sync"
+ "sync/atomic"
"testing"
+ "time"
glsqlite "github.com/glebarez/sqlite"
"github.com/stretchr/testify/require"
@@ -18,25 +21,29 @@ import (
"github.com/getarcaneapp/arcane/backend/internal/services"
)
-func setupAnalyticsSettingsService(t *testing.T) *services.SettingsService {
+func setupAnalyticsStateServicesInternal(t *testing.T) (*database.DB, *services.SettingsService, *services.KVService) {
t.Helper()
ctx := context.Background()
db, err := gorm.Open(glsqlite.Open(":memory:"), &gorm.Config{})
require.NoError(t, err)
require.NoError(t, db.AutoMigrate(&models.SettingVariable{}))
+ require.NoError(t, db.AutoMigrate(&models.KVEntry{}))
- svc, err := services.NewSettingsService(ctx, &database.DB{DB: db})
+ wrappedDB := &database.DB{DB: db}
+ settingsService, err := services.NewSettingsService(ctx, wrappedDB)
require.NoError(t, err)
- require.NoError(t, svc.SetStringSetting(ctx, "instanceId", "test-instance"))
+ require.NoError(t, settingsService.SetStringSetting(ctx, "instanceId", "test-instance"))
- return svc
+ return wrappedDB, settingsService, services.NewKVService(wrappedDB)
}
-func newHeartbeatServer(t *testing.T) (*httptest.Server, <-chan []byte) {
+func newHeartbeatServer(t *testing.T) (*httptest.Server, <-chan []byte, *atomic.Int32) {
t.Helper()
- bodyCh := make(chan []byte, 1)
+ bodyCh := make(chan []byte, 10)
+ requestCount := &atomic.Int32{}
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ requestCount.Add(1)
body, err := io.ReadAll(r.Body)
if err != nil {
t.Errorf("failed to read heartbeat body: %v", err)
@@ -45,17 +52,17 @@ func newHeartbeatServer(t *testing.T) (*httptest.Server, <-chan []byte) {
w.WriteHeader(http.StatusOK)
}))
- return server, bodyCh
+ return server, bodyCh, requestCount
}
func TestAnalyticsJob_Run_ManagerPayload(t *testing.T) {
ctx := context.Background()
- settingsService := setupAnalyticsSettingsService(t)
- server, bodyCh := newHeartbeatServer(t)
+ _, settingsService, kvService := setupAnalyticsStateServicesInternal(t)
+ server, bodyCh, _ := newHeartbeatServer(t)
defer server.Close()
cfg := &config.Config{Environment: config.AppEnvironmentProduction}
- job := NewAnalyticsJob(settingsService, server.Client(), cfg)
+ job := NewAnalyticsJob(settingsService, kvService, server.Client(), cfg)
job.heartbeatURL = server.URL
job.Run(ctx)
@@ -76,12 +83,12 @@ func TestAnalyticsJob_Run_ManagerPayload(t *testing.T) {
func TestAnalyticsJob_Run_AgentPayload(t *testing.T) {
ctx := context.Background()
- settingsService := setupAnalyticsSettingsService(t)
- server, bodyCh := newHeartbeatServer(t)
+ _, settingsService, kvService := setupAnalyticsStateServicesInternal(t)
+ server, bodyCh, _ := newHeartbeatServer(t)
defer server.Close()
cfg := &config.Config{AgentMode: true, Environment: config.AppEnvironmentProduction}
- job := NewAnalyticsJob(settingsService, server.Client(), cfg)
+ job := NewAnalyticsJob(settingsService, kvService, server.Client(), cfg)
job.heartbeatURL = server.URL
job.Run(ctx)
@@ -100,12 +107,12 @@ func TestAnalyticsJob_Run_AgentPayload(t *testing.T) {
func TestAnalyticsJob_Run_SkipsWhenDisabled(t *testing.T) {
ctx := context.Background()
- settingsService := setupAnalyticsSettingsService(t)
- server, bodyCh := newHeartbeatServer(t)
+ _, settingsService, kvService := setupAnalyticsStateServicesInternal(t)
+ server, bodyCh, _ := newHeartbeatServer(t)
defer server.Close()
cfg := &config.Config{AnalyticsDisabled: true, Environment: config.AppEnvironmentProduction}
- job := NewAnalyticsJob(settingsService, server.Client(), cfg)
+ job := NewAnalyticsJob(settingsService, kvService, server.Client(), cfg)
job.heartbeatURL = server.URL
job.Run(ctx)
@@ -119,12 +126,12 @@ func TestAnalyticsJob_Run_SkipsWhenDisabled(t *testing.T) {
func TestAnalyticsJob_Run_SkipsWhenTestEnv(t *testing.T) {
ctx := context.Background()
- settingsService := setupAnalyticsSettingsService(t)
- server, bodyCh := newHeartbeatServer(t)
+ _, settingsService, kvService := setupAnalyticsStateServicesInternal(t)
+ server, bodyCh, _ := newHeartbeatServer(t)
defer server.Close()
cfg := &config.Config{Environment: config.AppEnvironmentTest}
- job := NewAnalyticsJob(settingsService, server.Client(), cfg)
+ job := NewAnalyticsJob(settingsService, kvService, server.Client(), cfg)
job.heartbeatURL = server.URL
job.Run(ctx)
@@ -135,3 +142,86 @@ func TestAnalyticsJob_Run_SkipsWhenTestEnv(t *testing.T) {
default:
}
}
+
+func TestAnalyticsJob_Run_SkipsWithinHeartbeatWindowAfterRestart(t *testing.T) {
+ ctx := context.Background()
+ wrappedDB, settingsService, kvService := setupAnalyticsStateServicesInternal(t)
+ server, _, requestCount := newHeartbeatServer(t)
+ defer server.Close()
+
+ cfg := &config.Config{Environment: config.AppEnvironmentProduction}
+ firstAttemptAt := time.Date(2026, time.March, 10, 7, 9, 46, 0, time.UTC)
+
+ job := NewAnalyticsJob(settingsService, kvService, server.Client(), cfg)
+ job.heartbeatURL = server.URL
+ job.now = func() time.Time { return firstAttemptAt }
+ job.Run(ctx)
+
+ reloadedSettingsService, err := services.NewSettingsService(ctx, wrappedDB)
+ require.NoError(t, err)
+ restartedJob := NewAnalyticsJob(reloadedSettingsService, services.NewKVService(wrappedDB), server.Client(), cfg)
+ restartedJob.heartbeatURL = server.URL
+ restartedJob.now = func() time.Time { return firstAttemptAt.Add(19 * time.Minute) }
+ restartedJob.Run(ctx)
+
+ require.Equal(t, int32(1), requestCount.Load())
+}
+
+func TestAnalyticsJob_Run_AllowsSendAfterHeartbeatWindow(t *testing.T) {
+ ctx := context.Background()
+ _, settingsService, kvService := setupAnalyticsStateServicesInternal(t)
+ server, _, requestCount := newHeartbeatServer(t)
+ defer server.Close()
+
+ cfg := &config.Config{Environment: config.AppEnvironmentProduction}
+ firstAttemptAt := time.Date(2026, time.March, 10, 7, 9, 46, 0, time.UTC)
+
+ firstJob := NewAnalyticsJob(settingsService, kvService, server.Client(), cfg)
+ firstJob.heartbeatURL = server.URL
+ firstJob.now = func() time.Time { return firstAttemptAt }
+ firstJob.Run(ctx)
+
+ secondJob := NewAnalyticsJob(settingsService, kvService, server.Client(), cfg)
+ secondJob.heartbeatURL = server.URL
+ secondJob.now = func() time.Time { return firstAttemptAt.Add(25 * time.Hour) }
+ secondJob.Run(ctx)
+
+ require.Equal(t, int32(2), requestCount.Load())
+}
+
+func TestAnalyticsJob_Run_ConcurrentRunsSendOnce(t *testing.T) {
+ ctx := context.Background()
+ _, settingsService, kvService := setupAnalyticsStateServicesInternal(t)
+ server, _, requestCount := newHeartbeatServer(t)
+ defer server.Close()
+
+ cfg := &config.Config{Environment: config.AppEnvironmentProduction}
+ job := NewAnalyticsJob(settingsService, kvService, server.Client(), cfg)
+ job.heartbeatURL = server.URL
+ job.now = func() time.Time {
+ return time.Date(2026, time.March, 10, 7, 9, 46, 0, time.UTC)
+ }
+
+ start := make(chan struct{})
+ var wg sync.WaitGroup
+ for range 2 {
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ <-start
+ job.Run(ctx)
+ }()
+ }
+
+ close(start)
+ wg.Wait()
+
+ require.Equal(t, int32(1), requestCount.Load())
+}
+
+func TestAnalyticsJob_Schedule_UsesFixedHourlyCheck(t *testing.T) {
+ _, settingsService, kvService := setupAnalyticsStateServicesInternal(t)
+ job := NewAnalyticsJob(settingsService, kvService, nil, &config.Config{Environment: config.AppEnvironmentProduction})
+
+ require.Equal(t, analyticsHeartbeatCheckSchedule, job.Schedule(context.Background()))
+}
diff --git a/backend/pkg/scheduler/gitops_sync_job_test.go b/backend/pkg/scheduler/gitops_sync_job_test.go
index fea09ddf9..85fcd6da0 100644
--- a/backend/pkg/scheduler/gitops_sync_job_test.go
+++ b/backend/pkg/scheduler/gitops_sync_job_test.go
@@ -9,7 +9,7 @@ import (
func TestGitOpsSyncJobSchedule_Default(t *testing.T) {
ctx := context.Background()
- settingsSvc := setupAnalyticsSettingsService(t)
+ _, settingsSvc, _ := setupAnalyticsStateServicesInternal(t)
job := NewGitOpsSyncJob(nil, settingsSvc)
got := job.Schedule(ctx)
@@ -18,7 +18,7 @@ func TestGitOpsSyncJobSchedule_Default(t *testing.T) {
func TestGitOpsSyncJobSchedule_UsesConfiguredCron(t *testing.T) {
ctx := context.Background()
- settingsSvc := setupAnalyticsSettingsService(t)
+ _, settingsSvc, _ := setupAnalyticsStateServicesInternal(t)
require.NoError(t, settingsSvc.SetStringSetting(ctx, "gitopsSyncInterval", "0 */7 * * * *"))
job := NewGitOpsSyncJob(nil, settingsSvc)
@@ -28,7 +28,7 @@ func TestGitOpsSyncJobSchedule_UsesConfiguredCron(t *testing.T) {
func TestGitOpsSyncJobSchedule_LegacyIntegerMinutes(t *testing.T) {
ctx := context.Background()
- settingsSvc := setupAnalyticsSettingsService(t)
+ _, settingsSvc, _ := setupAnalyticsStateServicesInternal(t)
require.NoError(t, settingsSvc.SetStringSetting(ctx, "gitopsSyncInterval", "120"))
job := NewGitOpsSyncJob(nil, settingsSvc)
@@ -38,7 +38,7 @@ func TestGitOpsSyncJobSchedule_LegacyIntegerMinutes(t *testing.T) {
func TestGitOpsSyncJobSchedule_InvalidCronFallsBackToDefault(t *testing.T) {
ctx := context.Background()
- settingsSvc := setupAnalyticsSettingsService(t)
+ _, settingsSvc, _ := setupAnalyticsStateServicesInternal(t)
require.NoError(t, settingsSvc.SetStringSetting(ctx, "gitopsSyncInterval", "not-a-cron"))
job := NewGitOpsSyncJob(nil, settingsSvc)
diff --git a/backend/resources/migrations/postgres/038_create_kv_table.down.sql b/backend/resources/migrations/postgres/038_create_kv_table.down.sql
new file mode 100644
index 000000000..d4b20a7bd
--- /dev/null
+++ b/backend/resources/migrations/postgres/038_create_kv_table.down.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS kv;
diff --git a/backend/resources/migrations/postgres/038_create_kv_table.up.sql b/backend/resources/migrations/postgres/038_create_kv_table.up.sql
new file mode 100644
index 000000000..6e4e24eba
--- /dev/null
+++ b/backend/resources/migrations/postgres/038_create_kv_table.up.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS kv (
+ key TEXT NOT NULL PRIMARY KEY,
+ value TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ updated_at TIMESTAMPTZ
+);
diff --git a/backend/resources/migrations/sqlite/038_create_kv_table.down.sql b/backend/resources/migrations/sqlite/038_create_kv_table.down.sql
new file mode 100644
index 000000000..d4b20a7bd
--- /dev/null
+++ b/backend/resources/migrations/sqlite/038_create_kv_table.down.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS kv;
diff --git a/backend/resources/migrations/sqlite/038_create_kv_table.up.sql b/backend/resources/migrations/sqlite/038_create_kv_table.up.sql
new file mode 100644
index 000000000..a9539dada
--- /dev/null
+++ b/backend/resources/migrations/sqlite/038_create_kv_table.up.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS kv (
+ key TEXT NOT NULL PRIMARY KEY,
+ value TEXT NOT NULL,
+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ updated_at DATETIME
+);
diff --git a/cli/pkg/jobs/cmd.go b/cli/pkg/jobs/cmd.go
index 0522b4f72..b15419e87 100644
--- a/cli/pkg/jobs/cmd.go
+++ b/cli/pkg/jobs/cmd.go
@@ -58,15 +58,13 @@ var getCmd = &cobra.Command{
output.Header("Job Schedules")
output.KeyValue("Environment health interval", cfg.EnvironmentHealthInterval)
output.KeyValue("Event cleanup interval", cfg.EventCleanupInterval)
- output.KeyValue("Analytics heartbeat interval", cfg.AnalyticsHeartbeatInterval)
return nil
},
}
var (
- environmentHealthInterval string
- eventCleanupInterval string
- analyticsHeartbeatInterval string
+ environmentHealthInterval string
+ eventCleanupInterval string
)
var updateCmd = &cobra.Command{
@@ -86,11 +84,8 @@ var updateCmd = &cobra.Command{
if cmd.Flags().Changed("event-cleanup-interval") {
req.EventCleanupInterval = &eventCleanupInterval
}
- if cmd.Flags().Changed("analytics-heartbeat-interval") {
- req.AnalyticsHeartbeatInterval = &analyticsHeartbeatInterval
- }
- if req.EnvironmentHealthInterval == nil && req.EventCleanupInterval == nil && req.AnalyticsHeartbeatInterval == nil {
+ if req.EnvironmentHealthInterval == nil && req.EventCleanupInterval == nil {
return fmt.Errorf("no updates provided (set at least one interval flag)")
}
@@ -117,7 +112,6 @@ var updateCmd = &cobra.Command{
output.Success("Job schedules updated")
output.KeyValue("Environment health interval", result.Data.EnvironmentHealthInterval)
output.KeyValue("Event cleanup interval", result.Data.EventCleanupInterval)
- output.KeyValue("Analytics heartbeat interval", result.Data.AnalyticsHeartbeatInterval)
return nil
},
}
@@ -131,5 +125,4 @@ func init() {
updateCmd.Flags().StringVar(&environmentHealthInterval, "environment-health-interval", "", "Environment health job interval (cron expression)")
updateCmd.Flags().StringVar(&eventCleanupInterval, "event-cleanup-interval", "", "Event cleanup job interval (cron expression)")
- updateCmd.Flags().StringVar(&analyticsHeartbeatInterval, "analytics-heartbeat-interval", "", "Analytics heartbeat job interval (cron expression)")
}
diff --git a/frontend/messages/en.json b/frontend/messages/en.json
index c43ca474a..8f7cdb0dc 100644
--- a/frontend/messages/en.json
+++ b/frontend/messages/en.json
@@ -1066,10 +1066,6 @@
"jobs_event_cleanup_description": "How often Arcane deletes events older than 36 hours",
"jobs_event_cleanup_interval_label": "Event Cleanup Interval (minutes)",
"jobs_event_cleanup_interval_help": "Run every 5–10080 minutes",
- "jobs_analytics_title": "Analytics Heartbeat",
- "jobs_analytics_description": "Only runs in production, and only if analytics are enabled",
- "jobs_analytics_interval_label": "Analytics Heartbeat Interval (minutes)",
- "jobs_analytics_interval_help": "Minimum 60 minutes",
"jobs_run_now": "Run Now",
"jobs_next_run": "Next run",
"jobs_schedule": "Schedule",
@@ -1084,8 +1080,6 @@
"jobs_environment_health_description": "Checks the health and connectivity of all enabled environments",
"jobs_event_cleanup_name": "Event Cleanup",
"jobs_event_cleanup_name_description": "Removes old system events to maintain database performance",
- "jobs_analytics_heartbeat_name": "Analytics Heartbeat",
- "jobs_analytics_heartbeat_description": "Sends usage statistics and telemetry data",
"jobs_auto_update_name": "Auto Update",
"jobs_auto_update_description": "Automatically updates containers when new images are available",
"jobs_image_polling_name": "Image Polling",
diff --git a/frontend/src/lib/types/job-schedule.type.ts b/frontend/src/lib/types/job-schedule.type.ts
index 172053fd0..14358b1d5 100644
--- a/frontend/src/lib/types/job-schedule.type.ts
+++ b/frontend/src/lib/types/job-schedule.type.ts
@@ -1,7 +1,6 @@
export type JobSchedules = {
environmentHealthInterval: string;
eventCleanupInterval: string;
- analyticsHeartbeatInterval: string;
autoUpdateInterval: string;
pollingInterval: string;
scheduledPruneInterval: string;
diff --git a/frontend/src/routes/(app)/environments/[id]/components/JobsTab.svelte b/frontend/src/routes/(app)/environments/[id]/components/JobsTab.svelte
index 3e9349f1a..bead252be 100644
--- a/frontend/src/routes/(app)/environments/[id]/components/JobsTab.svelte
+++ b/frontend/src/routes/(app)/environments/[id]/components/JobsTab.svelte
@@ -160,7 +160,7 @@
{ id: 'telemetry', label: m.jobs_telemetry_heading() }
];
- const hiddenJobIds = new Set(['gitops-sync', 'filesystem-watcher']);
+ const hiddenJobIds = new Set(['analytics-heartbeat', 'gitops-sync', 'filesystem-watcher']);
function getJobsByCategory(categoryId: string, jobs: JobStatus[]): JobStatus[] {
return jobs.filter((j) => {
diff --git a/types/jobschedule/jobschedule.go b/types/jobschedule/jobschedule.go
index 251a208d3..2dd1fcdc5 100644
--- a/types/jobschedule/jobschedule.go
+++ b/types/jobschedule/jobschedule.go
@@ -7,30 +7,28 @@ import "time"
// All fields are in minutes.
// This makes conversion to time.Duration straightforward in the backend.
type Config struct {
- EnvironmentHealthInterval string `json:"environmentHealthInterval"`
- EventCleanupInterval string `json:"eventCleanupInterval"`
- AnalyticsHeartbeatInterval string `json:"analyticsHeartbeatInterval"`
- AutoUpdateInterval string `json:"autoUpdateInterval"`
- PollingInterval string `json:"pollingInterval"`
- ScheduledPruneInterval string `json:"scheduledPruneInterval"`
- GitopsSyncInterval string `json:"gitopsSyncInterval"`
- VulnerabilityScanInterval string `json:"vulnerabilityScanInterval"`
- AutoHealInterval string `json:"autoHealInterval"`
+ EnvironmentHealthInterval string `json:"environmentHealthInterval"`
+ EventCleanupInterval string `json:"eventCleanupInterval"`
+ AutoUpdateInterval string `json:"autoUpdateInterval"`
+ PollingInterval string `json:"pollingInterval"`
+ ScheduledPruneInterval string `json:"scheduledPruneInterval"`
+ GitopsSyncInterval string `json:"gitopsSyncInterval"`
+ VulnerabilityScanInterval string `json:"vulnerabilityScanInterval"`
+ AutoHealInterval string `json:"autoHealInterval"`
}
// Update is used to update job schedule intervals (in minutes).
//
// Any nil field is ignored.
type Update struct {
- EnvironmentHealthInterval *string `json:"environmentHealthInterval,omitempty"`
- EventCleanupInterval *string `json:"eventCleanupInterval,omitempty"`
- AnalyticsHeartbeatInterval *string `json:"analyticsHeartbeatInterval,omitempty"`
- AutoUpdateInterval *string `json:"autoUpdateInterval,omitempty"`
- PollingInterval *string `json:"pollingInterval,omitempty"`
- ScheduledPruneInterval *string `json:"scheduledPruneInterval,omitempty"`
- GitopsSyncInterval *string `json:"gitopsSyncInterval,omitempty"`
- VulnerabilityScanInterval *string `json:"vulnerabilityScanInterval,omitempty"`
- AutoHealInterval *string `json:"autoHealInterval,omitempty"`
+ EnvironmentHealthInterval *string `json:"environmentHealthInterval,omitempty"`
+ EventCleanupInterval *string `json:"eventCleanupInterval,omitempty"`
+ AutoUpdateInterval *string `json:"autoUpdateInterval,omitempty"`
+ PollingInterval *string `json:"pollingInterval,omitempty"`
+ ScheduledPruneInterval *string `json:"scheduledPruneInterval,omitempty"`
+ GitopsSyncInterval *string `json:"gitopsSyncInterval,omitempty"`
+ VulnerabilityScanInterval *string `json:"vulnerabilityScanInterval,omitempty"`
+ AutoHealInterval *string `json:"autoHealInterval,omitempty"`
}
// JobStatus represents the current status and metadata for a background job.
diff --git a/types/meta/job_metadata.go b/types/meta/job_metadata.go
index c1afcdcbd..ec70e292a 100644
--- a/types/meta/job_metadata.go
+++ b/types/meta/job_metadata.go
@@ -51,9 +51,9 @@ var jobMetadataRegistry = map[string]JobMetadata{
"analytics-heartbeat": {
ID: "analytics-heartbeat",
Name: "Analytics Heartbeat",
- Description: "Sends usage statistics and telemetry data",
+ Description: "Checks hourly and sends anonymous telemetry at most once per 24 hours",
Category: "telemetry",
- SettingsKey: "analyticsHeartbeatInterval",
+ SettingsKey: "",
ManagerOnly: false,
IsContinuous: false,
CanRunManually: true,