오프라인 이미지 뷰어 가이드

오프라인 이미지 뷰어 가이드 (Offline Image Viewer Guide)

HDFS의 fsimage 파일 내용을 사람이 읽을 수 있는 형식으로 덤프하고 읽기 전용 WebHDFS API를 제공하는 Offline Image Viewer(oiv) 도구를 설명하는 문서예요. 클러스터가 실행 중이 아니어도 네임스페이스를 오프라인으로 분석·검사할 수 있게 해 줍니다.

출처: 문서

본문

개요 (Overview)

Offline Image Viewer는 hdfs fsimage 파일의 내용을 사람이 읽을 수 있는 형식으로 덤프하고, Hadoop 클러스터 네임스페이스의 오프라인 분석·검사를 가능하게 하는 읽기 전용 WebHDFS API를 제공하는 도구입니다. 매우 큰 이미지 파일도 비교적 빠르게 처리할 수 있어요. Hadoop 2.4 이상에 포함된 레이아웃 형식을 처리합니다. 더 오래된 레이아웃 형식을 처리하려면 Hadoop 2.3의 Offline Image Viewer나 oiv_legacy 명령을 사용할 수 있습니다. 도구가 이미지 파일을 처리할 수 없으면 깨끗하게 종료됩니다. Offline Image Viewer는 클러스터가 실행 중일 필요가 없어요. 완전히 오프라인으로 동작합니다.

Offline Image Viewer는 여러 출력 프로세서를 제공합니다.

Web — 기본 출력 프로세서. 읽기 전용 WebHDFS API를 노출하는 HTTP 서버를 띄웁니다. 사용자는 HTTP REST API로 네임스페이스를 대화형으로 조사할 수 있어요. 보안 모드와 HTTPS는 지원하지 않습니다.
XML — fsimage의 XML 문서를 만들고 fsimage 안의 모든 정보를 포함합니다. 이 출력은 XML 도구로 자동 처리·분석하기 좋아요. XML 문법이 장황해서 가장 많은 출력을 생성합니다.
FileDistribution — 네임스페이스 이미지의 파일 크기를 분석하는 도구. maxSize와 step을 지정해 정수 범위 [0, maxSize]를 정의하고, 그 범위를 step 크기의 구간 [0, s[1], …, s[n-1], maxSize]으로 나눠 각 구간 [s[i-1], s[i])에 속하는 파일 수를 계산합니다. maxSize보다 큰 파일은 항상 마지막 구간에 들어갑니다. 기본 출력은 탭으로 구분된 두 열 테이블(Size, NumFiles) 형식입니다. Size는 구간의 시작을, numFiles는 그 구간에 크기가 속하는 이미지의 파일 수를 나타내요. -format 옵션을 지정하면 Size 열에 표시되는 바이트 수 대신 사람이 읽기 좋은 형식으로 출력하고, Size 열이 Size Range 열로 바뀝니다.
Delimited (실험) — inode와 inodes-under-construction에 모두 공통인 모든 요소를 구분자로 나눠 텍스트 파일로 생성. 기본 구분자는 \t이며 -delimiter 인자로 변경할 수 있음.
DetectCorruption (실험) — 이미지의 일부를 선택적으로 로드하고 불일치를 적극적으로 찾아 잠재적 손상을 탐지. 찾은 손상 요약을 구분자 형식으로 출력. 검사가 완전하지는 않으며 네임스페이스 재구성 중 누락된 노드만 잡아냅니다.
ReverseXML (실험) — XML 프로세서의 반대. XML 파일에서 fsimage를 재구성. 테스트용 fsimage를 만들거나 손상된 fsimage를 수동 편집하기 쉽게 해 줍니다.

사용법 (Usage)

Web 프로세서

Web 프로세서는 읽기 전용 WebHDFS API를 노출하는 HTTP 서버를 띄웁니다. -addr 옵션으로 수신 주소를 지정할 수 있어요(기본 localhost:5978).

bash$ bin/hdfs oiv -i fsimage
14/04/07 13:25:14 INFO offlineImageViewer.WebImageViewer: WebImageViewer
started. Listening on /127.0.0.1:5978. Press Ctrl+C to stop the viewer.

