chore: add usage tracking package #19095

deansheather · 2025-07-30T06:02:37Z

Not used in coderd yet, see stack.

Adds two new packages:

coderd/usage: provides an interface for the "Collector" as well as a stub implementation for AGPL
enterprise/coderd/usage: provides an interface for the "Publisher" as well as a Tallyman implementation

Relates to coder/internal#814

deansheather · 2025-07-30T06:02:57Z

chore: move usage types to new package #19103
chore: wire up usage tracking for managed agents #19096
chore: add usage tracking package #19095 👈 (View in Graphite)
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

johnstcn

I have some non-blocking comments below but might need to take another pass.

coderd/database/dbauthz/dbauthz.go

coderd/database/queries/usageevents.sql

johnstcn · 2025-07-30T08:21:26Z

enterprise/coderd/usage/publisher.go

+const (
+	CoderLicenseJWTHeader = "Coder-License-JWT"
+
+	tallymanURL         = "https://tallyman-ingress.coder.com"


I can see an argument for making this a var so it's configurable at build time.

If we do need that we can add it very easily in the future.

enterprise/coderd/usage/publisher.go

johnstcn · 2025-07-30T08:34:40Z

coderd/database/migrations/000353_create_usage_events_table.up.sql

Obligatory reminder to check migration number before merging!

CODEOWNERS

coderd/database/migrations/000353_create_usage_events_table.up.sql

coderd/database/queries/usageevents.sql

coderd/database/migrations/000353_create_usage_events_table.up.sql

coderd/usage/events.go

enterprise/coderd/usage/publisher_test.go

enterprise/coderd/usage/publisher.go

johnstcn

I don't have any further blocking comments and the dbauthz stuff looks OK to me. I'd like a +1 from Spike before merging though. You probably also need to run make gen again.

coderd/usage/events.go

enterprise/coderd/usage/inserter.go

enterprise/coderd/usage/publisher_test.go

spikecurtis

LGTM modulo gen failures

Emyrk

No blockers from me! 👍

Emyrk · 2025-08-15T13:05:14Z

coderd/database/dbauthz/dbauthz_test.go

@@ -5666,3 +5666,34 @@ func (s *MethodTestSuite) TestUserSecrets() {
 			Asserts(userSecret, policy.ActionRead, userSecret, policy.ActionDelete)
 	}))
 }
