feat(BA-6883): expose kernel scheduling history over GraphQL v2

jopemachine · claude · jopemachine · commit 2d50b46366a4 · 2026-07-21T16:18:42.000+09:00
Add the kernel slice of the Strawberry scheduling-history schema, mirroring the
session, deployment, and route slices:

- `adminKernelSchedulingHistories` — super-admin, system-wide
- `kernelScopedSchedulingHistories` — scoped to one kernel via `KernelScope`

The node exposes `kernel` and `session` back-references through the existing
data loaders, and `resolve_nodes` is backed by a new `kernel_history_loader`
over `batch_load_kernel_histories_by_ids`.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/changes/12989.feature.md b/changes/12989.feature.md
@@ -0,0 +1 @@
+Expose kernel scheduling history over GraphQL v2 with `adminKernelSchedulingHistories` (super-admin, system-wide) and `scopedKernelSchedulingHistories` (scoped to one kernel), alongside the existing session, deployment, and route history roots.
diff --git a/docs/manager/graphql-reference/supergraph.graphql b/docs/manager/graphql-reference/supergraph.graphql
@@ -8508,6 +8508,101 @@ enum KernelResourceAllocationOrderField
   USED @join__enumValue(graph: STRAWBERRY)
 }
 
+"""Added in 26.8.0. Kernel scheduling history record."""
+type KernelSchedulingHistory implements Node
+  @join__implements(graph: STRAWBERRY, interface: "Node")
+  @join__type(graph: STRAWBERRY)
+{
+  """The Globally Unique ID of this object"""
+  id: ID!
+  kernelId: ID!
+  sessionId: ID!
+  phase: String!
+  fromStatus: String
+  toStatus: String
+  result: SchedulingResult!
+  errorCode: String
+  message: String
+  attempts: Int!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+
+  """Added in 26.8.0. The kernel this history record belongs to."""
+  kernel: KernelV2
+
+  """Added in 26.8.0. The session owning the kernel."""
+  session: SessionV2
+}
+
+"""Added in 26.8.0. Kernel scheduling history connection."""
+type KernelSchedulingHistoryConnection
+  @join__type(graph: STRAWBERRY)
+{
+  """Pagination data for this connection"""
+  pageInfo: PageInfo!
+
+  """Contains the nodes in this connection"""
+  edges: [KernelSchedulingHistoryEdge!]!
+  count: Int!
+}
+
+"""An edge in a connection."""
+type KernelSchedulingHistoryEdge
+  @join__type(graph: STRAWBERRY)
+{
+  """A cursor for use in pagination"""
+  cursor: String!
+
+  """The item at the end of the edge"""
+  node: KernelSchedulingHistory!
+}
+
+"""Added in 26.8.0. Filter for kernel scheduling history"""
+input KernelSchedulingHistoryFilter
+  @join__type(graph: STRAWBERRY)
+{
+  id: UUIDFilter = null
+  kernelId: UUIDFilter = null
+  sessionId: UUIDFilter = null
+  phase: StringFilter = null
+  fromStatus: [String!] = null
+  toStatus: [String!] = null
+  result: SchedulingResultFilter = null
+  errorCode: StringFilter = null
+  message: StringFilter = null
+  createdAt: DateTimeFilter = null
+  updatedAt: DateTimeFilter = null
+  AND: [KernelSchedulingHistoryFilter!] = null
+  OR: [KernelSchedulingHistoryFilter!] = null
+  NOT: [KernelSchedulingHistoryFilter!] = null
+}
+
+"""Added in 26.8.0. Order by specification for kernel scheduling history"""
+input KernelSchedulingHistoryOrderBy
+  @join__type(graph: STRAWBERRY)
+{
+  field: KernelSchedulingHistoryOrderField!
+  direction: OrderDirection! = DESC
+}
+
+"""
+Added in 26.8.0. Fields available for ordering kernel scheduling history
+"""
+enum KernelSchedulingHistoryOrderField
+  @join__type(graph: STRAWBERRY)
+{
+  CREATED_AT @join__enumValue(graph: STRAWBERRY)
+  UPDATED_AT @join__enumValue(graph: STRAWBERRY)
+}
+
+"""Added in 26.8.0. Scope for kernel scheduling history query"""
+input KernelScope
+  @join__type(graph: STRAWBERRY)
+{
+  """Kernel ID to get history for"""
+  kernelId: UUID!
+}
+
 """
 Added in 26.2.0. Represents a kernel (compute container) in Backend.AI.
 """
