From fdc4737235f1b8e997ae40d03c4072a07d18e3ac Mon Sep 17 00:00:00 2001
From: Alex Rhee <arheebikes@gmail.com>
Date: Mon, 19 Oct 2026 16:14:57 -0700
Subject: [PATCH] Enable container CPU metrics for API pods

---
 braintrust/README.md                          |  15 +++
 braintrust/templates/api-configmap.yaml       |   1 +
 .../tests/api-container-cpu-metrics_test.yaml | 115 ++++++++++++++++++
 3 files changed, 131 insertions(+)
 create mode 100644 braintrust/tests/api-container-cpu-metrics_test.yaml

diff --git a/braintrust/README.md b/braintrust/README.md
index 435347c..50dbc9c 100644
--- a/braintrust/README.md
+++ b/braintrust/README.md
@@ -469,3 +469,18 @@ Example values files for different cloud providers and configurations are locate
 - `examples/google-autopilot-cel/values.yaml`: GKE Autopilot deployment with CEL-friendly security settings.
 - `examples/google-api-isolation-autoscaling/values.yaml`: Minimal example for API workload isolation and per-pool autoscaling on GKE (combine with an Autopilot or Standard values file).
 - `examples/google-standard/values.yaml`: GKE Standard deployment.
+
+## API container CPU metrics
+
+Compatible API images collect container CPU time on Linux when `ENABLE_CONTAINER_CPU_METRICS=true`, which this chart sets for every API pool. The `api.container.cpu.time` counter measures CPU seconds across all processes in the API container using cgroup v1 or v2 accounting. Metrics use the existing OTEL exporter and require metrics telemetry to be enabled. Older API images ignore the setting.
+
+To disable collection, set:
+
+```yaml
+api:
+  extraEnvVars:
+    - name: ENABLE_CONTAINER_CPU_METRICS
+      value: "false"
+```
+
+Remove this override to enable collection again. Existing `extraEnvVars` entries should be retained when adding the override.
diff --git a/braintrust/templates/api-configmap.yaml b/braintrust/templates/api-configmap.yaml
index 41643ba..e7c161a 100644
--- a/braintrust/templates/api-configmap.yaml
+++ b/braintrust/templates/api-configmap.yaml
@@ -86,6 +86,7 @@ data:
   {{- end }}
   BRAINSTORE_BACKFILL_DISABLE_HISTORICAL: {{ .Values.api.backfillDisableHistorical | quote }}
   BRAINSTORE_BACKFILL_DISABLE_NONHISTORICAL: {{ .Values.api.backfillDisableNonhistorical | quote }}
+  ENABLE_CONTAINER_CPU_METRICS: "true"
   CONTROL_PLANE_TELEMETRY: {{ .Values.global.controlPlaneTelemetry | quote }}
   BRAINSTORE_INSERT_ROW_REFS: "true"
   # Logs v2 table. Requires pg_partman extension (default enabled in our TF modules)
diff --git a/braintrust/tests/api-container-cpu-metrics_test.yaml b/braintrust/tests/api-container-cpu-metrics_test.yaml
new file mode 100644
index 0000000..17359ed
--- /dev/null
+++ b/braintrust/tests/api-container-cpu-metrics_test.yaml
@@ -0,0 +1,115 @@
+suite: API container CPU metrics
+templates:
+  - api-configmap.yaml
+  - api-deployment.yaml
+tests:
+  - it: enables CPU collection on aws
+    template: api-configmap.yaml
+    values:
+      - __fixtures__/base-values.yaml
+    set:
+      cloud: aws
+    asserts:
+      - equal:
+          path: data.ENABLE_CONTAINER_CPU_METRICS
+          value: "true"
+  - it: enables CPU collection on google
+    template: api-configmap.yaml
+    values:
+      - __fixtures__/base-values.yaml
+    set:
+      cloud: google
+    asserts:
+      - equal:
+          path: data.ENABLE_CONTAINER_CPU_METRICS
+          value: "true"
+  - it: enables CPU collection on azure
+    template: api-configmap.yaml
+    values:
+      - __fixtures__/base-values.yaml
+    set:
+      cloud: azure
+    asserts:
+      - equal:
+          path: data.ENABLE_CONTAINER_CPU_METRICS
+          value: "true"
+  - it: shares CPU configuration with the default pool with isolation false
+    template: api-deployment.yaml
+    values:
+      - __fixtures__/base-values.yaml
+    set:
+      api.workloadIsolation.enabled: false
+    documentIndex: 0
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].envFrom
+          content:
+            configMapRef:
+              name: braintrust-api
+  - it: shares CPU configuration with the default pool with isolation true
+    template: api-deployment.yaml
+    values:
+      - __fixtures__/base-values.yaml
+    set:
+      api.workloadIsolation.enabled: true
+    documentIndex: 0
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].envFrom
+          content:
+            configMapRef:
+              name: braintrust-api
+  - it: shares CPU configuration with the ingest pool with isolation true
+    template: api-deployment.yaml
+    values:
+      - __fixtures__/base-values.yaml
+    set:
+      api.workloadIsolation.enabled: true
+    documentIndex: 1
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].envFrom
+          content:
+            configMapRef:
+              name: braintrust-api
+  - it: shares CPU configuration with the background pool with isolation true
+    template: api-deployment.yaml
+    values:
+      - __fixtures__/base-values.yaml
+    set:
+      api.workloadIsolation.enabled: true
+    documentIndex: 2
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].envFrom
+          content:
+            configMapRef:
+              name: braintrust-api
+  - it: allows explicitly setting CPU collection to false
+    template: api-deployment.yaml
+    values:
+      - __fixtures__/base-values.yaml
+    set:
+      api.extraEnvVars:
+        - name: ENABLE_CONTAINER_CPU_METRICS
+          value: "false"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: ENABLE_CONTAINER_CPU_METRICS
+            value: "false"
+  - it: allows explicitly setting CPU collection to true
+    template: api-deployment.yaml
+    values:
+      - __fixtures__/base-values.yaml
+    set:
+      api.extraEnvVars:
+        - name: ENABLE_CONTAINER_CPU_METRICS
+          value: "true"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: ENABLE_CONTAINER_CPU_METRICS
+            value: "true"