Compute Session Monitoring

As of Backend.AI v20.03, compute sessions are composed of one or more containers, while interactions with sessions only occur with the master container when using REST APIs. The GraphQL API allows users and admins to check details of sessions and their belonging containers.

Changed in version v5.20191215.

Query Schema

ComputeSession provides information about the whole session, including user-requested parameters when creating sessions.

type ComputeSession {
  # identity and type
  id: UUID
  name: String
  type: String
  id: UUID
  tag: String

  # image
  image: String
  registry: String
  cluster_template: String  # reserved for future release

  # ownership
  domain_name: String
  group_name: String
  group_id: UUID
  user_email: String
  user_id: UUID
  access_key: String
  created_user_email: String  # reserved for future release
  created_user_uuid: UUID     # reserved for future release

  # status
  status: String
  status_changed: DateTime
  status_info: String
  created_at: DateTime
  terminated_at: DateTime
  startup_command: String
  result: String

  # resources
  resource_opts: JSONString
  scaling_group: String
  service_ports: JSONString   # only available in master
  mounts: List[String]            # shared by all kernels
  occupied_slots: JSONString  # ResourceSlot; sum of belonging containers

  # statistics
  num_queries: BigInt

  # owned containers (aka kernels)
  containers: List[ComputeContainer]  # full list of owned containers

  # pipeline relations
  dependencies: List[ComputeSession]  # full list of dependency sessions
}

The sessions may be queried one by one using compute_sesssion field on the root query schema, or as a paginated list using compute_session_list.

type Query {
  compute_session(
    id: UUID!,
  ): ComputeSession

  compute_session_list(
    limit: Int!,
    offset: Int!,
    order_key: String,
    order_asc: Boolean,
    domain_name: String,  # super-admin can query sessions in any domain
    group_id: String,     # domain-admins can query sessions in any group
    access_key: String,   # admins can query sessions of other users
    status: String,
  ): PaginatedList[ComputeSession]
}

ComputeContainer provides information about individual containers that belongs to the given session. Note that the client must assume that id is different from container_id, because agents may be configured to use non-Docker backends.

Note

The container ID in the GraphQL queries and REST APIs are different from the actual Docker container ID. The Docker container IDs can be queried using container_id field of ComputeContainer objects. If the agents are configured to using non-Docker-based backends, then container_id may also be completely arbitrary identifiers.

type ComputeContainer {
  # identity
  id: UUID
  role: String      # "master" is reserved, other values are defined by cluster templates
  hostname: String  # used by sibling containers in the same session
  session_id: UUID

  # image
  image: String
  registry: String

  # status
  status: String
  status_changed: DateTime
  status_info: String
  created_at: DateTime
  terminated_at: DateTime

  # resources
  agent: String               # super-admin only
  container_id: String
  resource_opts: JSONString
  # NOTE: mounts are same in all containers of the same session.
  occupied_slots: JSONString  # ResourceSlot

  # statistics
  live_stat: JSONString
  last_stat: JSONString
}

In the same way, the containers may be queried one by one using compute_container field on the root query schema, or as a paginated list using compute_container_list for a single session.

Note

The container ID of the master container of each session is same to the session ID.

type Query {
  compute_container(
    id: UUID!,
  ): ComputeContainer

  compute_container_list(
    limit: Int!,
    offset: Int!,
    session_id: UUID!,
    role: String,
  ): PaginatedList[ComputeContainer]
}

Query Example

query(
  $limit: Int!,
  $offset: Int!,
  $ak: String,
  $status: String,
) {
  compute_session_list(
    limit: $limit,
    offset: $offset,
    access_key: $ak,
    status: $status,
  ) {
    total_count
    items {
      id
      name
      type
      user_email
      status
      status_info
      status_updated
      containers {
        id
        role
        agent
      }
    }
  }
}

API Parameters

Using the above GraphQL query, clients may send the following JSON object as the request:

{
  "query": "...",
  "variables": {
    "limit": 10,
    "offset": 0,
    "ak": "AKIA....",
    "status": "RUNNING"
  }
}

API Response

{
  "compute_session_list": {
    "total_count": 1,
    "items": [
      {
        "id": "12c45b55-ce3c-418d-9c58-223bbba307f1",
        "name": "mysession",
        "type": "interactive",
        "user_email": "user@lablup.com",
        "status": "RUNNING",
        "status_info": null,
        "status_updated": "2020-02-16T15:47:28.997335+00:00",
        "containers": [
          {
            "id": "12c45b55-ce3c-418d-9c58-223bbba307f1",
            "role": "master",
            "agent": "i-agent01"
          },
          {
            "id": "12c45b55-ce3c-418d-9c58-223bbba307f2",
            "role": "slave",
            "agent": "i-agent02"
          },
          {
            "id": "12c45b55-ce3c-418d-9c58-223bbba307f3",
            "role": "slave",
            "agent": "i-agent03"
          }
        ]
      }
    ]
  }
}