@@ -14709,6 +14804,9 @@ type Query
   """Added in 26.4.2. List session scheduling history (admin only)"""
   adminSessionSchedulingHistories(filter: SessionSchedulingHistoryFilter = null, orderBy: [SessionSchedulingHistoryOrderBy!] = null, before: String = null, after: String = null, first: Int = null, last: Int = null, limit: Int = null, offset: Int = null): SessionSchedulingHistoryConnection @join__field(graph: STRAWBERRY)
 
+  """Added in 26.8.0. List kernel scheduling history (superadmin only)"""
+  adminKernelSchedulingHistories(filter: KernelSchedulingHistoryFilter = null, orderBy: [KernelSchedulingHistoryOrderBy!] = null, before: String = null, after: String = null, first: Int = null, last: Int = null, limit: Int = null, offset: Int = null): KernelSchedulingHistoryConnection @join__field(graph: STRAWBERRY)
+
   """Added in 25.16.0. List all deployments (superadmin only)."""
   adminDeployments(filter: DeploymentFilter = null, orderBy: [DeploymentOrderBy!] = null, before: String = null, after: String = null, first: Int = null, last: Int = null, limit: Int = null, offset: Int = null): ModelDeploymentConnection @join__field(graph: STRAWBERRY)
 
@@ -14990,6 +15088,9 @@ type Query
   """Added in 26.2.0. Get scheduling history for a specific session."""
   sessionScopedSchedulingHistories(scope: SessionScope!, filter: SessionSchedulingHistoryFilter = null, orderBy: [SessionSchedulingHistoryOrderBy!] = null, before: String = null, after: String = null, first: Int = null, last: Int = null, limit: Int = null, offset: Int = null): SessionSchedulingHistoryConnection @join__field(graph: STRAWBERRY)
 
+  """Added in 26.8.0. Get scheduling history for a specific kernel."""
+  scopedKernelSchedulingHistories(scope: KernelScope!, filter: KernelSchedulingHistoryFilter = null, orderBy: [KernelSchedulingHistoryOrderBy!] = null, before: String = null, after: String = null, first: Int = null, last: Int = null, limit: Int = null, offset: Int = null): KernelSchedulingHistoryConnection @join__field(graph: STRAWBERRY)
+
   """Added in 26.2.0. Get scheduling history for a specific deployment."""
   deploymentScopedSchedulingHistories(scope: DeploymentScope!, filter: DeploymentHistoryFilter = null, orderBy: [DeploymentHistoryOrderBy!] = null, before: String = null, after: String = null, first: Int = null, last: Int = null, limit: Int = null, offset: Int = null): DeploymentHistoryConnection @join__field(graph: STRAWBERRY)
 
diff --git a/docs/manager/graphql-reference/v2-schema.graphql b/docs/manager/graphql-reference/v2-schema.graphql
@@ -5632,6 +5632,86 @@ enum KernelResourceAllocationOrderField {
   USED
 }
 
