coder · deansheather · Jul 30, 2025 · Jul 30, 2025 · Jul 30, 2025 · spikecurtis
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -7,7 +7,6 @@ tailnet/proto/ @spikecurtis @johnstcn
 vpn/vpn.proto @spikecurtis @johnstcn
 vpn/version.go @spikecurtis @johnstcn
 
-
 # This caching code is particularly tricky, and one must be very careful when
 # altering it.
 coderd/files/ @aslilac
@@ -29,3 +28,8 @@ site/src/api/countriesGenerated.ts
 site/src/api/rbacresourcesGenerated.ts
 site/src/api/typesGenerated.ts
 site/CLAUDE.md
+
+# Usage tracking code requires intimate knowledge of Tallyman and Metronome, as
+# well as guidance from revenue.
+coderd/usage/ @deansheather
+enterprise/coderd/usage/ @deansheather
diff --git a/coderd/database/dbauthz/dbauthz.go b/coderd/database/dbauthz/dbauthz.go
@@ -3913,6 +3913,13 @@ func (q *querier) InsertTemplateVersionWorkspaceTag(ctx context.Context, arg dat
 	return q.db.InsertTemplateVersionWorkspaceTag(ctx, arg)
 }
 
+func (q *querier) InsertUsageEvent(ctx context.Context, arg database.InsertUsageEventParams) error {
+	if err := q.authorizeContext(ctx, policy.ActionCreate, rbac.ResourceSystem); err != nil {
+		return err
+	}
+	return q.db.InsertUsageEvent(ctx, arg)
+}
+
 func (q *querier) InsertUser(ctx context.Context, arg database.InsertUserParams) (database.User, error) {
 	// Always check if the assigned roles can actually be assigned by this actor.
 	impliedRoles := append([]rbac.RoleIdentifier{rbac.RoleMember()}, q.convertToDeploymentRoles(arg.RBACRoles)...)
@@ -4260,6 +4267,14 @@ func (q *querier) RevokeDBCryptKey(ctx context.Context, activeKeyDigest string)
 	return q.db.RevokeDBCryptKey(ctx, activeKeyDigest)
 }
 
+func (q *querier) SelectUsageEventsForPublishing(ctx context.Context, arg time.Time) ([]database.UsageEvent, error) {
+	// ActionUpdate because we're updating the publish_started_at column.
+	if err := q.authorizeContext(ctx, policy.ActionUpdate, rbac.ResourceSystem); err != nil {
+		return nil, err
+	}
+	return q.db.SelectUsageEventsForPublishing(ctx, arg)
+}
+
 func (q *querier) TryAcquireLock(ctx context.Context, id int64) (bool, error) {
 	return q.db.TryAcquireLock(ctx, id)
 }
@@ -4725,6 +4740,13 @@ func (q *querier) UpdateTemplateWorkspacesLastUsedAt(ctx context.Context, arg da
 	return fetchAndExec(q.log, q.auth, policy.ActionUpdate, fetch, q.db.UpdateTemplateWorkspacesLastUsedAt)(ctx, arg)
 }
 
+func (q *querier) UpdateUsageEventsPostPublish(ctx context.Context, arg database.UpdateUsageEventsPostPublishParams) error {
+	if err := q.authorizeContext(ctx, policy.ActionUpdate, rbac.ResourceSystem); err != nil {
+		return err
+	}
+	return q.db.UpdateUsageEventsPostPublish(ctx, arg)
+}
+
 func (q *querier) UpdateUserDeletedByID(ctx context.Context, id uuid.UUID) error {
 	return deleteQ(q.log, q.auth, q.db.GetUserByID, q.db.UpdateUserDeletedByID)(ctx, id)
 }

diff --git a/coderd/database/dbauthz/dbauthz_test.go b/coderd/database/dbauthz/dbauthz_test.go
@@ -5845,3 +5845,27 @@ func (s *MethodTestSuite) TestAuthorizePrebuiltWorkspace() {
 			}).Asserts(w, policy.ActionUpdate, w.AsPrebuild(), policy.ActionUpdate)
 	}))
 }
