add cgroup data to server telemetry

components/schemas/infrastructure/servers/telemetry/ServerTelemetrySnapshot.yml → components/schemas/infrastructure/servers/telemetry/snapshot/ServerTelemetrySnapshot.yml

@@ -11,35 +11,40 @@ required:
   - processes
 properties:
   generated:
-    $ref: "../../../DateTime.yml"
+    $ref: "../../../../DateTime.yml"
     description: The timestamp at which this telemetry snapshot was generated.
   system:
     description: General system telemetry. Null when system telemetry is unavailable.
     oneOf:
-      - $ref: ./ServerTelemetrySystem.yml
+      - $ref: ./system/ServerTelemetrySystem.yml
       - type: "null"
   cpu:
     description: CPU telemetry for this snapshot. Null when CPU telemetry is unavailable.
     oneOf:
-      - $ref: ./ServerTelemetryCpu.yml
+      - $ref: ./cpu/ServerTelemetryCpu.yml
       - type: "null"
   memory:
     description: Memory telemetry for this snapshot. Null when memory telemetry is unavailable.
     oneOf:
-      - $ref: ./ServerTelemetryMemory.yml
+      - $ref: ./memory/ServerTelemetryMemory.yml
       - type: "null"
   network:
     description: Network telemetry for this snapshot. Null when network telemetry is unavailable.
     oneOf:
-      - $ref: ./ServerTelemetryNetwork.yml
+      - $ref: ./network/ServerTelemetryNetwork.yml
       - type: "null"
   disk:
     description: Disk telemetry for this snapshot. Null when disk telemetry is unavailable.
     oneOf:
-      - $ref: ./ServerTelemetryDisk.yml
+      - $ref: ./storage/ServerTelemetryDisk.yml
       - type: "null"
   processes:
     description: Process telemetry for this snapshot. Null when process telemetry is unavailable.
     oneOf:
-      - $ref: ./ServerTelemetryProcesses.yml
+      - $ref: ./processes/ServerTelemetryProcesses.yml
+      - type: "null"
+  cgroups:
+    description: Cgroup telemetry for this snapshot. Null when cgroup telemetry is unavailable.
+    oneOf:
+      - $ref: ./cgroups/ServerTelemetryCgroups.yml
       - type: "null"

components/schemas/infrastructure/servers/telemetry/snapshot/cgroups/ServerTelemetryCgroupCpuStats.yml

@@ -0,0 +1,35 @@
+title: ServerTelemetryCgroupCpuStats
+type: object
+description: CPU usage and throttling statistics for a cgroup, sourced from cpu.stat.
+required:
+  - usage_usec
+  - user_usec
+  - system_usec
+  - nr_periods
+  - nr_throttled
+  - throttled_usec
+properties:
+  usage_usec:
+    type: integer
+    format: int64
+    description: Total CPU time consumed by the cgroup, in microseconds.
+  user_usec:
+    type: integer
+    format: int64
+    description: CPU time consumed in user mode, in microseconds.
+  system_usec:
+    type: integer
+    format: int64
+    description: CPU time consumed in kernel (system) mode, in microseconds.
+  nr_periods:
+    type: integer
+    format: int64
+    description: Number of enforcement periods that have elapsed while CPU bandwidth limiting was active.
+  nr_throttled:
+    type: integer
+    format: int64
+    description: Number of enforcement periods in which the cgroup was throttled.
+  throttled_usec:
+    type: integer
+    format: int64
+    description: Total time the cgroup was throttled, in microseconds.

components/schemas/infrastructure/servers/telemetry/snapshot/cgroups/ServerTelemetryCgroupMemoryStats.yml

@@ -0,0 +1,43 @@
+title: ServerTelemetryCgroupMemoryStats
+type: object
+description: Memory and swap usage statistics for a cgroup.
+required:
+  - usage_bytes
+  - swap_usage_bytes
+  - peak_bytes
+  - swap_peak_bytes
+  - events
+  - stat_metrics
+properties:
+  usage_bytes:
+    type: integer
+    format: int64
+    description: Current total memory usage of the cgroup, in bytes (memory.current).
+  swap_usage_bytes:
+    type: integer
+    format: int64
+    description: Current swap usage of the cgroup, in bytes (memory.swap.current).
+  peak_bytes:
+    type: integer
+    format: int64
+    description: Peak memory usage recorded for the cgroup, in bytes (memory.peak).
+  swap_peak_bytes:
+    type: integer
+    format: int64
+    description: Peak swap usage recorded for the cgroup, in bytes (memory.swap.peak).
+  events:
+    description: Memory controller event counters keyed by event name, sourced from memory.events (for example low, high, max, oom, oom_kill).
+    type:
+      - object
+      - "null"
+    additionalProperties:
+      type: integer
+      format: int64
+  stat_metrics:
+    description: Detailed memory statistics keyed by metric name, sourced from memory.stat.
+    type:
+      - object
+      - "null"
+    additionalProperties:
+      type: integer
+      format: int64

