> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenTelemetry

> 查阅 PPIO Agent Sandbox 通过 OTLP/HTTP 导出 CPU、内存、磁盘、组织配额、用量以及生命周期事件的说明，为对接 OpenTelemetry Collector 或可观测性平台提供参考。

Sandbox 遥测通过 OpenTelemetry 协议（OTLP）将资源指标、组织配额与用量，以及生命周期事件导出到任意兼容的接收端。

## 配置 OTLP 端点

> [!WARNING]
>
> **权限与团队作用范围**
>
> * 只有具有 **Owner** 或 **Admin** 角色的团队成员可以管理 OpenTelemetry 配置。
> * 配置作用于**整个团队**，而非仅对保存配置的成员生效。
> * `user_uuid` 属性表示**团队所有者账号 UUID**，不是当前成员的账号 UUID。
> * 授权管理员可以读取**完整的 Header 值**，包括其中的鉴权凭据。请将这些值视为对授权管理员可见的敏感信息。

1. 打开 [Sandbox 控制台设置](https://ppio.com/sandbox/console/settings)，找到 **OpenTelemetry** 区域。
2. 在 **OTLP Endpoint** 中填入 OpenTelemetry Collector 或可观测性平台提供的基础 URL。
3. 如果接收端需要鉴权或其他请求头，在 **Headers** 中添加，最多可配置 32 个。
4. 打开 **Enable export**，点击 **Save**。

![Sandbox 控制台 OpenTelemetry 设置入口](https://mintcdn.com/ppinfra/nclK0fRAlnwd416T/images/sandbox/opentelemetry-settings.png?fit=max\&auto=format\&n=nclK0fRAlnwd416T\&q=85\&s=ba263f0f3836d94e56898a0ed3fe0953)

## 可用遥测数据

| 数据 | 可监控内容 | OTLP 信号 |
| - | - | - |
| Sandbox 资源 | 分配的 CPU 核数、CPU 利用率、分配和已用内存与磁盘 | Metrics |
| 组织配额与用量 | 并发 Sandbox、CPU 和内存用量，以及组织与单个 Sandbox 的限制 | Metrics |
| 生命周期事件 | `create`、`pause`、`resume`、`delete` 等操作，包含状态、耗时和错误 | Logs |

本页介绍可用的指标和事件信息。如果希望直接通过 SDK 或 CLI 查询数据，参见 [Sandbox 指标](https://ppio.com/docs/sandbox/sandbox-metrics.md) 和 [Sandbox 事件](https://ppio.com/docs/sandbox/sandbox-events.md)。

## Resource 属性

每个 Resource 都包含以下字符串属性：

| 属性 | 说明 |
| - | - |
| `service.name` | 标识遥测类别：`ppio.sandbox.events`、`ppio.sandbox.metrics` 或 `ppio.sandbox.organization`。 |
| `ppio.sandbox.user_uuid` | 团队所有者账号 UUID。 |

> [!NOTE]
>
> 下文所有指标名与业务属性使用默认前缀 `ppio.sandbox.`。实际前缀由服务端配置决定。

## Sandbox 资源指标

资源指标使用 `service.name = ppio.sandbox.metrics`。六个指标全部为 `Gauge`，表示采样时刻的值，每个数据点附带采样时间戳。

| 指标名 | 单位 | 说明 |
| - | - | - |
| `ppio.sandbox.cpu_core_total` | `{core}` | 分配的 CPU 核数。 |
| `ppio.sandbox.cpu_utilization` | `1` | CPU 利用率，沿用源数值，不做换算。 |
| `ppio.sandbox.mem_total_mb` | `MB` | 分配内存。 |
| `ppio.sandbox.mem_use_mb` | `MB` | 已用内存。 |
| `ppio.sandbox.disk_total_mb` | `MB` | 分配磁盘。 |
| `ppio.sandbox.disk_use_mb` | `MB` | 已用磁盘。 |

CPU 利用率导出时不乘以或除以 100，不要仅凭单位 `1` 推断值的范围为 0–1。内存和磁盘指标的单位字符串为 `MB`，但数值由字节除以 `1024²` 得到，实际为 MiB。

### 资源指标属性

每个数据点包含以下字符串属性：

| 属性 | 说明 |
| - | - |
| `ppio.sandbox.event_id` | 与采样关联的事件标识。 |
| `ppio.sandbox.region_id` | Region 标识。 |
| `ppio.sandbox.template_id` | 模板标识。 |
| `ppio.sandbox.sandbox_id` | Sandbox 标识。 |
| `ppio.sandbox.user_uuid` | 团队所有者账号 UUID。 |
| `ppio.sandbox.member_uuid` | 源记录中的成员标识。 |
| `ppio.sandbox.cluster_id` | 集群标识。 |

使用这些属性可以按 Sandbox 筛选，或在模板、Region 之间对比资源使用。当对应的 total 大于 0 时，内存利用率可按 `mem_use_mb / mem_total_mb` 计算，磁盘利用率可按 `disk_use_mb / disk_total_mb` 计算。

## 组织配额与用量

组织指标使用 `service.name = ppio.sandbox.organization`。所有指标均为 `Gauge` 类型，取整数值，每个数据点附带采集时间戳。

### 配额

| 指标名 | 单位 | 说明 |
| - | - | - |
| `ppio.sandbox.limit.concurrent_instances` | `{sandbox}` | 最大并发 Sandbox 数。 |
| `ppio.sandbox.limit.concurrent_cpu_core` | `{core}` | 最大并发 CPU 总核数。 |
| `ppio.sandbox.limit.concurrent_mem_mb` | `MB` | 最大并发内存总量。 |
| `ppio.sandbox.limit.disk_mb` | `MB` | 单个 Sandbox 可用磁盘。 |
| `ppio.sandbox.limit.max_length_hours` | `h` | 单个 Sandbox 最大持续时长。 |
| `ppio.sandbox.limit.max_ram_mb` | `MB` | 单个 Sandbox 最大内存。 |
| `ppio.sandbox.limit.max_vcpu` | `{core}` | 单个 Sandbox 最大 CPU 核数。 |

### 当前用量

| 指标名 | 单位 | 说明 |
| - | - | - |
| `ppio.sandbox.usage.concurrent_instances` | `{sandbox}` | 当前并发 Sandbox 数。 |
| `ppio.sandbox.usage.concurrent_cpu_core` | `{core}` | 当前并发 CPU 总核数。 |
| `ppio.sandbox.usage.concurrent_mem_mb` | `MB` | 当前并发内存总量。 |

将每个并发用量指标与对应的限制对比，即可监控剩余容量。有关 Sandbox 限制的更多信息，参见 [配额与限制](https://ppio.com/docs/sandbox/quota-limits.md)。

### 组织指标属性

每个数据点包含以下字符串属性：

| 属性 | 说明 |
| - | - |
| `ppio.sandbox.region_id` | Region 标识。 |
| `ppio.sandbox.cluster_id` | 组织指标中当前填入 Region 标识。 |
| `ppio.sandbox.user_uuid` | 团队所有者账号 UUID。 |
| `ppio.sandbox.member_uuid` | 配置中的成员标识，可能为空。 |

当某个可选源值缺失时，发送端会跳过对应的 `limit.concurrent_cpu_core`、`limit.concurrent_mem_mb` 或 `usage.concurrent_mem_mb` 数据点。不要把缺失的点当作 0 处理。其他指标值为 0 时仍会发送。

## 生命周期事件

生命周期事件使用 `service.name = ppio.sandbox.events`，以 Logs 形式导出，不是 Metrics。它们描述 Sandbox 的生命周期操作，而不是命令的 stdout 或 stderr。如需获取命令输出，参见 [命令流式输出](https://ppio.com/docs/sandbox/commands-streaming.md)。

### 事件信息

每条事件包含时间戳、严重级别、消息和下文列出的属性。

* **事件时间**：事件发生的时间。源时间戳缺失时取当前时间。
* **观察时间**：该批事件准备导出的时间。
* **严重级别**：状态为 `fail` 或 HTTP 状态码 ≥ 500 时为 `ERROR`，否则为 `INFO`。Severity Text 为事件状态，如 `success` 或 `fail`。
* **消息**：`sandbox lifecycle event: <event_name>`。

### 事件属性

| 属性 | 类型 | 说明 |
| - | - | - |
| `ppio.sandbox.event_id` | String | 事件标识。 |
| `ppio.sandbox.region_id` | String | Region 标识。 |
| `ppio.sandbox.template_id` | String | 模板标识。 |
| `ppio.sandbox.template_name` | String | 模板名称。 |
| `ppio.sandbox.sandbox_id` | String | Sandbox 标识。 |
| `ppio.sandbox.user_uuid` | String | 团队所有者账号 UUID。 |
| `ppio.sandbox.member_uuid` | String | 源记录中的成员标识。 |
| `ppio.sandbox.event_name` | String | 事件名称，如 `create`、`pause`、`resume`、`delete`。 |
| `ppio.sandbox.state` | String | 事件状态。 |
| `ppio.sandbox.error_msg` | String | 错误信息。 |
| `ppio.sandbox.latency_ms` | Integer | 请求耗时，毫秒。 |
| `ppio.sandbox.status_code` | Integer | HTTP 状态码。 |

按 `sandbox_id` 过滤事件可以排查单个 Sandbox 的问题；使用 `event_name`、`state`、`status_code` 和 `error_msg` 定位失败的操作；使用 `latency_ms` 查看请求耗时。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.