다음 셸 명령으로 뷰어에 접근해 fsimage의 정보를 얻을 수 있습니다.

bash$ bin/hdfs dfs -ls webhdfs://127.0.0.1:5978/
Found 2 items
drwxrwx--* - root supergroup          0 2014-03-26 20:16 webhdfs://127.0.0.1:5978/tmp
drwxr-xr-x   - root supergroup          0 2014-03-31 14:08 webhdfs://127.0.0.1:5978/user

모든 파일·디렉터리 정보를 얻으려면 다음 명령을 쓰면 됩니다.

bash$ bin/hdfs dfs -ls -R webhdfs://127.0.0.1:5978/

HTTP REST API로 JSON 형식의 FileStatuses를 얻을 수도 있어요.

bash$ curl -i http://127.0.0.1:5978/webhdfs/v1/?op=liststatus
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 252

{"FileStatuses":{"FileStatus":[
{"fileId":16386,"accessTime":0,"replication":0,"owner":"theuser","length":0,"permission":"755","blockSize":0,"modificationTime":1392772497282,"type":"DIRECTORY","group":"supergroup","childrenNum":1,"pathSuffix":"user"}
]}}

Web 프로세서는 현재 다음 연산을 지원합니다.

XML 프로세서

XML 프로세서는 fsimage의 모든 내용을 덤프하는 데 사용합니다. -i와 -o 명령줄로 입력·출력 파일을 지정해요.

bash$ bin/hdfs oiv -p XML -i fsimage -o fsimage.xml

이렇게 하면 fsimage의 모든 정보를 담은 fsimage.xml 파일이 만들어집니다. 매우 큰 이미지 파일은 이 과정이 몇 분 걸릴 수 있어요.

XML 프로세서로 Offline Image Viewer를 실행하면 다음과 같은 출력이 나옵니다.

<?xml version="1.0"?>
<fsimage>
<NameSection>
  <genstampV1>1000</genstampV1>
  <genstampV2>1002</genstampV2>
  <genstampV1Limit>0</genstampV1Limit>
  <lastAllocatedBlockId>1073741826</lastAllocatedBlockId>
  <txid>37</txid>
</NameSection>
<INodeSection>
  <lastInodeId>16400</lastInodeId>
  <inode>
    <id>16385</id>
    <type>DIRECTORY</type>
    <name></name>
    <mtime>1392772497282</mtime>
    <permission>theuser:supergroup:rwxr-xr-x</permission>
    <nsquota>9223372036854775807</nsquota>
    <dsquota>-1</dsquota>
  </inode>
...remaining output omitted...

ReverseXML 프로세서

ReverseXML 프로세서는 XML 프로세서의 반대입니다. -i와 -o로 입력 XML 파일과 출력 fsimage 파일을 지정해요.

bash$ bin/hdfs oiv -p ReverseXML -i fsimage.xml -o fsimage

이렇게 하면 XML 파일에서 fsimage를 재구성합니다.

FileDistribution 프로세서

FileDistribution 프로세서는 네임스페이스 이미지의 파일 크기를 분석합니다. -maxSize(기본 128GB)와 -step(기본 2MB)을 바이트 단위로 지정할 수 있어요.

bash$ bin/hdfs oiv -p FileDistribution -maxSize maxSize -step size -i fsimage -o output

프로세서는 각 구간에 속하는 시스템의 파일 수를 계산합니다. 출력 파일은 탭으로 구분된 두 열 테이블 형식입니다.

Size	NumFiles
4	1
12	1
16	1
20	1
totalFiles = 4
totalDirectories = 2
totalBlocks = 4
totalSpace = 48
maxFileSize = 21

출력을 더 읽기 쉽게 하려면 추가로 -format 옵션을 지정할 수 있어요.

bash$ bin/hdfs oiv -p FileDistribution -maxSize maxSize -step size -format -i fsimage -o output

그러면 다음과 같은 출력이 나옵니다.

Size Range	NumFiles
(0 B, 4 B]	1
(8 B, 12 B]	1
(12 B, 16 B]	1
(16 B, 21 B]	1
totalFiles = 4
totalDirectories = 2
totalBlocks = 4
totalSpace = 48
maxFileSize = 21

