Add CPU, GPU and RAM load to API

Author: benoit-cty

carbonserver/carbonserver/api/infra/database/sql_models.py

@@ -21,6 +21,9 @@ class Emission(Base):
     gpu_energy = Column(Float)
     ram_energy = Column(Float)
     energy_consumed = Column(Float)
+    cpu_utilization_percent = Column(Float, nullable=True)
+    gpu_utilization_percent = Column(Float, nullable=True)
+    ram_utilization_percent = Column(Float, nullable=True)
     wue = Column(Float, nullable=False, default=0)
     run_id = Column(UUID(as_uuid=True), ForeignKey("runs.id", ondelete="CASCADE"))
     run = relationship("Run", back_populates="emissions")

carbonserver/carbonserver/api/infra/repositories/repository_emissions.py

@@ -41,6 +41,9 @@ def add_emission(self, emission: EmissionCreate) -> UUID:
                 gpu_energy=emission.gpu_energy,
                 ram_energy=emission.ram_energy,
                 energy_consumed=emission.energy_consumed,
+                cpu_utilization_percent=emission.cpu_utilization_percent,
+                gpu_utilization_percent=emission.gpu_utilization_percent,
+                ram_utilization_percent=emission.ram_utilization_percent,
                 wue=emission.wue,
                 run_id=emission.run_id,
             )
@@ -105,6 +108,9 @@ def map_sql_to_schema(emission: sql_models.Emission) -> Emission:
             gpu_energy=emission.gpu_energy,
             ram_energy=emission.ram_energy,
             energy_consumed=emission.energy_consumed,
+            cpu_utilization_percent=emission.cpu_utilization_percent,
+            gpu_utilization_percent=emission.gpu_utilization_percent,
+            ram_utilization_percent=emission.ram_utilization_percent,
             wue=emission.wue,
             run_id=emission.run_id,
         )

carbonserver/carbonserver/api/infra/repositories/repository_experiments.py

