跳到正文
Ephemeral Sandbox mascot — a Siamese kitten peeking out of its wooden sandbox
浏览文档

接口

可观测性 CLI 参考

检查在线健康状态、追踪、事件、资源和层栈状态。

本页内容+

运行之前

sandbox-observability-cli 提供五种只读视图。与运行时客户端不同，其沙箱选择器属于各项操作。snapshot 可省略选择器以查看集群；其他操作均要求提供。

Shell
sandbox-observability-cli help
sandbox-observability-cli help snapshot
sandbox-observability-cli snapshot

先运行 snapshot，再查询与故障相关的证据。架构指南解释这些证据背后的运行时、层栈与工作区边界。

按类别筛选操作

显示 5 / 5 项命令。

集群健康状态

检查标准化的在线可用性与活动运行时状态。

snapshot

检查在线沙箱健康状态

只读

显示一个沙箱的在线状态；省略 sandbox_id 时聚合管理器已知且处于 ready 状态的全部沙箱。

何时使用

  1. 省略 sandbox_id 查看集群聚合结果，或提供 ID 选择一条管理器记录。
  2. 每个节点都会标准化 availability，并用 errors 数组保留局部失败。
  3. 先用此操作查看在线健康状态，再按需查询遥测或资源操作。

语法

用法
sandbox-observability-cli snapshot [--sandbox-id ID]

参数

参数类型必填说明
--sandbox-id IDstring否可选的目标沙箱 ID。省略时，管理器查询全部 ready 沙箱。

示例

Shell
sandbox-observability-cli snapshot
sandbox-observability-cli snapshot --sandbox-id eos-abc

代表性结果

JSON 输出
{
  "sandboxes": [
    {
      "sandbox_id": "sbox-example",
      "lifecycle_state": "ready",
      "availability": "available",
      "sampled_at_unix_ms": 1784016000000,
      "errors": [],
      "daemon": {
        "daemon_pid": 321,
        "runtime_dir": "/run/ephemeral-os"
      },
      "resources": {
        "latest": null,
        "history": []
      },
      "workspaces": [],
      "stack": {
        "layer_count": 2,
        "layers_bytes": 4096,
        "active_leases": 0
      }
    }
  ]
}

结果约定： 指定沙箱的调用直接返回节点结构，而不是带 sandboxes 的聚合包装。

相关操作tracecgrouplayerstack

追踪与事件

将遥测折叠为 span 瀑布图或经过筛选的事实流。

trace

渲染 span 瀑布图

只读

将遥测日志折叠为某条精确 trace 或最近根 trace 的嵌套 span 瀑布图。

何时使用

  1. 使用 last 查看最近开始的根 trace，或提供精确的 trace/request ID。
  2. spans 是一组树，包含已完成的 span 数据、偏移量、子节点和事件。
  3. 未知 trace 不属于操作错误；它会返回空的 spans 数组。

语法

用法
sandbox-observability-cli trace --sandbox-id ID [--trace-id TRACE|last]

参数

参数类型必填说明
--sandbox-id IDstring是目标沙箱 ID（用于选择要查询的守护进程）。
--trace-id TRACE|laststring否；默认值 last要渲染的 trace ID；使用 'last' 表示最近的根 trace。

示例

Shell
sandbox-observability-cli trace --sandbox-id eos-abc --trace-id req-7f3
sandbox-observability-cli trace --sandbox-id eos-abc --trace-id last

代表性结果

JSON 输出
{
  "view": "trace",
  "trace": "request-uuid",
  "spans": [
    {
      "span": {
        "ts": 1784016000250,
        "trace": "request-uuid",
        "span": "d-0",
        "name": "daemon.dispatch",
        "dur_ms": 250,
        "status": "completed",
        "attrs": {
          "op": "exec_command"
        }
      },
      "offset_ms": 0,
      "children": [],
      "events": []
    }
  ]
}

结果约定： span status 为 completed、error、cancelled 或 timed_out；attrs 由具体操作决定。

相关操作eventssnapshot

events

筛选跨 trace 的领域事件

只读

将遥测日志折叠为按新到旧排列的事件流，可按精确名称、时间戳和数量筛选。

何时使用

  1. name 是精确的点分标签，例如 lease.acquired。
  2. last_n 只保留最新的匹配项；省略筛选条件则返回所有保留的事件。
  3. 每个事件都带有 trace 和 parent 标识，可继续用 trace 跟踪。

语法

用法
sandbox-observability-cli events --sandbox-id ID [--name NAME] [--since-ms MS] [--last-n N]

参数