Delimited 프로세서

Delimited 프로세서는 각 요소를 구분자 문자열(기본 \t)로 나눈 fsimage의 텍스트 표현을 생성합니다. -delimiter 옵션으로 새 구분자 문자열을 지정할 수 있어요.

bash$ bin/hdfs oiv -p Delimited -delimiter delimiterString -i fsimage -o output

또한 다음 명령으로 중간 결과를 캐시할 임시 디렉터리를 지정할 수 있습니다.

bash$ bin/hdfs oiv -p Delimited -delimiter delimiterString -t temporaryDir -i fsimage -o output

설정하지 않으면 Delimited 프로세서는 텍스트를 출력하기 전에 네임스페이스를 메모리에 구성합니다. 이 프로세서의 출력은 다음과 같습니다.

Path	Replication	ModificationTime	AccessTime	PreferredBlockSize	BlocksCount	FileSize	NSQUOTA	DSQUOTA	Permission	UserName	GroupName
/	0	2017-02-13 10:39	1970-01-01 08:00	0	0	0	9223372036854775807	-1	drwxr-xr-x	root	supergroup
/dir0	0	2017-02-13 10:39	1970-01-01 08:00	0	0	0	-1	-1	drwxr-xr-x	root	supergroup
/dir0/file0	1	2017-02-13 10:39	2017-02-13 10:39	134217728	1	1	0	0	-rw-r--r--	root	supergroup
/dir0/file1	1	2017-02-13 10:39	2017-02-13 10:39	134217728	1	1	0	0	-rw-r--r--	root	supergroup
/dir0/file2	1	2017-02-13 10:39	2017-02-13 10:39	134217728	1	1	0	0	-rw-r--r--	root	supergroup

DetectCorruption 프로세서

DetectCorruption 프로세서는 fsimage에 오류가 있다면 그 오류의 텍스트 표현을 생성합니다. 다음 경우를 표시해요.

inode가 fsimage에 언급됐지만 관련 메타데이터를 찾을 수 없음 (CorruptNode)
inode에 손상된 자식이 하나 이상 있음 (MissingChildren)

구분자 문자열은 -delimiter 옵션으로, 중간 결과 캐시는 -t 옵션으로 제공할 수 있어요.

bash$ bin/hdfs oiv -p DetectCorruption -delimiter delimiterString -t temporaryDir -i fsimage -o output

손상이 없으면 이 프로세서의 출력은 비어 있고, 있으면 다음 형식의 항목이 출력됩니다.

CorruptionType	Id	IsSnapshot	ParentPath	ParentId	Name	NodeType	CorruptChildren
MissingChild	16385	false	/	Missing		Node	1
MissingChild	16386	false	/	16385	dir0	Node	2
CorruptNode	16388	true		16386		Unknown	0
CorruptNode	16389	true		16386		Unknown	0
CorruptNodeWithMissingChild	16391	true		16385		Unknown	1
CorruptNode	16394	true		16391		Unknown	0

CorruptionType 열은 MissingChild, CorruptNode 또는 이 둘의 조합일 수 있어요. IsSnapshot은 노드가 스냅샷에 유지되는지 여부를 보여줍니다. NodeType 열에는 노드가 inode인지(Node), 참조인지(Ref), 손상되어 알 수 없는지(Unknown)에 따라 써집니다. CorruptChildren은 inode가 가질 수 있는 손상된 자식 수를 담아요.

옵션 (Options)

