> For the complete documentation index, see [llms.txt](https://documentation.alluxio.io/ee-ai-cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.alluxio.io/ee-ai-cn/reference/collectinfo-crd.md).

# CollectInfo 参考

`CollectInfo` 是驱动 Alluxio 诊断信息收集的 Kubernetes 自定义资源。创建一个 `CollectInfo` 就是在告诉 Operator 的 doctor controller：从集群里**收集什么**、 **什么时候**收集，以及可选地**上传到哪里**。

只有在需要修改默认行为时才需要这一页。如果只是想生成一个诊断包发给 Alluxio 支持 团队，请按[使用 Doctor 收集诊断快照](https://documentation.alluxio.io/ee-ai-cn/reference/pages/QoKzJ5ZPp2ITNgqFe7Ml#id-4.-shi-yong-doctor-shou-ji-zhen-duan-kuai-zhao) 操作——默认配置会收集过去一天的全部内容，无需任何额外设置。

每次运行会在 doctor-controller Pod 的 `/data/doctor` 目录下生成一个 `.tar.gz` 归档。命名规则和下载方式见 [查找并下载诊断包](/ee-ai-cn/administration/troubleshooting-alluxio.md#cha-zhao-bing-xia-zai-zhen-duan-bao)。

## 完整示例

下面每个字段都是可选的。这个示例把它们全部列出以展示结构；实际使用的 `CollectInfo` 通常短得多。

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: CollectInfo
metadata:
  name: example-doctor
  # 必须与 Alluxio 集群位于同一命名空间
  namespace: alx-ns
spec:
  # 配置定时收集
  scheduled:
    # false：立即执行一次；true：启用定时执行
    enabled: false
    # 仅在 enabled: true 时生效
    cron: "0 0 * * *"
    # 仅在 enabled: true 时生效
    timeZone: "Asia/Shanghai"
    # 仅在 enabled: true 时生效，收集结果的保留时长
    expiration: "720h"

  # 要收集的信息类型
  type:
    - all

  # 日志收集配置
  logs:
    # 收集过去 1 小时（3600 秒）的日志
    # 注意：留空则默认收集过去 1 天（86400 秒）的日志
    sinceSeconds: 3600
    # tail: 1000 # 或者用 tail 收集最后 1000 行
    # sinceTime: "2025-11-12T06:00:00Z" # 或者用 sinceTime 收集某个时间点之后的日志

  # 监控指标收集配置
  metrics:
    # 收集过去 24 小时的指标
    duration: 24h
    # 采样间隔 5 分钟
    step: 5m

  # （可选）上传配置
  # upload:
  #   account: test
  #   productionId: xxx # 可选
  #   awsKey: <alluxio-provided-key>
  #   awsSecret: <alluxio-provided-secret>
```

## `spec.scheduled`

控制这次收集是执行一次还是按计划重复执行。

**决定开关的是 `cron`。** 没有设置 `spec.scheduled.cron` 的 `CollectInfo` 在被创建后 只运行一次；设置了 `cron` 的则按该计划重复运行。

| 字段           | 类型      | 默认值            | 说明                                                                                                                                                                          |
| ------------ | ------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cron`       | string  | —              | 定时任务的 Cron 表达式。**它是否存在**决定了这次收集是否重复执行。例如 `"0 0 * * *"`（每天零点）。参见 [Kubernetes Cron 语法](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#schedule-syntax)。 |
| `timeZone`   | string  | —              | 解析 `cron` 表达式所用的时区。例如 `"Asia/Shanghai"`。参见 [Kubernetes 时区](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#time-zones)。                                |
| `expiration` | string  | `4320h`（180 天） | 归档保留多久后自动清理。使用 [Go duration 格式](https://pkg.go.dev/time#ParseDuration)。                                                                                                     |
| `enabled`    | boolean | `false`        | **已废弃**——请改用 `cron` 是否存在来控制。它不再决定收集是否重复执行，只影响 `metrics.step` 的默认值。                                                                                                          |

{% hint style="info" %}
Operator 创建的每个集群都已自带一个 `CollectInfo`，在每天 UTC 零点运行，`type: all`， 日志窗口 24 小时，归档保留 180 天。用 `kubectl -n <集群命名空间> get collectinfo` 查看你自己的。
{% endhint %}

## `spec.type`

选择要收集哪些类别的数据。不填 `type` 等同于 `all`。

| 取值               | 收集内容                                                                                  | 在归档中的位置             |
| ---------------- | ------------------------------------------------------------------------------------- | ------------------- |
| `all`            | 下面的全部内容。这是默认值。                                                                        | —                   |
| `config`         | 解析后的 Alluxio 与 gateway 配置、自定义配置、完整属性导出，以及 `AlluxioCluster` manifest。                  | `config/`           |
| `dynamic-config` | 存放在 etcd 中、并通过 coordinator 读回的集群状态：license、挂载表、配额、worker 节点、优先级、TTL 规则、缓存过滤器以及虚拟路径映射。 | `etcd/`             |
| `hardware`       | Kubernetes 节点的 CPU、内存和磁盘信息，以及集群和 operator 命名空间下的 Pod spec。                            | `hardware/`         |
| `job-history`    | Job service 历史记录，包括 load 和 free 作业。                                                   | `job-history/`      |
| `logs`           | Coordinator、worker、FUSE Pod 及其他组件的容器日志。                                               | `logs/<namespace>/` |
| `meta`           | 本次收集任务自身的元信息——何时执行、针对哪个集群，以及实际生效的日志与指标窗口。                                             | `meta/`             |
| `metrics`        | 从 Alluxio 组件抓取的 Prometheus 指标。                                                        | `metrics/`          |

{% hint style="warning" %}
无法识别的取值会被**静默跳过**——doctor controller 只打印一条 warning，归档照常 生成但缺少该类别。特别注意 `etcd` **不是**合法取值；etcd 中的状态由 `dynamic-config` 收集。
{% endhint %}

`metrics` 是最慢、产出文件最大的类别。如果只需要日志和配置，把它从 `type` 里去掉。

## `spec.logs`

限定每个组件贡献多少日志历史。该字段参照 Kubernetes [`PodLogOptions`](https://pkg.go.dev/k8s.io/api/core/v1#PodLogOptions) 设计。

| 字段             | 类型      | 说明                                                   |
| -------------- | ------- | ---------------------------------------------------- |
| `tail`         | integer | 收集每个容器日志的最后 N 行。例如 `1000`。                           |
| `sinceSeconds` | integer | 收集从 N 秒前到现在的日志。例如 `3600`（过去 1 小时）。                   |
| `sinceTime`    | string  | 收集某个 RFC3339 绝对时间点之后的日志。例如 `"2025-11-12T06:00:00Z"`。 |

同时设置多个时的优先级：

1. `tail` 优先级最高。设置了 `tail` 时，`sinceSeconds` 和 `sinceTime` 都会被忽略。
2. 未设置 `tail` 时，`sinceSeconds` 或 `sinceTime` 生效——两者只能设置一个。
3. `logs` 缺省或为空时，默认收集过去一天（86400 秒）。

如果要排查的问题是一天以前开始的，务必调大这个窗口；默认值会静默截断更早的日志。

## `spec.metrics`

限定 Prometheus 指标的时间范围。仅当 `type` 中包含 `metrics` 时才会读取。

| 字段         | 类型     | 默认值                  | 说明                    |
| ---------- | ------ | -------------------- | --------------------- |
| `duration` | string | `24h`                | 从当前时间往回收集多长时间。        |
| `step`     | string | 一次性运行 `5m`，定时运行 `2h` | 采样间隔。间隔越小分辨率越高，归档也越大。 |

## `spec.upload`

把生成的归档上传到 Alluxio 维护的 S3 存储桶，这样支持团队无需你手动传输文件即可 获取。凭证由 Alluxio 提供——该配置块不能用于你自己的存储桶。

| 字段             | 类型     | 必填 | 说明                                        |
| -------------- | ------ | -- | ----------------------------------------- |
| `account`      | string | 是  | Alluxio 提供的账号标识。                          |
| `productionId` | string | 否  | **已废弃**——production ID 现在会从 tarball 自动检测。 |
| `awsKey`       | string | 是  | Alluxio 提供的 AWS access key。               |
| `awsSecret`    | string | 是  | Alluxio 提供的 AWS secret key。               |

不配置 `upload`（默认行为）时，归档只保留在 doctor-controller Pod 内，需要你自行 取回。

## `spec.alluxioCluster`

指定要从哪些 Alluxio 集群收集，是一组 `name` 和 `namespace` 的列表。当 `CollectInfo` 与集群不在同一命名空间，或者一次收集需要覆盖多个集群时，需要设置它。

```yaml
spec:
  alluxioCluster:
    - name: alluxio-cluster
      namespace: alx-ns
```

## 相关文档

* [故障排除](/ee-ai-cn/administration/troubleshooting-alluxio.md) —— 使用该资源的任务导向指南
* [监控指标](/ee-ai-cn/reference/metrics.md) —— `spec.metrics` 采样的指标
* [在 Kubernetes 上安装](/ee-ai-cn/start/installing-on-kubernetes.md) —— 部署提供 doctor controller 的 Operator