← Documents Documentation/admin-guide/filesystem-monitoring.rst GitHub 원문 ↗

Linux 6.18.37 · Administration / Filesystems

Linux filesystem monitoring with fanotify

FAN_FS_ERROR 알림의 목적, 최초 오류 보존 정책, 필수 레코드와 복구용 inode 식별 정보를 설명합니다.

Source pathDocumentation/admin-guide/filesystem-monitoring.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

오류 조기 감지

filesystem-monitoring.rst:1-35

상태 감시 데몬이 파일시스템 전체 오류를 수신하고 최초 실패 정보를 잃지 않도록 하는 `FAN_FS_ERROR`의 설계를 설명합니다.

알림 레코드

filesystem-monitoring.rst:36-78

순서가 고정되지 않은 metadata, generic error, FID 레코드와 오류 횟수 및 inode 식별 필드를 정리합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
1 .. SPDX-License-Identifier: GPL-2.0
2
3 ====================================
4 File system Monitoring with fanotify
5 ====================================
6
7 File system Error Reporting
8 ===========================
9
10 Fanotify supports the FAN_FS_ERROR event type for file system-wide error
11 reporting. It is meant to be used by file system health monitoring
12 daemons, which listen for these events and take actions (notify
13 sysadmin, start recovery) when a file system problem is detected.
14
15 By design, a FAN_FS_ERROR notification exposes sufficient information
16 for a monitoring tool to know a problem in the file system has happened.
17 It doesn't necessarily provide a user space application with semantics
18 to verify an IO operation was successfully executed. That is out of
19 scope for this feature. Instead, it is only meant as a framework for
20 early file system problem detection and reporting recovery tools.
21
22 When a file system operation fails, it is common for dozens of kernel
23 errors to cascade after the initial failure, hiding the original failure
24 log, which is usually the most useful debug data to troubleshoot the
25 problem. For this reason, FAN_FS_ERROR tries to report only the first
26 error that occurred for a file system since the last notification, and
27 it simply counts additional errors. This ensures that the most
28 important pieces of information are never lost.
29
30 FAN_FS_ERROR requires the fanotify group to be setup with the
31 FAN_REPORT_FID flag.
32
33 At the time of this writing, the only file system that emits FAN_FS_ERROR
34 notifications is Ext4.
35
36 A FAN_FS_ERROR Notification has the following format::
37
38 ::
39
40 [ Notification Metadata (Mandatory) ]
41 [ Generic Error Record (Mandatory) ]
42 [ FID record (Mandatory) ]
43
44 The order of records is not guaranteed, and new records might be added
45 in the future. Therefore, applications must not rely on the order and
46 must be prepared to skip over unknown records. Please refer to
47 ``samples/fanotify/fs-monitor.c`` for an example parser.
48
49 Generic error record
50 --------------------
51
52 The generic error record provides enough information for a file system
53 agnostic tool to learn about a problem in the file system, without
54 providing any additional details about the problem. This record is
55 identified by ``struct fanotify_event_info_header.info_type`` being set
56 to FAN_EVENT_INFO_TYPE_ERROR.
57
58 ::
59
60 struct fanotify_event_info_error {
61 struct fanotify_event_info_header hdr;
62 __s32 error;
63 __u32 error_count;
64 };
65
66 The `error` field identifies the type of error using errno values.
67 `error_count` tracks the number of errors that occurred and were
68 suppressed to preserve the original error information, since the last
69 notification.
70
71 FID record
72 ----------
73
74 The FID record can be used to uniquely identify the inode that triggered
75 the error through the combination of fsid and file handle. A file system
76 specific application can use that information to attempt a recovery
77 procedure. Errors that are not related to an inode are reported with an
78 empty file handle of type FILEID_INVALID.
79

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

fanotify 파일시스템 오류 보고의 목적

1-20

fanotify를 사용한 파일시스템 모니터링 문서입니다. fanotify는 파일시스템 전체 오류를 보고하는 `FAN_FS_ERROR` 이벤트 형식을 지원합니다. 파일시스템 상태 감시 데몬은 이 이벤트를 수신하고 문제가 감지되면 시스템 관리자에게 알리거나 복구를 시작할 수 있습니다.

`FAN_FS_ERROR` 알림은 감시 도구가 파일시스템에 문제가 발생했다는 사실을 알기에 충분한 정보를 노출하도록 설계되었습니다. 사용자 공간 애플리케이션이 특정 I/O 작업의 성공 여부를 검증할 수 있는 의미 체계까지 반드시 제공하지는 않으며, 그것은 이 기능의 범위를 벗어납니다. 이 기능은 파일시스템 문제를 조기에 감지하고 복구 도구에 보고하는 프레임워크입니다.

첫 오류 보존과 지원 조건

21-35

파일시스템 작업이 실패하면 최초 실패 뒤에 수십 개의 커널 오류가 연쇄적으로 발생해, 문제 해결에 가장 유용한 최초 실패 로그를 가리는 일이 흔합니다. 따라서 `FAN_FS_ERROR`는 마지막 알림 이후 파일시스템에서 처음 발생한 오류만 보고하고 추가 오류는 개수만 셉니다. 이 방식은 가장 중요한 정보가 사라지지 않게 합니다.

`FAN_FS_ERROR`를 사용하려면 fanotify 그룹을 `FAN_REPORT_FID` 플래그로 설정해야 합니다.

이 문서를 작성한 시점에는 Ext4만 `FAN_FS_ERROR` 알림을 발생시킵니다.

FAN_FS_ERROR 알림 레코드 배치

36-48

`FAN_FS_ERROR` 알림은 아래 세 필수 레코드로 구성됩니다.

FAN_FS_ERROR 필수 레코드
레코드필수 여부역할
Notification Metadata필수fanotify 알림의 공통 메타데이터
Generic Error Record필수파일시스템 독립적인 오류 번호와 누적 횟수
FID record필수fsid와 file handle을 통한 inode 식별 정보
undefinedundefined
undefinedundefined

원문의 세 줄 ASCII 레코드 배치를 순서 의존성이 없는 구조화 표로 다시 그렸습니다.

레코드 순서는 보장되지 않으며 앞으로 새 레코드가 추가될 수 있습니다. 따라서 애플리케이션은 순서에 의존해서는 안 되고, 알 수 없는 레코드를 건너뛸 준비가 되어 있어야 합니다. 파서 예제는 `samples/fanotify/fs-monitor.c`를 참고하십시오.

Generic error record

49-70

generic error record는 문제의 추가 세부 사항 없이도 파일시스템에 문제가 생겼음을 파일시스템 비종속 도구가 알 수 있는 정보를 제공합니다. `struct fanotify_event_info_header.info_type`이 `FAN_EVENT_INFO_TYPE_ERROR`로 설정된 레코드가 이 형식입니다.

struct fanotify_event_info_error {
     struct fanotify_event_info_header hdr;
    __s32 error;
    __u32 error_count;
};
필드설명
errorerrno 값을 사용해 오류 종류를 식별합니다.
error_count마지막 알림 이후 최초 오류 정보를 보존하기 위해 억제한 추가 오류의 수를 추적합니다.

FID record

71-78

FID record는 `fsid`와 file handle의 조합으로 오류를 일으킨 inode를 고유하게 식별할 수 있습니다. 파일시스템 전용 애플리케이션은 이 정보로 복구 절차를 시도할 수 있습니다. inode와 관련 없는 오류는 형식이 `FILEID_INVALID`인 빈 file handle로 보고됩니다.