+
+func (s *MethodTestSuite) TestUsageEvents() {
+	s.Run("InsertUsageEvent", s.Subtest(func(db database.Store, check *expects) {
+		check.Args(database.InsertUsageEventParams{
+			ID:        "1",
+			EventType: database.UsageEventTypeDcManagedAgentsV1,
+			EventData: []byte("{}"),
+			CreatedAt: dbtime.Now(),
+		}).Asserts(rbac.ResourceSystem, policy.ActionCreate)
+	}))
+
+	s.Run("SelectUsageEventsForPublishing", s.Subtest(func(db database.Store, check *expects) {
+		check.Args(dbtime.Now()).Asserts(rbac.ResourceSystem, policy.ActionUpdate)
+	}))
+
+	s.Run("UpdateUsageEventsPostPublish", s.Subtest(func(db database.Store, check *expects) {
+		check.Args(database.UpdateUsageEventsPostPublishParams{
+			Now:             dbtime.Now(),
+			IDs:             []string{"1", "2"},
+			FailureMessages: []string{"error", "error"},
+			SetPublishedAts: []bool{false, false},
+		}).Asserts(rbac.ResourceSystem, policy.ActionUpdate)
+	}))
+}
diff --git a/coderd/database/dbmetrics/querymetrics.go b/coderd/database/dbmetrics/querymetrics.go
diff --git a/coderd/database/dbmock/dbmock.go b/coderd/database/dbmock/dbmock.go
diff --git a/coderd/database/dump.sql b/coderd/database/dump.sql
diff --git a/coderd/database/migrations/000353_create_usage_events_table.down.sql b/coderd/database/migrations/000353_create_usage_events_table.down.sql
@@ -0,0 +1,2 @@
+DROP TABLE usage_events;
+DROP TYPE usage_event_type;
diff --git a/coderd/database/migrations/000353_create_usage_events_table.up.sql b/coderd/database/migrations/000353_create_usage_events_table.up.sql
@@ -0,0 +1,26 @@
+CREATE TYPE usage_event_type AS ENUM (
+  'dc_managed_agents_v1'
+);
+
+COMMENT ON TYPE usage_event_type IS 'The usage event type with version. "dc" means "discrete" (e.g. a single event, for counters), "hb" means "heartbeat" (e.g. a recurring event that contains a total count of usage generated from the database, for gauges).';
+
+CREATE TABLE usage_events (
+  id TEXT PRIMARY KEY,
+  event_type usage_event_type NOT NULL,
+  event_data JSONB NOT NULL,
+  created_at TIMESTAMP WITH TIME ZONE NOT NULL,
+  publish_started_at TIMESTAMP WITH TIME ZONE DEFAULT NULL,
+  published_at TIMESTAMP WITH TIME ZONE DEFAULT NULL,
+  failure_message TEXT DEFAULT NULL
+);
+
+COMMENT ON TABLE usage_events IS 'usage_events contains usage data that is collected from the product and potentially shipped to the usage collector service.';
+COMMENT ON COLUMN usage_events.id IS 'For "discrete" event types, this is a random UUID. For "heartbeat" event types, this is a combination of the event type and a truncated timestamp.';
+COMMENT ON COLUMN usage_events.event_data IS 'Event payload. Determined by the matching usage struct for this event type.';
+COMMENT ON COLUMN usage_events.publish_started_at IS 'Set to a timestamp while the event is being published by a Coder replica to the usage collector service. Used to avoid duplicate publishes by multiple replicas. Timestamps older than 1 hour are considered expired.';
+COMMENT ON COLUMN usage_events.published_at IS 'Set to a timestamp when the event is successfully (or permanently unsuccessfully) published to the usage collector service. If set, the event should never be attempted to be published again.';
+COMMENT ON COLUMN usage_events.failure_message IS 'Set to an error message when the event is temporarily or permanently unsuccessfully published to the usage collector service.';
+
+CREATE INDEX idx_usage_events_created_at ON usage_events (created_at);
+CREATE INDEX idx_usage_events_publish_started_at ON usage_events (publish_started_at);
+CREATE INDEX idx_usage_events_published_at ON usage_events (published_at);
diff --git a/coderd/database/migrations/testdata/fixtures/000353_create_usage_events_table.up.sql b/coderd/database/migrations/testdata/fixtures/000353_create_usage_events_table.up.sql
@@ -0,0 +1,60 @@
+INSERT INTO usage_events (
+    id,
+    event_type,
+    event_data,
+    created_at,
+    publish_started_at,
+    published_at,
+    failure_message
+)
+VALUES
+-- Unpublished dc_managed_agents_v1 event.
+(
+    'event1',
+    'dc_managed_agents_v1',
+    '{"count":1}',
+    '2023-01-01 00:00:00+00',
+    NULL,
+    NULL,
+    NULL
+),
+-- Successfully published dc_managed_agents_v1 event.
+(
+    'event2',
+    'dc_managed_agents_v1',
+    '{"count":2}',
+    '2023-01-01 00:00:00+00',
+    NULL,
+    '2023-01-01 00:00:02+00',
+    NULL
+),
+-- Publish in progress dc_managed_agents_v1 event.
+(
+    'event3',
+    'dc_managed_agents_v1',
+    '{"count":3}',
+    '2023-01-01 00:00:00+00',
+    '2023-01-01 00:00:01+00',
+    NULL,
+    NULL
+),
+-- Temporarily failed to publish dc_managed_agents_v1 event.
+(
+    'event4',
+    'dc_managed_agents_v1',
+    '{"count":4}',
+    '2023-01-01 00:00:00+00',
+    NULL,
+    NULL,
+    'publish failed temporarily'
+),
+-- Permanently failed to publish dc_managed_agents_v1 event.
+(
+    'event5',
+    'dc_managed_agents_v1',
+    '{"count":5}',
+    '2023-01-01 00:00:00+00',
+    NULL,
+    '2023-01-01 00:00:02+00',
+    'publish failed permanently'
+)
diff --git a/coderd/database/modelmethods.go b/coderd/database/modelmethods.go
@@ -4,6 +4,7 @@ import (
 	"encoding/hex"
 	"sort"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/google/uuid"
@@ -628,3 +629,11 @@ func (m WorkspaceAgentVolumeResourceMonitor) Debounce(
 
 	return m.DebouncedUntil, false
 }
+
+func (e UsageEventType) IsDiscrete() bool {
+	return e.Valid() && strings.HasPrefix(string(e), "dc_")
+}
+
+func (e UsageEventType) IsHeartbeat() bool {
+	return e.Valid() && strings.HasPrefix(string(e), "hb_")
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		DROP TABLE usage_events;
		DROP TYPE usage_event_type;