chore: add usage tracking package (#19095)

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 https://github.com/coder/internal/issues/814

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

@@ -0,0 +1 @@
+DROP TABLE usage_events;

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

@@ -0,0 +1,25 @@
+CREATE TABLE usage_events (
+  id TEXT PRIMARY KEY,
+  -- 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')),
+  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_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).';
+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 an index with all three fields used by the
+-- SelectUsageEventsForPublishing query.
+CREATE INDEX idx_usage_events_select_for_publishing
+  ON usage_events (published_at, publish_started_at, created_at);

coderd/database/migrations/testdata/fixtures/000359_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'
+)