@@ -135,6 +135,15 @@ def get_project_detailed_sums_by_experiment(
                     func.sum(SqlModelEmission.energy_consumed).label("energy_consumed"),
                     func.sum(SqlModelEmission.duration).label("duration"),
                     func.avg(SqlModelEmission.emissions_rate).label("emissions_rate"),
+                    func.avg(SqlModelEmission.cpu_utilization_percent).label(
+                        "cpu_utilization_percent"
+                    ),
+                    func.avg(SqlModelEmission.gpu_utilization_percent).label(
+                        "gpu_utilization_percent"
+                    ),
+                    func.avg(SqlModelEmission.ram_utilization_percent).label(
+                        "ram_utilization_percent"
+                    ),
                     func.count(SqlModelEmission.emissions_rate).label(
                         "emissions_count"
                     ),

carbonserver/carbonserver/api/infra/repositories/repository_organizations.py

@@ -116,6 +116,15 @@ def get_organization_detailed_sums(
                     func.sum(SqlModelEmission.energy_consumed).label("energy_consumed"),
                     func.sum(SqlModelEmission.duration).label("duration"),
                     func.avg(SqlModelEmission.emissions_rate).label("emissions_rate"),
+                    func.avg(SqlModelEmission.cpu_utilization_percent).label(
+                        "cpu_utilization_percent"
+                    ),
+                    func.avg(SqlModelEmission.gpu_utilization_percent).label(
+                        "gpu_utilization_percent"
+                    ),
+                    func.avg(SqlModelEmission.ram_utilization_percent).label(
+                        "ram_utilization_percent"
+                    ),
                     func.count(SqlModelEmission.emissions_rate).label(
                         "emissions_count"
                     ),

carbonserver/carbonserver/api/infra/repositories/repository_projects.py

@@ -130,6 +130,15 @@ def get_project_detailed_sums(
                     func.sum(SqlModelEmission.energy_consumed).label("energy_consumed"),
                     func.sum(SqlModelEmission.duration).label("duration"),
                     func.avg(SqlModelEmission.emissions_rate).label("emissions_rate"),
+                    func.avg(SqlModelEmission.cpu_utilization_percent).label(
+                        "cpu_utilization_percent"
+                    ),
+                    func.avg(SqlModelEmission.gpu_utilization_percent).label(
+                        "gpu_utilization_percent"
+                    ),
+                    func.avg(SqlModelEmission.ram_utilization_percent).label(
+                        "ram_utilization_percent"
+                    ),
                     func.count(SqlModelEmission.emissions_rate).label(
                         "emissions_count"
                     ),

carbonserver/carbonserver/api/infra/repositories/repository_runs.py

@@ -144,6 +144,15 @@ def get_experiment_detailed_sums_by_run(
                     func.sum(SqlModelEmission.energy_consumed).label("energy_consumed"),
                     func.sum(SqlModelEmission.duration).label("duration"),
                     func.avg(SqlModelEmission.emissions_rate).label("emissions_rate"),
+                    func.avg(SqlModelEmission.cpu_utilization_percent).label(
+                        "cpu_utilization_percent"
+                    ),
+                    func.avg(SqlModelEmission.gpu_utilization_percent).label(
+                        "gpu_utilization_percent"
+                    ),
+                    func.avg(SqlModelEmission.ram_utilization_percent).label(
+                        "ram_utilization_percent"
+                    ),
                     func.count(SqlModelEmission.emissions_rate).label(
                         "emissions_count"
                     ),

carbonserver/carbonserver/api/schemas.py

@@ -87,6 +87,15 @@ class EmissionBase(BaseModel):
     ram_energy: Optional[float] = Field(
         ..., ge=0, description="The ram_energy must be greater than zero"
     )
+    cpu_utilization_percent: Optional[float] = Field(
+        None, ge=0, le=100, description="The CPU utilization must be between 0 and 100"
+    )
+    gpu_utilization_percent: Optional[float] = Field(
+        None, ge=0, le=100, description="The GPU utilization must be between 0 and 100"
+    )
+    ram_utilization_percent: Optional[float] = Field(
+        None, ge=0, le=100, description="The RAM utilization must be between 0 and 100"
+    )
     wue: Optional[float] = Field(
         default=0,
         ge=0,
@@ -183,6 +192,9 @@ class RunReport(RunBase):
     duration: float
     emissions_rate: float
     emissions_count: int
+    cpu_utilization_percent: Optional[float] = None
+    gpu_utilization_percent: Optional[float] = None
+    ram_utilization_percent: Optional[float] = None
 
 
 class ExperimentBase(BaseModel):
@@ -246,6 +258,9 @@ class ExperimentReport(ExperimentBase):
     duration: int
     emissions_rate: float
     emissions_count: int
+    cpu_utilization_percent: Optional[float] = None
+    gpu_utilization_percent: Optional[float] = None
+    ram_utilization_percent: Optional[float] = None
 
     class Config:
         schema_extra = {
@@ -377,6 +392,9 @@ class ProjectReport(ProjectBase):
     duration: int
     emissions_rate: float
     emissions_count: int
+    cpu_utilization_percent: Optional[float] = None
+    gpu_utilization_percent: Optional[float] = None
+    ram_utilization_percent: Optional[float] = None
 
 
 class OrganizationBase(BaseModel):
@@ -420,6 +438,9 @@ class OrganizationReport(OrganizationBase):
     duration: int
     emissions_rate: float
     emissions_count: int
+    cpu_utilization_percent: Optional[float] = None
+    gpu_utilization_percent: Optional[float] = None
+    ram_utilization_percent: Optional[float] = None
 
 
 class Membership(BaseModel):

carbonserver/carbonserver/database/alembic/versions/20251119_add_utilization_metrics.py

@@ -0,0 +1,44 @@
+"""add_utilization_metrics_to_emissions
+
+Revision ID: 20251119_add_utilization
+Revises: 202501_f3a10
+Create Date: 2025-11-19 18:52:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "20251119_add_utilization"
+down_revision = "202501_f3a10"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    """
+    Add CPU, GPU, and RAM utilization percentage fields to emissions table.
+    These fields track the average utilization of resources during emission tracking.
+    """
+    op.add_column(
+        "emissions",
+        sa.Column("cpu_utilization_percent", sa.Float, nullable=True),
+    )
+    op.add_column(
+        "emissions",
+        sa.Column("gpu_utilization_percent", sa.Float, nullable=True),
+    )
+    op.add_column(
+        "emissions",
+        sa.Column("ram_utilization_percent", sa.Float, nullable=True),
+    )
+
+
+def downgrade():
+    """
+    Remove CPU, GPU, and RAM utilization percentage fields from emissions table.
+    """
+    op.drop_column("emissions", "ram_utilization_percent")
+    op.drop_column("emissions", "gpu_utilization_percent")
+    op.drop_column("emissions", "cpu_utilization_percent")