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

接口

可观测性 MCP 工具

调用五项只读可观测性工具并解读其结构化证据。

本页内容+

调用之前

使用 sandbox-mcp --set observability 启动一个 stdio 服务器。这五项工具均为只读。snapshot 接受可选的 sandbox_id；其他四项必须提供。

服务器进程
sandbox-mcp --set observability

先查询 snapshot，再缩小到 trace、事件、资源或层证据。架构指南解释这些证据背后的运行时与层栈边界。

按类别筛选操作

显示 5 / 5 项工具。

集群健康状态

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

snapshot

检查在线沙箱健康状态

只读

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

何时使用

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

工具参数

属性类型必填说明
sandbox_idstring否可选的目标沙箱 ID。省略时，管理器查询全部 ready 沙箱。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "snapshot",
    "arguments": {}
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "可选的目标沙箱 ID。省略时，管理器查询全部 ready 沙箱。"
    }
  },
  "required": [],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "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
          }
        }
      ]
    },
    "isError": false
  }
}

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

相关操作tracecgrouplayerstack

追踪与事件

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

trace

渲染 span 瀑布图

只读

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

何时使用

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

工具参数

属性类型必填说明
sandbox_idstring是目标沙箱 ID（用于选择要查询的守护进程）。
trace_idstring否；默认值 last要渲染的 trace ID；使用 'last' 表示最近的根 trace。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "trace",
    "arguments": {
      "sandbox_id": "sbox-example",
      "trace_id": "last"
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "目标沙箱 ID（用于选择要查询的守护进程）。"
    },
    "trace_id": {
      "type": "string",
      "description": "要渲染的 trace ID；使用 'last' 表示最近的根 trace。",
      "default": "last"
    }
  },
  "required": [
    "sandbox_id"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "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": []
        }
      ]
    },
    "isError": false
  }
}

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

相关操作eventssnapshot

events

筛选跨 trace 的领域事件

只读

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

何时使用

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

工具参数

属性类型必填说明
sandbox_idstring是目标沙箱 ID（用于选择要查询的守护进程）。
namestring否仅保留名称完全匹配的事件（例如 lease.acquired）。
since_msinteger否仅保留此 Unix 毫秒时间戳及之后的事件。
last_ninteger否仅保留匹配结果中最新的 N 条事件。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "events",
    "arguments": {
      "sandbox_id": "sbox-example",
      "name": "lease.acquired",
      "last_n": 20
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "目标沙箱 ID（用于选择要查询的守护进程）。"
    },
    "name": {
      "type": "string",
      "description": "仅保留名称完全匹配的事件（例如 lease.acquired）。"
    },
    "since_ms": {
      "type": "integer",
      "description": "仅保留此 Unix 毫秒时间戳及之后的事件。",
      "minimum": 0
    },
    "last_n": {
      "type": "integer",
      "description": "仅保留匹配结果中最新的 N 条事件。",
      "minimum": 0
    }
  },
  "required": [
    "sandbox_id"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "view": "events",
      "events": [
        {
          "ts": 1784016000120,
          "trace": "request-uuid",
          "parent": "d-1",
          "name": "lease.acquired",
          "attrs": {
            "layer_id": "layer-7"
          }
        }
      ]
    },
    "isError": false
  }
}

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

相关操作trace

资源与层

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

cgroup

读取资源时间序列

只读

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

何时使用

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

工具参数

属性类型必填说明
sandbox_idstring是目标沙箱 ID（用于选择要查询的守护进程）。
scopestring否；默认值 sandbox资源范围：'sandbox' 或工作区 ID。
window_msinteger否；默认值 60000回溯窗口，单位为毫秒，最大为 600000。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "cgroup",
    "arguments": {
      "sandbox_id": "sbox-example",
      "scope": "sandbox",
      "window_ms": 60000
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "目标沙箱 ID（用于选择要查询的守护进程）。"
    },
    "scope": {
      "type": "string",
      "description": "资源范围：'sandbox' 或工作区 ID。",
      "default": "sandbox"
    },
    "window_ms": {
      "type": "integer",
      "description": "回溯窗口，单位为毫秒，最大为 600000。",
      "minimum": 0,
      "default": 60000
    }
  },
  "required": [
    "sandbox_id"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "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": {}
        }
      ]
    },
    "isError": false
  }
}

结果约定： 沙箱指标会把 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_idstring是目标沙箱 ID（用于选择要查询的守护进程）。
workspace_idstring否显示某个工作区的 lower 层和私有 upperdir。
window_msinteger否；默认值 60000层栈趋势的回溯窗口，单位为毫秒，最大为 600000。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "layerstack",
    "arguments": {
      "sandbox_id": "sbox-example",
      "window_ms": 60000
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "目标沙箱 ID（用于选择要查询的守护进程）。"
    },
    "workspace_id": {
      "type": "string",
      "description": "显示某个工作区的 lower 层和私有 upperdir。"
    },
    "window_ms": {
      "type": "integer",
      "description": "层栈趋势的回溯窗口，单位为毫秒，最大为 600000。",
      "minimum": 0,
      "default": 60000
    }
  },
  "required": [
    "sandbox_id"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "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": []
    },
    "isError": false
  }
}

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

相关操作snapshotcgroup

证据与结果约定

结果只代表调用时刻，并可能包含局部证据。MCP 结果包含空的 content 数组、位于 structuredContent 的网关响应和 isError。操作及传输失败使用 isError: true，并保留结构化错误 envelope 供检查。

18 个结果