components/schemas/infrastructure/servers/telemetry/snapshot/cgroups/ServerTelemetryCgroupPressureMetric.yml

@@ -0,0 +1,13 @@
+title: ServerTelemetryCgroupPressureMetric
+type: object
+description: Pressure stall information for a single resource, split into some and full stall measurements.
+required:
+  - some
+  - full
+properties:
+  some:
+    description: Pressure measured while one or more tasks were stalled waiting on the resource.
+    $ref: ./ServerTelemetryCgroupPressureValues.yml
+  full:
+    description: Pressure measured while all non-idle tasks were simultaneously stalled waiting on the resource.
+    $ref: ./ServerTelemetryCgroupPressureValues.yml

components/schemas/infrastructure/servers/telemetry/snapshot/cgroups/ServerTelemetryCgroupPressureStats.yml

@@ -0,0 +1,17 @@
+title: ServerTelemetryCgroupPressureStats
+type: object
+description: Pressure stall information (PSI) for a cgroup, covering CPU, memory, and IO.
+required:
+  - cpu
+  - memory
+  - io
+properties:
+  cpu:
+    description: CPU pressure stall information.
+    $ref: ./ServerTelemetryCgroupPressureMetric.yml
+  memory:
+    description: Memory pressure stall information.
+    $ref: ./ServerTelemetryCgroupPressureMetric.yml
+  io:
+    description: IO pressure stall information.
+    $ref: ./ServerTelemetryCgroupPressureMetric.yml

components/schemas/infrastructure/servers/telemetry/snapshot/cgroups/ServerTelemetryCgroupPressureValues.yml

@@ -0,0 +1,25 @@
+title: ServerTelemetryCgroupPressureValues
+type: object
+description: Pressure stall averages over trailing time windows, plus the total accumulated stall time.
+required:
+  - avg10
+  - avg60
+  - avg300
+  - total_usec
+properties:
+  avg10:
+    type: number
+    format: double
+    description: Percentage of time stalled over the trailing 10-second window.
+  avg60:
+    type: number
+    format: double
+    description: Percentage of time stalled over the trailing 60-second window.
+  avg300:
+    type: number
+    format: double
+    description: Percentage of time stalled over the trailing 300-second window.
+  total_usec:
+    type: integer
+    format: int64
+    description: Total stall time accumulated, in microseconds.

components/schemas/infrastructure/servers/telemetry/snapshot/cgroups/ServerTelemetryCgroupV2Stats.yml

@@ -0,0 +1,21 @@
+title: ServerTelemetryCgroupV2Stats
+type: object
+description: Statistics collected from a single cgroup v2 control group.
+required:
+  - path
+  - cpu
+  - memory
+  - pressure
+properties:
+  path:
+    type: string
+    description: The cgroup v2 filesystem path these statistics were collected from.
+  cpu:
+    description: CPU usage and throttling statistics for the cgroup.
+    $ref: ./ServerTelemetryCgroupCpuStats.yml
+  memory:
+    description: Memory and swap usage statistics for the cgroup.
+    $ref: ./ServerTelemetryCgroupMemoryStats.yml
+  pressure:
+    description: Pressure stall information (PSI) for the cgroup.
+    $ref: ./ServerTelemetryCgroupPressureStats.yml

components/schemas/infrastructure/servers/telemetry/snapshot/cgroups/ServerTelemetryCgroups.yml

@@ -0,0 +1,13 @@
+title: ServerTelemetryCgroups
+type: object
+description: A collection of cgroup v2 statistics, keyed by cgroup identifier.
+required:
+  - cgroups
+properties:
+  cgroups:
+    description: Map of cgroup v2 statistics, keyed by cgroup identifier.
+    type:
+      - object
+      - "null"
+    additionalProperties:
+      $ref: ./ServerTelemetryCgroupV2Stats.yml

platform/api.yml

@@ -789,7 +789,7 @@ components:
   schemas:
     # This is a webhook only type for now, but we want it included in the output.
     ServerTelemetrySnapshot:
-      $ref: ../components/schemas/infrastructure/servers/telemetry/ServerTelemetrySnapshot.yml
+      $ref: ../components/schemas/infrastructure/servers/telemetry/snapshot/ServerTelemetrySnapshot.yml
 
 webhooks:
   environmentMetricsPush: