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

# 可观测性

> Cyberun 平台如何向运维方暴露日志、追踪与(正在编写中的)指标。

Cyberun 部署通过运维方已在使用的标准机制暴露可观测性 —— 今天是结构化日志与 OpenTelemetry 追踪,公开的指标目录与审计日志投递正在编写中。

## 日志

每个云侧组件(API 服务器、网关、许可证服务)都发出结构化日志。两项设置控制输出:

| 键               | 取值                            | 备注                          |
| --------------- | ----------------------------- | --------------------------- |
| `logger.level`  | `debug`、`info`、`warn`、`error` | 默认 `info`。按环境设置。            |
| `logger.format` | `text`、`json`                 | 开发默认 `text`;生产聚合器使用 `json`。 |

环境变量覆盖遵循标准 `CYBERUN_<SECTION>_<KEY>` 映射 —— `CYBERUN_LOGGER_LEVEL`、`CYBERUN_LOGGER_FORMAT`。

### 结构化字段

日志在适用之处使用以下一致的字段。聚合器可以基于其中任意字段建立索引:

* `team_id` —— 请求的团队范围(当属于团队范围时)。
* `user_id` —— 发起请求的用户,适用于用户发起的操作。
* `task_id`、`agent_id`、`workflow_id` —— 资源引用。
* `credential_kind` —— `integration`、`agent` 或 `device`;从不记录凭证值。
* `feature` —— 当请求因功能门控被拒时,所要求的许可证功能。
* `error` —— 序列化的错误链。

凭证值、JWT、刷新令牌、许可证素材、webhook 签名密钥与 OAuth 客户端密钥都不会被记录。

### 日志来源

| 来源        | 组件                | 用于                                |
| --------- | ----------------- | --------------------------------- |
| HTTP 请求日志 | API 服务器(HTTP 中间件) | 每个请求的延迟、状态、路由耗时。                  |
| 网关事件日志    | 代理网关              | 代理连接/断开、任务派发、隧道生命周期。              |
| 代理进程日志    | 每代理进程 + 运行时子进程    | 任务执行细节;ComfyUI / Nerfstudio 标准输出。 |
| 仓库层日志     | DB 层              | 慢速 / 失败路径上的查询耗时。                  |
| 许可证日志     | 许可证服务 + 许可证中间件    | 许可证加载、刷新、门控拒绝。                    |

## 追踪(OpenTelemetry)

OTLP 导出已内置,默认关闭。按部署启用:

| 键                         | 默认值              | 备注                        |
| ------------------------- | ---------------- | ------------------------- |
| `telemetry.enabled`       | `false`          | 生产时启用。                    |
| `telemetry.service_name`  | `cyberun`        | 在采集多服务追踪时,按进程覆盖。          |
| `telemetry.otlp_endpoint` | `localhost:4317` | 你的采集器地址。                  |
| `telemetry.otlp_insecure` | `true`(开发)       | 生产请置为 `false`;采集器应终止 TLS。 |
| `telemetry.sample_ratio`  | `1.0`            | 请求量大时,生产可调低。              |

启用后,API 服务器、网关与代理都会为 HTTP 请求处理、任务派发、隧道生命周期与运行时调用发出 span。把端点指向任何兼容 OTLP 的采集器(Jaeger、Tempo、Honeycomb、Datadog、Lightstep 等)即可。

## 指标

一等的 Prometheus / OpenMetrics 端点,以及指标名、标签与推荐告警的文档,正在编写中。在它发布之前,运维方通常从下列来源派生运维信号:

* HTTP 请求日志中的状态与延迟字段(聚合器侧,例如 Loki / OpenSearch)。
* OTLP 追踪数据(采集器侧)。
* 许可证校验器的续订事件。

如果你在正式端点上线之前就需要为某个监控目标提供显式的指标点,请通过 [sales@cyberun.cloud](mailto:sales@cyberun.cloud) 联系我们 —— 我们可以就已暴露的过渡性接入点给出建议。

## 任务事件流

任务进度被发布到内部事件总线(`task.*` 事件),API 服务器以两种形式转发给客户端:

* **HTTP Server-Sent Events**,位于 `GET /api/v1/r/tasks/{taskId}/events` —— 客户端订阅的官方线上格式。
* **MCP `notifications/progress`** 事件,通过 `stream_task_events` 工具(Cloud MCP)。

将你自己的后端以流式消费形式订阅事件总线属于运维方议题;具体模式正在作为公开部署指南的一部分编写中。今天,定制订阅方走合作伙伴通道。

## 健康检查

每个云侧进程都暴露一个基础的存活探针端点。规范化路径、期望载荷与告警建议会在公开部署指南中一并发布。在此之前,把它们当作标准 HTTP `200`-或-非 来对待;正式的健康检查规范正在编写中。

## 审计日志

访问决策(登录、凭证颁发、角色变更、许可证门控拒绝)出现在结构化日志流中,并附带上述字段集合。一个专用的审计日志目的地(独立接收端、独立保留期、防篡改)正在为合规驱动的部署编写中。

## 另见

* [架构](/zh/platform/architecture) —— 发出上述信号的组件。
* [要求](/zh/platform/requirements) —— 依赖对可观测性的贡献(DB 查询日志、消息总线保留)。
* [许可证管理](/zh/platform/license) —— 许可证事件浮现在与其它内容同一条日志流中。