플래그	설명
`-i` / `--inputFile` 입력 파일	처리할 입력 fsimage 파일(ReverseXML 프로세서를 쓰면 XML 파일) 지정. 필수.
`-o` / `--outputFile` 출력 파일	지정한 출력 프로세서가 파일을 생성하는 경우 출력 파일 이름 지정. 이미 있으면 조용히 덮어씀. (기본 stdout으로 출력) 입력이 XML 파일이면 `<outputFile>.md5`도 생성.
`-p` / `--processor` 프로세서	image 파일에 적용할 프로세서 지정. 현재 유효한 값은 `Web`(기본), `XML`, `Delimited`, `DetectCorruption`, `FileDistribution`, `ReverseXML`.
`-addr` 주소	수신 주소(host:port) 지정(기본 localhost:5978). Web 프로세서와 함께 사용.
`-maxSize` 크기	분석할 파일 크기 범위 [0, maxSize]를 바이트 단위로 지정(기본 128GB). FileDistribution 프로세서와 함께 사용.
`-step` 크기	분포의 세분화를 바이트 단위로 지정(기본 2MB). FileDistribution 프로세서와 함께 사용.
`-format`	바이트 수 대신 사람이 읽기 좋은 형식으로 출력을 포맷(기본 false). FileDistribution 프로세서와 함께 사용.
`-delimiter` arg	Delimited 또는 DetectCorruption 프로세서에 사용할 구분 문자열.
`-t` / `--temp` 임시 디렉터리	Delimited 출력을 생성하기 위해 중간 결과를 캐시할 임시 디렉터리. 설정하지 않으면 Delimited 프로세서가 텍스트 출력 전에 네임스페이스를 메모리에 구성.
`-h` / `--help`	도구 사용법과 도움말 표시 후 종료.

결과 분석 (Analyzing Results)

Offline Image Viewer를 사용하면 hdfs 네임스페이스에 대한 방대한 데이터를 쉽게 모을 수 있습니다. 이 정보로 파일 시스템 사용 패턴을 탐구하거나 임의 기준에 맞는 특정 파일을 찾는 등 다양한 네임스페이스 분석을 할 수 있어요.

oiv_legacy 명령

ProtocolBuffer 기반 fsimage(HDFS-5698)가 도입하면서 내부 레이아웃이 바뀌어, OfflineImageViewer는 과도한 메모리를 소모하고 Indented 프로세서 같은 일부 기능을 잃었어요. 많은 메모리 없이 처리하거나 이런 프로세서를 쓰려면 oiv_legacy 명령(Hadoop 2.3의 oiv와 동일)을 사용할 수 있습니다.

Usage

dfs.namenode.legacy-oiv-image.dir을 적절한 디렉터리로 설정해 standby NameNode 또는 SecondaryNameNode가 체크포인트 중 네임스페이스를 옛 fsimage 형식으로 저장하게 합니다.
옛 형식 fsimage에 oiv_legacy 명령을 사용합니다.

bash$ bin/hdfs oiv_legacy -i fsimage_old -o output

Options

플래그	설명
`-i` / `--inputFile` 입력 파일	처리할 입력 fsimage 파일 지정. 필수.
`-o` / `--outputFile` 출력 파일	지정한 출력 프로세서가 파일을 생성하는 경우 출력 파일 이름 지정. 이미 있으면 조용히 덮어씀. 필수.
`-p` / `--processor` 프로세서	image 파일에 적용할 프로세서 지정. 유효한 값은 Ls(기본), XML, Delimited, Indented, FileDistribution, NameDistribution.
`-maxSize` 크기	분석할 파일 크기 범위 [0, maxSize]를 바이트 단위로 지정(기본 128GB). FileDistribution 프로세서와 함께 사용.
`-step` 크기	분포 세분화를 바이트 단위로 지정(기본 2MB). FileDistribution 프로세서와 함께 사용.
`-format`	바이트 수 대신 사람이 읽기 좋은 형식으로 출력 포맷(기본 false). FileDistribution 프로세서와 함께 사용.
`-skipBlocks`	파일 내 개별 블록을 열거하지 않음. 매우 큰 파일이 있는 네임스페이스에서 처리 시간과 출력 파일 공간을 아낄 수 있음. Ls 프로세서는 파일 크기를 정확히 결정하기 위해 블록을 읽으므로 이 옵션을 무시함.
`-printToScreen`	프로세서 출력을 지정 파일뿐 아니라 콘솔로도 보냄. 매우 큰 네임스페이스에서는 처리 시간이 한 자릿수 이상 늘어날 수 있음.
`-delimiter` arg	Delimited 프로세서와 함께 쓸 때 기본 탭 구분자를 _arg_로 지정한 문자열로 대체.
`-h` / `--help`	도구 사용법과 도움말 표시 후 종료.

더 알아보기 (Learn more)

원문: 문서