+"""Added in 26.8.0. Kernel scheduling history record."""
+type KernelSchedulingHistory implements Node {
+  """The Globally Unique ID of this object"""
+  id: ID!
+  kernelId: ID!
+  sessionId: ID!
+  phase: String!
+  fromStatus: String
+  toStatus: String
+  result: SchedulingResult!
+  errorCode: String
+  message: String
+  attempts: Int!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+
+  """Added in 26.8.0. The kernel this history record belongs to."""
+  kernel: KernelV2
+
+  """Added in 26.8.0. The session owning the kernel."""
+  session: SessionV2
+}
+
+"""Added in 26.8.0. Kernel scheduling history connection."""
+type KernelSchedulingHistoryConnection {
+  """Pagination data for this connection"""
+  pageInfo: PageInfo!
+
+  """Contains the nodes in this connection"""
+  edges: [KernelSchedulingHistoryEdge!]!
+  count: Int!
+}
+
+"""An edge in a connection."""
+type KernelSchedulingHistoryEdge {
+  """A cursor for use in pagination"""
+  cursor: String!
+
+  """The item at the end of the edge"""
+  node: KernelSchedulingHistory!
+}
+
+"""Added in 26.8.0. Filter for kernel scheduling history"""
+input KernelSchedulingHistoryFilter {
+  id: UUIDFilter = null
+  kernelId: UUIDFilter = null
+  sessionId: UUIDFilter = null
+  phase: StringFilter = null
+  fromStatus: [String!] = null
+  toStatus: [String!] = null
+  result: SchedulingResultFilter = null
+  errorCode: StringFilter = null
+  message: StringFilter = null
+  createdAt: DateTimeFilter = null
+  updatedAt: DateTimeFilter = null
+  AND: [KernelSchedulingHistoryFilter!] = null
+  OR: [KernelSchedulingHistoryFilter!] = null
+  NOT: [KernelSchedulingHistoryFilter!] = null
+}
+
+"""Added in 26.8.0. Order by specification for kernel scheduling history"""
+input KernelSchedulingHistoryOrderBy {
+  field: KernelSchedulingHistoryOrderField!
+  direction: OrderDirection! = DESC
+}
+
+"""
+Added in 26.8.0. Fields available for ordering kernel scheduling history
+"""
+enum KernelSchedulingHistoryOrderField {
+  CREATED_AT
+  UPDATED_AT
+}
+
+"""Added in 26.8.0. Scope for kernel scheduling history query"""
+input KernelScope {
+  """Kernel ID to get history for"""
+  kernelId: UUID!
+}
+
 """
 Added in 26.2.0. Represents a kernel (compute container) in Backend.AI.
 """