参数类型必填说明
--sandbox-id IDstring是目标沙箱 ID（用于选择要查询的守护进程）。
--name NAMEstring否仅保留名称完全匹配的事件（例如 lease.acquired）。
--since-ms MSinteger否仅保留此 Unix 毫秒时间戳及之后的事件。
--last-n Ninteger否仅保留匹配结果中最新的 N 条事件。

示例

Shell
sandbox-observability-cli events --sandbox-id eos-abc
sandbox-observability-cli events --sandbox-id eos-abc --name lease.acquired --last-n 20

代表性结果

JSON 输出
{
  "view": "events",
  "events": [
    {
      "ts": 1784016000120,
      "trace": "request-uuid",
      "parent": "d-1",
      "name": "lease.acquired",
      "attrs": {
        "layer_id": "layer-7"
      }
    }
  ]
}

结果约定： attrs 是开放的领域事实对象，内容随事件名称变化。

相关操作trace

资源与层

检查资源采样和活动层 manifest。

cgroup

读取资源时间序列

只读

从 Docker Engine 读取沙箱 CPU、内存和 I/O 计数器，或从守护进程遥测读取工作区磁盘采样。

何时使用

  1. 使用 sandbox 范围读取 Docker CPU、内存和块 I/O 计数器。
  2. 使用工作区 ID 作为 scope，读取守护进程记录的工作区磁盘采样。
  3. 仅当选定窗口中存在之前的计数器采样时，才会出现差值。

语法

用法
sandbox-observability-cli cgroup --sandbox-id ID [--scope SCOPE] [--window-ms MS]

参数

参数类型必填说明
--sandbox-id IDstring是目标沙箱 ID（用于选择要查询的守护进程）。
--scope SCOPEstring否；默认值 sandbox资源范围：'sandbox' 或工作区 ID。
--window-ms MSinteger否；默认值 60000回溯窗口，单位为毫秒，最大为 600000。

示例

Shell
sandbox-observability-cli cgroup --sandbox-id eos-abc
sandbox-observability-cli cgroup --sandbox-id eos-abc --scope ws-1 --window-ms 60000

代表性结果

JSON 输出
{
  "view": "cgroup",
  "scope": "sandbox",
  "series": [
    {
      "ts": 1784016000000,
      "sample_delta_ms": null,
      "metrics": {
        "metrics_source": "docker_engine",
        "cpu_usec": 912345,
        "mem_cur": 67108864,
        "mem_max": 1073741824,
        "io_rbytes": 4096,
        "io_wbytes": 8192
      },
      "deltas": {}
    }
  ]
}

结果约定： 沙箱指标会把 metrics_source 标识为 docker_engine。

相关操作snapshotlayerstack

layerstack

检查活动层 manifest

只读

显示活动 manifest 中的在线层大小、租约、基础层占用和可选趋势数据。

何时使用

  1. 省略 workspace_id 返回完整的活动 manifest 和可选趋势。
  2. 提供 workspace_id 返回该会话的 lower 层和私有 upperdir 字节数。
  3. 层按 manifest 顺序返回；booked_by 和 leased_by_workspaces 描述在线使用情况。

语法

用法
sandbox-observability-cli layerstack --sandbox-id ID [--workspace-id WS] [--window-ms MS]

参数

参数类型必填说明
--sandbox-id IDstring是目标沙箱 ID（用于选择要查询的守护进程）。
--workspace-id WSstring否显示某个工作区的 lower 层和私有 upperdir。
--window-ms MSinteger否；默认值 60000层栈趋势的回溯窗口，单位为毫秒，最大为 600000。

示例

Shell
sandbox-observability-cli layerstack --sandbox-id eos-abc
sandbox-observability-cli layerstack --sandbox-id eos-abc --workspace-id ws-7

代表性结果

JSON 输出
{
  "view": "layerstack",
  "manifest_version": 7,
  "root_hash": "sha256:…",
  "active_lease_count": 1,
  "total_bytes": 16384,
  "total_allocated_bytes": 20480,
  "storage_logical_bytes": 24576,
  "storage_allocated_bytes": 28672,
  "staging_entry_count": 0,
  "layers": [
    {
      "layer_id": "layer-7",
      "bytes": 8192,
      "allocated_bytes": 12288,
      "leased_by_workspaces": 1,
      "booked_by": []
    }
  ],
  "trend": []
}

结果约定： 提供 workspace_id 时，结果结构变为 { view, workspace, mounts, upper_bytes }。

相关操作snapshotcgroup

证据与错误约定

结果是某个时刻的证据，而非事件订阅。调用之间，时间戳、偏移量和计数器都可能推进。集群快照在各节点的 errors 数组中保留局部失败，因此一个不可用沙箱不会抹去健康结果。

退出码 0 向 stdout 写入 JSON；退出码 1 向 stderr 写入网关或操作错误；退出码 2 表示本地语法、校验或配置失败。

18 个结果