# 诊断快照

为诊断 Alluxio 中的问题或故障，需要生成一个包含集群各种信息的诊断快照（diagnostic snapshot)，该快照可通过运行 `collectinfo` 功能获取。

`collectinfo` 结果包含以下类型的信息：

* config: Alluxio `conf/`目录中的配置文件.
* hardware: 运行 coordinator、worker、fuse 和 operator 组件的 K8s 节点的 CPU、内存和硬件规格
* etcd: Alluxio 集群中存储到etcd中的信息，包括挂载点（mount）、配额（quota）、优先级（priority）、有效时间 (TTL）、worker 及许可证信息。
* logs: coordinator、worker、fuse 和 operator 组件的日志。支持 tail 日志，可显示日志末尾的指定行数。
* metrics: 支持设置持续时间(duration)和步长(step)，以定义指标的时间范围和采样间隔。
* job history: Alluxio 集群中的 load、free 和 copy 任务历史记录, 包括任务的详细信息和状态。

## 系统要求

首先确认 `operator` 启动成功，并且有 `alluxio-collectinfo-controller` 在运行。下面是 `operator` 的信息，可以看到 `alluxio-collectinfo-controller` 在运行。如果 `alluxio-collectinfo-controller` 不存在，表明当前使用的 `operator` 版本不支持 `collectinfo` 功能，请升级 `operator` 版本。

```console
kubectl -n alluxio-operator get pod
NAME                                             READY   STATUS    RESTARTS   AGE
alluxio-cluster-controller-8656d54bc-x6ms6       1/1     Running   0          19s
alluxio-collectinfo-controller-cc49c56b6-wlw8k   1/1     Running   0          19s
alluxio-csi-controller-84df9646fd-4d5b8          2/2     Running   0          19s
alluxio-csi-nodeplugin-fcp7b                     2/2     Running   0          19s
alluxio-csi-nodeplugin-t59ch                     2/2     Running   0          19s
alluxio-csi-nodeplugin-vbq2q                     2/2     Running   0          19s
alluxio-ufs-controller-57fbdf8d5c-2f79l          1/1     Running   0          19s
```

确认 Alluxio 集群是否启动成功, 下面是 Alluxio 集群的信息，可以看到 Alluxio 集群的各个组件都在运行。

```console
kubectl -n alx-ns get pod
NAME                                          READY   STATUS    RESTARTS   AGE
alluxio-cluster-coordinator-0                 1/1     Running   0          2m17s
alluxio-cluster-etcd-0                        1/1     Running   0          2m17s
alluxio-cluster-etcd-1                        1/1     Running   0          2m17s
alluxio-cluster-etcd-2                        1/1     Running   0          2m17s
alluxio-cluster-grafana-9fd587b4f-mnczs       1/1     Running   0          2m17s
alluxio-cluster-prometheus-6b55c568b8-sfp96   1/1     Running   0          2m17s
alluxio-cluster-worker-779d87567f-95wls       1/1     Running   0          2m17s
alluxio-cluster-worker-779d87567f-sgh4b       1/1     Running   0          2m17s
```

## 采集信息

`collectinfo` 用于采集 Alluxio 集群的信息，包括配置、硬件、任务记录、日志和指标信息。提供定时采集和单次采集两种方式。

* 定时采集可以设置采集的时间间隔，例如每天、每周、每月等；
* 单次采集会立刻触发一次采集任务。

创建 Alluxio 集群之后会自动创建定时采集，用于采集集群信息。\
默认情况下，定时采集每天会自动采集信息。可以通过 `collectinfo` 的状态来查看采集信息的进度，`LASTSCHEDULETIME` 表示下次执行采集任务的时间，`LASTSUCCESSFULTIME` 表示最近采集成功的时间。

```console
kubectl -n alx-ns get collectinfo
NAME                                  LASTSCHEDULETIME       LASTSUCCESSFULTIME     Age
alluxio-cluster-alluxio-collectinfo                                                 0s
alluxio-cluster-alluxio-collectinfo                                                 0s
alluxio-cluster-alluxio-collectinfo   2025-01-23T00:00:00Z                          0s
alluxio-cluster-alluxio-collectinfo   2025-01-24T00:00:00Z                          2m
alluxio-cluster-alluxio-collectinfo   2025-01-24T00:00:00Z   2025-01-23T00:00:43Z   1d
alluxio-cluster-alluxio-collectinfo   2025-01-25T00:00:00Z   2025-01-23T00:00:43Z   1d
alluxio-cluster-alluxio-collectinfo   2025-01-25T00:00:00Z   2025-01-24T00:00:44Z   2d
alluxio-cluster-alluxio-collectinfo   2025-01-26T00:00:00Z   2025-01-24T00:00:44Z   2d
alluxio-cluster-alluxio-collectinfo   2025-01-26T00:00:00Z   2025-01-25T00:00:45Z   3d
```

完成信息采集后，会将采集结果保存在 `coordinator` pod 中，用于持久化数据。`collectinfo` 会根据 `expiration` 字段（请参考[详细配置](#详细配置)）的值删除过期的采集结果。\
默认的 `expiration` 为`720h`或30天，超过30天的采集结果会被删除。

可以进入 `coordinator` 的 pod 中查看采集结果。 执行下面的命令进入 `coordinator` 的 pod 中。

```console
COORDINATOR_NAME=$(kubectl -n alx-ns get pod -l app.kubernetes.io/name=alluxio,app.kubernetes.io/component=coordinator -o jsonpath="{.items[0].metadata.name}")

➜ kubectl -n alx-ns exec -it ${COORDINATOR_NAME} -- bash
alluxio@alluxio-cluster-coordinator-0:/$ 

# 进入metastore目录
alluxio@alluxio-cluster-coordinator-0:/$ cd /mnt/alluxio/metastore/collectinfo/

# 查看采集结果
alluxio@alluxio-cluster-coordinator-0:/mnt/alluxio/metastore/collectinfo$ ls
alluxio-cluster-alluxio-collectinfo_alx-ns_2025-01-23-00-00-00.tar.gz  alluxio-cluster-alluxio-collectinfo_alx-ns_2025-01-25-00-00-00.tar.gz
alluxio-cluster-alluxio-collectinfo_alx-ns_2025-01-24-00-00-00.tar.gz
```

一天的采集结果会保存在一个 `tar.gz` 文件中，文件名表示采集任务的名称、Alluxio 集群的命名空间和采集时间。

如果想修改收集内容或时间表，可以执行以下操作。

1. 删除现有的 `collectinfo` 资源

```console
# 删除 collectinfo
kubectl -n alx-ns delete collectinfo <COLLECTINFO_NAME>
```

2. 创建 `collectinfo.yaml` 文件，内容如下：

我们创建了一个 `collectinfo` 资源，名称为 `example-collectinfo`，和 Alluxio 集群同样位于 `alx-ns` 命名空间，\
并且设置了定时采集信息，`"0 0 * * *"` 代表每天午夜运行一次。\
可以参考 [Cron 时间表语法](https://kubernetes.io/zh-cn/docs/concepts/workloads/controllers/cron-jobs/#cron-schedule-syntax)。

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: CollectInfo
metadata:
  name: example-collectinfo
  namespace: alx-ns
spec:
  scheduled:
    enabled: true
    cron: "0 0 * * *"
```

完整的配置可以参考[详细配置](#详细配置)。

3. 创建 `collectinfo` ，开始采集信息。

```console
kubectl apply -f collectinfo.yaml
```

## 下载结果

通过 `kubectl cp` 的方式，将采集的信息拷贝到本地。

```console
# 设置环境变量保存 coordinator pod 的名字 
COORDINATOR_NAME=$(kubectl -n alx-ns get pod -l app.kubernetes.io/name=alluxio,app.kubernetes.io/component=coordinator -o jsonpath="{.items[0].metadata.name}")

# 需要填入 coordinator pod 的名字
kubectl -n alx-ns cp ${COORDINATOR_NAME}:/mnt/alluxio/metastore/collectinfo/ collectinfo-output
```

## 详细配置

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: CollectInfo
metadata:
  name: example-collectinfo
  namespace: alx-ns
spec:
  # 设置定时采集信息
  scheduled:
    # 是否启用定时采集，true表示启用，则会按照cron表达式定时采集信息
    # false表示不启用定时采集，则会立即采集一次信息
    enabled: false
    # cron表达式，用于设置定时采集的时间
    # 下面的示例表示每天午夜执行一次采集任务
    # cron表达式的具体语法可以参考：https://kubernetes.io/zh-cn/docs/concepts/workloads/controllers/cron-jobs/#cron-schedule-syntax
    cron: "0 0 * * *"
    # 时区，用于设置采集任务的时区
    # 下面的示例表示采集任务的时区为上海时区
    # 时区的具体值可以参考：https://kubernetes.io/zh-cn/docs/concepts/workloads/controllers/cron-jobs/#time-zones
    timezone: "Asia/Shanghai"
    # 采集任务的过期时间，超过过期时间的采集结果会被删除
    # 下面的示例表示采集结果会保存720小时，超过720小时的采集结果会被删除
    # 过期时间的具体值可以参考：https://golang.org/pkg/time/#ParseDuration
    expiration: "720h"
  # 采集信息类型，包括config, hardware, etcd, job-history, logs, metrics
  # 如果不指定或者指定all，表示采集全部信息
  # 允许指定多个类型:
  # type:
  #   - config
  #   - hardware
  type:
    - all
  logs:
    # 采集日志的数量，比如100表示采集最新的100条日志
    tail: 100
  # 指标信息，duration表示采集的时长，step表示采集的间隔
  # 下面的参数示例表示采集从现在到过去2小时内的全部指标(metrics)，间隔每分钟采集一次指标(metrics)
  metrics:
    # 采集指标(metrics)的时长，比如2h表示采集从现在到过去24小时内的指标(metrics)
    duration: 24h
    # 采集指标(metrics)的间隔，比如1m表示每分钟采集一次指标(metrics)
    step: 1m
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.alluxio.io/ee-ai-cn/ai-3.6/start/diagnostic-snapshot.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.