Add WS image metrics to workspace instances (#20426)

* Add WS image metrics to workspace instances

* Update tests

* fix ws-manager-api field description

* Prefer existing DB values for metrics

* Copy proto comments over to protocol type

components/gitpod-db/src/typeorm/entity/db-workspace-instance.ts

@@ -13,6 +13,7 @@ import {
     WorkspaceInstanceConfiguration,
     ImageBuildInfo,
     WorkspaceInstanceRepoStatus,
+    WorkspaceInstanceMetrics,
 } from "@gitpod/gitpod-protocol";
 import { TypeORM } from "../typeorm";
 import { Transformer } from "../transformer";
@@ -84,7 +85,7 @@ export class DBWorkspaceInstance implements WorkspaceInstance {
     gitStatus?: WorkspaceInstanceRepoStatus;
 
     /**
-     * This field is a databse-only copy of status.phase for the sole purpose of creating indexes on it.
+     * This field is a database-only copy of status.phase for the sole purpose of creating indexes on it.
      * Is replicated inside workspace-db-impl.ts/storeInstance.
      */
     @Column({
@@ -117,4 +118,10 @@ export class DBWorkspaceInstance implements WorkspaceInstance {
         transformer: Transformer.MAP_EMPTY_STR_TO_UNDEFINED,
     })
     usageAttributionId?: string;
+
+    @Column({
+        type: "simple-json",
+        nullable: true,
+    })
+    metrics?: WorkspaceInstanceMetrics;
 }

components/gitpod-db/src/typeorm/migration/1733397172273-AddWorkspaceInstanceMetrics.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2024 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License.AGPL.txt in the project root for license information.
+ */
+
+import { MigrationInterface, QueryRunner } from "typeorm";
+import { columnExists } from "./helper/helper";
+
+const table = "d_b_workspace_instance";
+const newColumn = "metrics";
+
+export class AddWorkspaceInstanceMetrics1733397172273 implements MigrationInterface {
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        if (!(await columnExists(queryRunner, table, newColumn))) {
+            await queryRunner.query(`ALTER TABLE ${table} ADD COLUMN ${newColumn} JSON NULL`);
+        }
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        if (await columnExists(queryRunner, table, newColumn)) {
+            await queryRunner.query(`ALTER TABLE ${table} DROP COLUMN ${newColumn}`);
+        }
+    }
+}

components/gitpod-protocol/src/workspace-instance.ts

@@ -75,7 +75,7 @@ export interface WorkspaceInstance {
 // WorkspaceInstanceStatus describes the current state of a workspace instance
 export interface WorkspaceInstanceStatus {
     // version is the current version of the workspace instance status
-    // Note: consider this value opague. The only guarantee given is that it imposes
+    // Note: consider this value opaque. The only guarantee given is that it imposes
     //       a partial order on status updates, i.e. a.version > b.version -> a newer than b.
     version?: number;
 
@@ -105,6 +105,9 @@ export interface WorkspaceInstanceStatus {
 
     // ownerToken is the token one needs to access the workspace. Its presence is checked by ws-proxy.
     ownerToken?: string;
+
+    // metrics contains metrics about the workspace instance
+    metrics?: WorkspaceInstanceMetrics;
 }
 
 // WorkspaceInstancePhase describes a high-level state of a workspace instance
@@ -122,11 +125,11 @@ export type WorkspaceInstancePhase =
     | "building"
 
     // Pending means the workspace does not yet consume resources in the cluster, but rather is looking for
-    // some space within the cluster. If for example the cluster needs to scale up to accomodate the
+    // some space within the cluster. If for example the cluster needs to scale up to accommodate the
     // workspace, the workspace will be in Pending state until that happened.
     | "pending"
 
-    // Creating means the workspace is currently being created. Thati includes downloading the images required
+    // Creating means the workspace is currently being created. That includes downloading the images required
     // to run the workspace over the network. The time spent in this phase varies widely and depends on the current
     // network speed, image size and cache states.
     | "creating"
@@ -193,7 +196,7 @@ export interface WorkspaceInstancePort {
     // The outward-facing port number
     port: number;
 
-    // The visiblity of this port. Optional for backwards compatibility.
+    // The visibility of this port. Optional for backwards compatibility.
     visibility?: PortVisibility;
 
     // Public, outward-facing URL where the port can be accessed on.
@@ -280,7 +283,7 @@ export interface IdeSetup {
 // WorkspaceInstanceConfiguration contains all per-instance configuration
 export interface WorkspaceInstanceConfiguration {
     // theiaVersion is the version of Theia this workspace instance uses
-    // @deprected: replaced with the ideImage field
+    // @deprecated: replaced with the ideImage field
     theiaVersion?: string;
 
     // feature flags are the lowercase feature-flag names as passed to ws-manager
@@ -324,3 +327,19 @@ export interface ImageBuildLogInfo {
     url: string;
     headers: { [key: string]: string };
 }
+
+/**
+ * Holds metrics about the workspace instance
+ */
+export interface WorkspaceInstanceMetrics {
+    image?: Partial<{
+        /**
+         * the total size of the image in bytes (includes Gitpod-specific layers like IDE)
+         */
+        totalSize: number;
+        /**
+         * the size of the workspace image in bytes
+         */
+        workspaceImageSize: number;
+    }>;
+}

components/public-api/gitpod/v1/workspace.proto

@@ -884,6 +884,14 @@ message WorkspaceSnapshot {
 }
 
 message WorkspaceSession {
+  message Metrics {
+    // workspace_image_size is the size of the workspace image in bytes
+    int64 workspace_image_size = 1;
+
+    // total_image_size is the total size of the image in bytes (includes Gitpod-specific layers like IDE)
+    int64 total_image_size = 2;
+  }
+
   string id = 1;
 
   Workspace workspace = 2;
@@ -893,4 +901,6 @@ message WorkspaceSession {
   google.protobuf.Timestamp started_time = 5;
   google.protobuf.Timestamp stopping_time = 6;
   google.protobuf.Timestamp stopped_time = 7;
+
+  Metrics metrics = 8;
 }