coder · dannykopping · Mar 11, 2024 · Mar 7, 2024 · Mar 8, 2024 · Mar 8, 2024
diff --git a/cli/server.go b/cli/server.go
@@ -229,13 +229,13 @@ func enablePrometheus(
 	afterCtx(ctx, closeInsightsMetricsCollector)
 
 	if vals.Prometheus.CollectAgentStats {
-		closeAgentStatsFunc, err := prometheusmetrics.AgentStats(ctx, logger, options.PrometheusRegistry, options.Database, time.Now(), 0)
+		closeAgentStatsFunc, err := prometheusmetrics.AgentStats(ctx, logger, options.PrometheusRegistry, options.Database, time.Now(), 0, options.DeploymentValues.Prometheus.AggregateAgentStatsBy.Value())
 		if err != nil {
 			return nil, xerrors.Errorf("register agent stats prometheus metric: %w", err)
 		}
 		afterCtx(ctx, closeAgentStatsFunc)
 
-		metricsAggregator, err := prometheusmetrics.NewMetricsAggregator(logger, options.PrometheusRegistry, 0)
+		metricsAggregator, err := prometheusmetrics.NewMetricsAggregator(logger, options.PrometheusRegistry, 0, options.DeploymentValues.Prometheus.AggregateAgentStatsBy.Value())
 		if err != nil {
 			return nil, xerrors.Errorf("can't initialize metrics aggregator: %w", err)
 		}

diff --git a/cli/testdata/coder_server_--help.golden b/cli/testdata/coder_server_--help.golden
@@ -123,6 +123,11 @@ INTROSPECTION / PROMETHEUS OPTIONS:
       --prometheus-address host:port, $CODER_PROMETHEUS_ADDRESS (default: 127.0.0.1:2112)
           The bind address to serve prometheus metrics.
 
+      --prometheus-aggregate-agent-stats-by string-array, $CODER_PROMETHEUS_AGGREGATE_AGENT_STATS_BY (default: agent_name,template_name,username,workspace_name)
+          When collecting agent stats, aggregate metrics by a given set of
+          comma-separated labels to reduce cardinality. Accepted values are
+          agent_name, template_name, username, workspace_name.
+
       --prometheus-collect-agent-stats bool, $CODER_PROMETHEUS_COLLECT_AGENT_STATS
           Collect agent stats (may increase charges for metrics storage).
 

diff --git a/cli/testdata/server-config.yaml.golden b/cli/testdata/server-config.yaml.golden
@@ -188,6 +188,15 @@ introspection:
     # Collect agent stats (may increase charges for metrics storage).
     # (default: <unset>, type: bool)
     collect_agent_stats: false
+    # When collecting agent stats, aggregate metrics by a given set of comma-separated
+    # labels to reduce cardinality. Accepted values are agent_name, template_name,
+    # username, workspace_name.
+    # (default: agent_name,template_name,username,workspace_name, type: string-array)
+    aggregate_agent_stats_by:
+      - agent_name
+      - template_name
+      - username
+      - workspace_name
     # Collect database metrics (may increase charges for metrics storage).
     # (default: false, type: bool)
     collect_db_metrics: false

diff --git a/coderd/agentmetrics/labels.go b/coderd/agentmetrics/labels.go
@@ -0,0 +1,38 @@
+package agentmetrics
+
+import (
+	"strings"
+
+	"golang.org/x/xerrors"
+)
+
+const (
+	LabelAgentName     = "agent_name"
+	LabelTemplateName  = "template_name"
+	LabelUsername      = "username"
+	LabelWorkspaceName = "workspace_name"
+)
+
+var (
+	LabelAll        = []string{LabelAgentName, LabelTemplateName, LabelUsername, LabelWorkspaceName}
+	LabelAgentStats = []string{LabelAgentName, LabelUsername, LabelWorkspaceName}
+)
+
+// ValidateAggregationLabels ensures a given set of labels are valid aggregation labels.
+func ValidateAggregationLabels(labels []string) error {
+	acceptable := LabelAll
+
+	seen := make(map[string]any, len(acceptable))
+	for _, label := range acceptable {
+		seen[label] = nil
+	}
+
+	for _, label := range labels {
+		if _, found := seen[label]; !found {
+			return xerrors.Errorf("%q is not a valid aggregation label; only one or more of %q are acceptable",
+				label, strings.Join(acceptable, ", "))
+		}
+	}
+
+	return nil
+}
diff --git a/coderd/agentmetrics/labels_test.go b/coderd/agentmetrics/labels_test.go
@@ -0,0 +1,53 @@
+package agentmetrics_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/coderd/agentmetrics"
+)
+
+func TestValidateAggregationLabels(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		labels      []string
+		expectedErr bool
+	}{
+		{
+			name: "empty list is valid",
+		},
+		{
+			name:   "single valid entry",
+			labels: []string{agentmetrics.LabelTemplateName},
+		},
+		{
+			name:   "multiple valid entries",
+			labels: []string{agentmetrics.LabelTemplateName, agentmetrics.LabelUsername},
+		},
+		{
+			name:   "repeated valid entries are not invalid",
+			labels: []string{agentmetrics.LabelTemplateName, agentmetrics.LabelUsername, agentmetrics.LabelUsername, agentmetrics.LabelUsername},
+		},
+		{
+			name:        "empty entry is invalid",
+			labels:      []string{""},
+			expectedErr: true,
+		},
+	}
+
+	for _, tc := range tests {
+		tc := tc
+
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := agentmetrics.ValidateAggregationLabels(tc.labels)
+			if tc.expectedErr {
+				require.Error(t, err)
+			}
+		})
+	}
+}
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json