+
+func (s *MethodTestSuite) TestUsageEvents() {
+	s.Run("InsertUsageEvent", s.Mocked(func(db *dbmock.MockStore, faker *gofakeit.Faker, check *expects) {


Mocked! Nice! Been slowly converting them all 👍

Emyrk · 2025-08-15T13:07:21Z

coderd/database/migrations/000359_create_usage_events_table.up.sql

+  -- We use a TEXT column with a CHECK constraint rather than an enum because of
+  -- the limitations with adding new values to an enum and using them in the
+  -- same transaction.
+  event_type TEXT NOT NULL CONSTRAINT usage_event_type_check CHECK (event_type IN ('dc_managed_agents_v1')),


Adding enum values is actually easy now:

coder/coderd/database/migrations/000300_notifications_method_inbox.up.sql

Line 1 in 82ea8e1

ALTER TYPE notification_method ADD VALUE IF NOT EXISTS 'inbox';

Removing them though is a problem:

coder/coderd/database/migrations/000300_notifications_method_inbox.down.sql

Lines 1 to 3 in 82ea8e1

-- The migration is about an enum value change

-- As we can not remove a value from an enum, we can let the down migration empty

-- In order to avoid any failure, we use ADD VALUE IF NOT EXISTS to add the value

(Although we never run down migrations so....)

Making it an enum generates the proper Golang enum

Spike asked me to not do this in a prior comment because you can't add a value and then reference it in the same transaction unless you're on pg 17. We run all migrations in a single transaction (for good reason, to avoid partial upgrades), which means we can never reference enum types in future transactions.

Emyrk · 2025-08-15T13:10:46Z

coderd/database/queries/usageevents.sql

+-- Note that this selects from the CTE, not the original table. The CTE is named
+-- the same as the original table to trick sqlc into reusing the existing struct
+-- for the table.


👍 Good trick

Emyrk · 2025-08-15T13:14:37Z

coderd/database/queries/usageevents.sql

+    SELECT
+        UNNEST(@ids::text[]) AS id,
+        UNNEST(@failure_messages::text[]) AS failure_message,
+        UNNEST(@set_published_ats::boolean[]) AS set_published_at
+) input
+WHERE
+    input.id = usage_events.id
+    -- If the number of ids, failure messages, and set published ats are not the
+    -- same, do not do anything. Unfortunately you can't really throw from a
+    -- query without writing a function or doing some jank like dividing by
+    -- zero, so this is the best we can do.
+    AND cardinality(@ids::text[]) = cardinality(@failure_messages::text[])
+    AND cardinality(@ids::text[]) = cardinality(@set_published_ats::boolean[]);


Yea, if we ever switch to PGX, it has batch operations: https://docs.sqlc.dev/en/latest/reference/changelog.html#batch-operation-improvements

Then we get type safety and the inputs are []struct{ /* ... Fields ... */}

coderd/rbac/roles_test.go

Emyrk · 2025-08-15T13:19:09Z

enterprise/coderd/license/license.go

@@ -584,6 +584,7 @@ type Claims struct {
 	Version          uint64   `json:"version"`
 	Features         Features `json:"features"`
 	RequireTelemetry bool     `json:"require_telemetry,omitempty"`
+	PublishUsageData bool     `json:"publish_usage_data,omitempty"`


Interesting this is not an entitlement?

It's not really a feature, rather a flag to send usage data (which will always get collected in enterprise builds) to a server. So it makes sense that it goes where RequireTelemetry goes since they're very similar.

enterprise/coderd/usage/publisher.go

deansheather · 2025-08-15T15:31:02Z

Merge activity

Aug 15, 3:31 PM UTC: @deansheather merged this pull request with Graphite.

github-actions bot assigned deansheather Jul 30, 2025

deansheather requested review from johnstcn and spikecurtis July 30, 2025 06:04

deansheather marked this pull request as ready for review July 30, 2025 06:05

deansheather mentioned this pull request Jul 30, 2025

chore: wire up usage tracking for managed agents #19096

Open

johnstcn reviewed Jul 30, 2025

View reviewed changes

spikecurtis reviewed Jul 30, 2025

View reviewed changes

deansheather mentioned this pull request Jul 30, 2025

chore: move usage types to new package #19103

Open

github-actions bot added the stale This issue is like stale bread. label Aug 7, 2025

github-actions bot closed this Aug 10, 2025

deansheather reopened this Aug 12, 2025

deansheather removed the stale This issue is like stale bread. label Aug 12, 2025

deansheather force-pushed the 07-30-chore_add_usage_tracking_package branch from e376311 to 82ea8e1 Compare August 15, 2025 09:28

deansheather requested a review from Emyrk as a code owner August 15, 2025 09:28

deansheather requested review from spikecurtis and johnstcn August 15, 2025 09:29

johnstcn approved these changes Aug 15, 2025

View reviewed changes

coderd/usage/events.go Show resolved Hide resolved

enterprise/coderd/usage/inserter.go Show resolved Hide resolved

enterprise/coderd/usage/publisher_test.go Outdated Show resolved Hide resolved

spikecurtis approved these changes Aug 15, 2025

View reviewed changes

Emyrk reviewed Aug 15, 2025

View reviewed changes

deansheather added 5 commits August 15, 2025 15:09

chore: add usage tracking package

b978c4c

add fixture

1a38205

PR comments

3afa02e

more PR comments

5ab8c27

gen

2529c80

deansheather force-pushed the 07-30-chore_add_usage_tracking_package branch from dca0890 to 2529c80 Compare August 15, 2025 15:19

deansheather merged commit a25d856 into main Aug 15, 2025
55 of 58 checks passed

deansheather deleted the 07-30-chore_add_usage_tracking_package branch August 15, 2025 15:31

github-actions bot locked and limited conversation to collaborators Aug 15, 2025

	-- The migration is about an enum value change
	-- As we can not remove a value from an enum, we can let the down migration empty
	-- In order to avoid any failure, we use ADD VALUE IF NOT EXISTS to add the value

chore: add usage tracking package #19095

chore: add usage tracking package #19095

Conversation

deansheather commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

deansheather commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

johnstcn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

johnstcn left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

spikecurtis left a comment

Choose a reason for hiding this comment

Uh oh!

Emyrk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

deansheather commented Aug 15, 2025

Merge activity

Uh oh!

Uh oh!

deansheather commented Jul 30, 2025 •

edited

Loading

deansheather commented Jul 30, 2025 •

edited

Loading

johnstcn left a comment •

edited

Loading