@@ -9748,6 +9828,9 @@ type Query {
   """Added in 26.4.2. List session scheduling history (admin only)"""
   adminSessionSchedulingHistories(filter: SessionSchedulingHistoryFilter = null, orderBy: [SessionSchedulingHistoryOrderBy!] = null, before: String = null, after: String = null, first: Int = null, last: Int = null, limit: Int = null, offset: Int = null): SessionSchedulingHistoryConnection
 
+  """Added in 26.8.0. List kernel scheduling history (superadmin only)"""
+  adminKernelSchedulingHistories(filter: KernelSchedulingHistoryFilter = null, orderBy: [KernelSchedulingHistoryOrderBy!] = null, before: String = null, after: String = null, first: Int = null, last: Int = null, limit: Int = null, offset: Int = null): KernelSchedulingHistoryConnection
+
   """Added in 25.16.0. List all deployments (superadmin only)."""
   adminDeployments(filter: DeploymentFilter = null, orderBy: [DeploymentOrderBy!] = null, before: String = null, after: String = null, first: Int = null, last: Int = null, limit: Int = null, offset: Int = null): ModelDeploymentConnection
 
@@ -10029,6 +10112,9 @@ type Query {
   """Added in 26.2.0. Get scheduling history for a specific session."""
   sessionScopedSchedulingHistories(scope: SessionScope!, filter: SessionSchedulingHistoryFilter = null, orderBy: [SessionSchedulingHistoryOrderBy!] = null, before: String = null, after: String = null, first: Int = null, last: Int = null, limit: Int = null, offset: Int = null): SessionSchedulingHistoryConnection
 
+  """Added in 26.8.0. Get scheduling history for a specific kernel."""
+  scopedKernelSchedulingHistories(scope: KernelScope!, filter: KernelSchedulingHistoryFilter = null, orderBy: [KernelSchedulingHistoryOrderBy!] = null, before: String = null, after: String = null, first: Int = null, last: Int = null, limit: Int = null, offset: Int = null): KernelSchedulingHistoryConnection
+
   """Added in 26.2.0. Get scheduling history for a specific deployment."""
   deploymentScopedSchedulingHistories(scope: DeploymentScope!, filter: DeploymentHistoryFilter = null, orderBy: [DeploymentHistoryOrderBy!] = null, before: String = null, after: String = null, first: Int = null, last: Int = null, limit: Int = null, offset: Int = null): DeploymentHistoryConnection
 
diff --git a/src/ai/backend/manager/api/adapters/scheduling_history/adapter.py b/src/ai/backend/manager/api/adapters/scheduling_history/adapter.py
@@ -31,6 +31,7 @@
     SessionHistoryNode,
 )
 from ai.backend.common.dto.manager.v2.scheduling_history.types import SubStepResultInfo
+from ai.backend.common.identifier.kernel_scheduling_history import KernelSchedulingHistoryID
 from ai.backend.common.identifier.replica import ReplicaID
 from ai.backend.common.types import KernelId
 from ai.backend.manager.api.adapter_options.pagination.pagination import PaginationSpec
@@ -162,6 +163,27 @@ async def batch_load_session_histories_by_ids(
         history_map = {h.id: self._session_data_to_dto(h) for h in action_result.histories}
         return [history_map.get(history_id) for history_id in ids]
 
+    async def batch_load_kernel_histories_by_ids(
+        self, ids: Sequence[KernelSchedulingHistoryID]
+    ) -> list[KernelHistoryNode | None]:
+        """Batch load kernel scheduling histories by their IDs for DataLoader use.
+
+        Returns KernelHistoryNode DTOs in the same order as the input ids list.
+        """
+        if not ids:
+            return []
+        querier = BatchQuerier(
+            pagination=OffsetPagination(limit=len(ids)),
+            conditions=[KernelSchedulingHistoryConditions.by_ids(ids)],
+        )
+        action_result = (
+            await self._processors.scheduling_history.search_kernel_history.wait_for_complete(
+                SearchKernelHistoryAction(querier=querier)
+            )
+        )
+        history_map = {h.id: self._kernel_data_to_dto(h) for h in action_result.items}
+        return [history_map.get(history_id) for history_id in ids]
+
     async def batch_load_deployment_histories_by_ids(
         self, ids: Sequence[UUID]
     ) -> list[DeploymentHistoryNode | None]:
diff --git a/src/ai/backend/manager/api/gql/data_loader/data_loaders.py b/src/ai/backend/manager/api/gql/data_loader/data_loaders.py
@@ -9,6 +9,7 @@
 from ai.backend.common.identifier.app_config_allow_list import AppConfigAllowListID
 from ai.backend.common.identifier.app_config_definition import AppConfigDefinitionID
 from ai.backend.common.identifier.deployment import DeploymentID
+from ai.backend.common.identifier.kernel_scheduling_history import KernelSchedulingHistoryID
 from ai.backend.common.types import AgentId, ImageID, KernelId, SessionId
 from ai.backend.manager.data.permission.id import ObjectId
 
@@ -102,6 +103,7 @@
     )
     from ai.backend.manager.api.gql.scheduling_history.types import (  # pants: no-infer-dep
         DeploymentHistory,
+        KernelSchedulingHistoryGQL,
         RouteHistory,
         SessionSchedulingHistory,
     )
@@ -718,6 +720,24 @@ async def load_fn(ids: list[uuid.UUID]) -> list[SessionSchedulingHistory | None]
 
         return DataLoader(load_fn=load_fn)
 
+    @cached_property
+    def kernel_history_loader(
+        self,
+    ) -> DataLoader[KernelSchedulingHistoryID, KernelSchedulingHistoryGQL | None]:
+        adapter = self._adapters.scheduling_history
+
+        async def load_fn(
+            ids: list[KernelSchedulingHistoryID],
+        ) -> list[KernelSchedulingHistoryGQL | None]:
+            from ai.backend.manager.api.gql.scheduling_history.types import (  # pants: no-infer-dep
+                KernelSchedulingHistoryGQL as KSH,
+            )
+
+            dtos = await adapter.batch_load_kernel_histories_by_ids(ids)
+            return [KSH.from_pydantic(dto) if dto is not None else None for dto in dtos]
+
+        return DataLoader(load_fn=load_fn)
+
     @cached_property
     def deployment_history_loader(
         self,
diff --git a/src/ai/backend/manager/api/gql/scheduling_history/__init__.py b/src/ai/backend/manager/api/gql/scheduling_history/__init__.py
@@ -2,15 +2,18 @@
 
 from .resolver import (
     DeploymentHistoryConnection,
+    KernelSchedulingHistoryConnectionGQL,
     RouteHistoryConnection,
     SessionSchedulingHistoryConnection,
     admin_deployment_histories,
+    admin_kernel_scheduling_histories,
     admin_route_histories,
     admin_session_scheduling_histories,
     deployment_histories,
     deployment_scoped_scheduling_histories,
     route_histories,
     route_scoped_scheduling_histories,
+    scoped_kernel_scheduling_histories,
     session_scheduling_histories,
     session_scoped_scheduling_histories,
 )
@@ -19,6 +22,10 @@
     DeploymentHistoryFilter,
     DeploymentHistoryOrderBy,
     DeploymentScope,
+    KernelSchedulingHistoryFilterGQL,
+    KernelSchedulingHistoryGQL,
+    KernelSchedulingHistoryOrderByGQL,
+    KernelScopeGQL,
     RouteHistory,
     RouteHistoryFilter,
     RouteHistoryOrderBy,
@@ -37,29 +44,36 @@
     # Types
     "SubStepResultGQL",
     "SessionSchedulingHistory",
+    "KernelSchedulingHistoryGQL",
     "DeploymentHistory",
     "RouteHistory",
     # Filters
     "SessionSchedulingHistoryFilter",
     "SessionSchedulingHistoryOrderBy",
+    "KernelSchedulingHistoryFilterGQL",
+    "KernelSchedulingHistoryOrderByGQL",
     "DeploymentHistoryFilter",
     "DeploymentHistoryOrderBy",
     "RouteHistoryFilter",
     "RouteHistoryOrderBy",
     # Scope types (added in 26.2.0)
     "SessionScope",
+    "KernelScopeGQL",
     "DeploymentScope",
     "RouteScope",
     # Connections
     "SessionSchedulingHistoryConnection",
+    "KernelSchedulingHistoryConnectionGQL",
     "DeploymentHistoryConnection",
     "RouteHistoryConnection",
     # Queries - Admin
     "admin_session_scheduling_histories",
+    "admin_kernel_scheduling_histories",
     "admin_deployment_histories",
     "admin_route_histories",
     # Queries - Scoped (added in 26.2.0)
     "session_scoped_scheduling_histories",
+    "scoped_kernel_scheduling_histories",
     "deployment_scoped_scheduling_histories",
     "route_scoped_scheduling_histories",
     # Queries - Legacy (deprecated)
diff --git a/src/ai/backend/manager/api/gql/scheduling_history/resolver.py b/src/ai/backend/manager/api/gql/scheduling_history/resolver.py
diff --git a/src/ai/backend/manager/api/gql/scheduling_history/types.py b/src/ai/backend/manager/api/gql/scheduling_history/types.py
diff --git a/src/ai/backend/manager/api/gql/schema.py b/src/ai/backend/manager/api/gql/schema.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Expose kernel scheduling history over GraphQL v2 with `adminKernelSchedulingHistories` (super-admin, system-wide) and `scopedKernelSchedulingHistories` (scoped to one kernel), alongside the existing session, deployment, and route history roots.