HBASE-26921 Rewrite the counting cells part in TestMultiVersions (#4316)
[hbase.git] / src / main / asciidoc / _chapters / hbase_mob.adoc
blob0e09db11a18d74ff709aef8f3b328cfe7b68573c
1 ////
2 /**
3  *
4  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements.  See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership.  The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License.  You may obtain a copy of the License at
11  *
12  *     http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 ////
22 [[hbase_mob]]
23 == Storing Medium-sized Objects (MOB)
24 :doctype: book
25 :numbered:
26 :toc: left
27 :icons: font
28 :experimental:
29 :toc: left
30 :source-language: java
32 Data comes in many sizes, and saving all of your data in HBase, including binary
33 data such as images and documents, is ideal. While HBase can technically handle
34 binary objects with cells that are larger than 100 KB in size, HBase's normal
35 read and write paths are optimized for values smaller than 100KB in size. When
36 HBase deals with large numbers of objects over this threshold, referred to here
37 as medium objects, or MOBs, performance is degraded due to write amplification
38 caused by splits and compactions. When using MOBs, ideally your objects will be between
39 100KB and 10MB (see the <<faq>>). HBase 2 added special internal handling of MOBs
40 to maintain performance, consistency, and low operational overhead. MOB support is
41 provided by the work done in link:https://issues.apache.org/jira/browse/HBASE-11339[HBASE-11339].
42 To take advantage of MOB, you need to use <<hfilev3,HFile version 3>>. Optionally,
43 configure the MOB file reader's cache settings for each RegionServer (see
44 <<mob.cache.configure>>), then configure specific columns to hold MOB data.
45 Client code does not need to change to take advantage of HBase MOB support. The
46 feature is transparent to the client.
48 === Configuring Columns for MOB
50 You can configure columns to support MOB during table creation or alteration,
51 either in HBase Shell or via the Java API. The two relevant properties are the
52 boolean `IS_MOB` and the `MOB_THRESHOLD`, which is the number of bytes at which
53 an object is considered to be a MOB. Only `IS_MOB` is required. If you do not
54 specify the `MOB_THRESHOLD`, the default threshold value of 100 KB is used.
56 .Configure a Column for MOB Using HBase Shell
57 ----
58 hbase> create 't1', {NAME => 'f1', IS_MOB => true, MOB_THRESHOLD => 102400}
59 hbase> alter 't1', {NAME => 'f1', IS_MOB => true, MOB_THRESHOLD => 102400}
60 ----
62 .Configure a Column for MOB Using the Java API
63 ====
64 [source,java]
65 ----
66 ...
67 HColumnDescriptor hcd = new HColumnDescriptor(“f”);
68 hcd.setMobEnabled(true);
69 ...
70 hcd.setMobThreshold(102400L);
71 ...
72 ----
73 ====
75 === Testing MOB
77 The utility `org.apache.hadoop.hbase.IntegrationTestIngestWithMOB` is provided to assist with testing
78 the MOB feature. The utility is run as follows:
79 [source,bash]
80 ----
81 $ sudo -u hbase hbase org.apache.hadoop.hbase.IntegrationTestIngestWithMOB \
82             -threshold 1024 \
83             -minMobDataSize 512 \
84             -maxMobDataSize 5120
85 ----
87 * `*threshold*` is the threshold at which cells are considered to be MOBs.
88    The default is 1 kB, expressed in bytes.
89 * `*minMobDataSize*` is the minimum value for the size of MOB data.
90    The default is 512 B, expressed in bytes.
91 * `*maxMobDataSize*` is the maximum value for the size of MOB data.
92    The default is 5 kB, expressed in bytes.
94 === MOB architecture
96 This section is derived from information found in
97 link:https://issues.apache.org/jira/browse/HBASE-11339[HBASE-11339], which covered the initial GA
98 implementation of MOB in HBase and
99 link:https://issues.apache.org/jira/browse/HBASE-22749[HBASE-22749], which improved things by
100 parallelizing MOB maintenance across the RegionServers. For more information see
101 the last version of the design doc created during the initial work,
102 "link:https://github.com/apache/hbase/blob/master/dev-support/design-docs/HBASE-11339%20MOB%20GA%20design.pdf[HBASE-11339 MOB GA design.pdf]",
103 and the design doc for the distributed mob compaction feature,
104 "link:https://github.com/apache/hbase/blob/master/dev-support/design-docs/HBASE-22749%20MOB%20distributed%20compaction.pdf[HBASE-22749 MOB distributed compaction.pdf]".
107 ==== Overview
109 The MOB feature reduces the overall IO load for configured column families by storing values that
110 are larger than the configured threshold outside of the normal regions to avoid splits, merges, and
111 most importantly normal compactions.
113 When a cell is first written to a region it is stored in the WAL and memstore regardless of value
114 size. When memstores from a column family configured to use MOB are eventually flushed two hfiles
115 are written simultaneously. Cells with a value smaller than the threshold size are written to a
116 normal region hfile. Cells with a value larger than the threshold are written into a special MOB
117 hfile and also have a MOB reference cell written into the normal region HFile. As the Region Server
118 flushes a MOB enabled memstore and closes a given normal region HFile it appends metadata that lists
119 each of the special MOB hfiles referenced by the cells within.
121 MOB reference cells have the same key as the cell they are based on. The value of the reference cell
122 is made up of two pieces of metadata: the size of the actual value and the MOB hfile that contains
123 the original cell. In addition to any tags originally written to HBase, the reference cell prepends
124 two additional tags. The first is a marker tag that says the cell is a MOB reference. This can be
125 used later to scan specifically just for reference cells. The second stores the namespace and table
126 at the time the MOB hfile is written out. This tag is used to optimize how the MOB system finds
127 the underlying value in MOB hfiles after a series of HBase snapshot operations (ref HBASE-12332).
128 Note that tags are only available within HBase servers and by default are not sent over RPCs.
130 All MOB hfiles for a given table are managed within a logical region that does not directly serve
131 requests. When these MOB hfiles are created from a flush or MOB compaction they are placed in a
132 dedicated mob data area under the hbase root directory specific to the namespace, table, mob
133 logical region, and column family. In general that means a path structured like:
135 ----
136 %HBase Root Dir%/mobdir/data/%namespace%/%table%/%logical region%/%column family%/
137 ----
139 With default configs, an example table named 'some_table' in the
140 default namespace with a MOB enabled column family named 'foo' this HDFS directory would be
142 ----
143 /hbase/mobdir/data/default/some_table/372c1b27e3dc0b56c3a031926e5efbe9/foo/
144 ----
146 These MOB hfiles are maintained by special chores in the HBase Master and across the individual
147 Region Servers. Specifically those chores take care of enforcing TTLs and compacting them. Note that
148 this compaction is primarily a matter of controlling the total number of files in HDFS because our
149 operational assumptions for MOB data is that it will seldom update or delete.
151 When a given MOB hfile is no longer needed as a result of our compaction process then a chore in
152 the Master will take care of moving it to the archive just
153 like any normal hfile. Because the table's mob region is independent of all the normal regions it
154 can coexist with them in the regular archive storage area:
156 ----
157 /hbase/archive/data/default/some_table/372c1b27e3dc0b56c3a031926e5efbe9/foo/
158 ----
160 The same hfile cleaning chores that take care of eventually deleting unneeded archived files from
161 normal regions thus also will take care of these MOB hfiles. As such, if there is a snapshot of a
162 MOB enabled table then the cleaning system will make sure those MOB files stick around in the
163 archive area as long as they are needed by a snapshot or a clone of a snapshot.
165 ==== MOB compaction
167 Each time the memstore for a MOB enabled column family performs a flush HBase will write values over
168 the MOB threshold into MOB specific hfiles. When normal region compaction occurs the Region Server
169 rewrites the normal data files while maintaining references to these MOB files without rewriting
170 them. Normal client lookups for MOB values transparently will receive the original values because
171 the Region Server internals take care of using the reference data to then pull the value out of a
172 specific MOB file. This indirection means that building up a large number of MOB hfiles doesn't
173 impact the overall time to retrieve any specific MOB cell. Thus, we need not perform compactions of
174 the MOB hfiles nearly as often as normal hfiles. As a result, HBase saves IO by not rewriting MOB
175 hfiles as a part of the periodic compactions a Region Server does on its own.
177 However, if deletes and updates of MOB cells are frequent then this indirection will begin to waste
178 space. The only way to stop using the space of a particular MOB hfile is to ensure no cells still
179 hold references to it. To do that we need to ensure we have written the current values into a new
180 MOB hfile. If our backing filesystem has a limitation on the number of files that can be present, as
181 HDFS does, then even if we do not have deletes or updates of MOB cells eventually there will be a
182 sufficient number of MOB hfiles that we will need to coalesce them.
184 Periodically a chore in the master coordinates having the region servers
185 perform a special major compaction that also handles rewriting new MOB files. Like all compactions
186 the Region Server will create updated hfiles that hold both the cells that are smaller than the MOB
187 threshold and cells that hold references to the newly rewritten MOB file. Because this rewriting has
188 the advantage of looking across all active cells for the region our several small MOB files should
189 end up as a single MOB file per region. The chore defaults to running weekly and can be
190 configured by setting `hbase.mob.compaction.chore.period` to the desired period in seconds.
192 ====
193 [source,xml]
194 ----
195 <property>
196     <name>hbase.mob.compaction.chore.period</name>
197     <value>2592000</value>
198     <description>Example of changing the chore period from a week to a month.</description>
199 </property>
200 ----
201 ====
203 By default, the periodic MOB compaction coordination chore will attempt to keep every region
204 busy doing compactions in parallel in order to maximize the amount of work done on the cluster.
205 If you need to tune the amount of IO this compaction generates on the underlying filesystem, you
206 can control how many concurrent region-level compaction requests are allowed by setting
207 `hbase.mob.major.compaction.region.batch.size` to an integer number greater than zero. If you set
208 the configuration to 0 then you will get the default behavior of attempting to do all regions in
209 parallel.
211 ====
212 [source,xml]
213 ----
214 <property>
215     <name>hbase.mob.major.compaction.region.batch.size</name>
216     <value>1</value>
217     <description>Example of switching from "as parallel as possible" to "serially"</description>
218 </property>
219 ----
220 ====
222 ==== MOB file archiving
224 Eventually we will have MOB hfiles that are no longer needed. Either clients will overwrite the
225 value or a MOB-rewriting compaction will store a reference to a newer larger MOB hfile. Because any
226 given MOB cell could have originally been written either in the current region or in a parent region
227 that existed at some prior point in time, individual Region Servers do not decide when it is time
228 to archive MOB hfiles. Instead a periodic chore in the Master evaluates MOB hfiles for archiving.
230 A MOB HFile will be subject to archiving under any of the following conditions:
232 * Any MOB HFile older than the column family's TTL
233 * Any MOB HFile older than a "too recent" threshold with no references to it from the regular hfiles
234   for all regions in a column family
236 To determine if a MOB HFile meets the second criteria the chore extracts metadata from the regular
237 HFiles for each MOB enabled column family for a given table. That metadata enumerates the complete
238 set of MOB HFiles needed to satisfy the references stored in the normal HFile area.
240 The period of the cleaner chore can be configured by setting `hbase.master.mob.cleaner.period` to a
241 positive integer number of seconds. It defaults to running daily. You should not need to tune it
242 unless you have a very aggressive TTL or a very high rate of MOB updates with a correspondingly
243 high rate of non-MOB compactions.
245 === MOB Optimization Tasks
247 ==== Further limiting write amplification
249 If your MOB workload has few to no updates or deletes then you can opt-in to MOB compactions that
250 optimize for limiting the amount of write amplification. It achieves this by setting a
251 size threshold to ignore MOB files during the compaction process. When a given region goes
252 through MOB compaction it will evaluate the size of the MOB file that currently holds the actual
253 value and skip rewriting the value if that file is over threshold.
255 The bound of write amplification in this mode can be approximated as
256 stem:["Write Amplification" = log_K(M/S)] where *K* is the number of files in compaction
257 selection, *M* is the configurable threshold for MOB files size, and *S* is the minmum size of
258 memstore flushes that create MOB files in the first place. For example given 5 files picked up per
259 compaction, a threshold of 1 GB, and a flush size of 10MB the write amplification will be
260 stem:[log_5((1GB)/(10MB)) = log_5(100) = 2.86].
262 If we are using an underlying filesystem with a limitation on the number of files, such as HDFS,
263 and we know our expected data set size we can choose our maximum file size in order to approach
264 this limit but stay within it in order to minimize write amplification. For example, if we expect to
265 store a petabyte and we have a conservative limitation of a million files in our HDFS instance, then
266 stem:[(1PB)/(1M) = 1GB] gives us a target limitation of a gigabyte per MOB file.
268 To opt-in to this compaction mode you must set `hbase.mob.compaction.type` to `optimized`. The
269 default MOB size threshold in this mode is set to 1GB. It can be changed by setting
270 `hbase.mob.compactions.max.file.size` to a positive integer number of bytes.
273 ====
274 [source,xml]
275 ----
276 <property>
277     <name>hbase.mob.compaction.type</name>
278     <value>optimized</value>
279     <description>opt-in to write amplification optimized mob compaction.</description>
280 </property>
281 <property>
282     <name>hbase.mob.compactions.max.file.size</name>
283     <value>10737418240</value>
284     <description>Example of tuning the max mob file size to 10GB</dscription>
285 </property>
286 ----
287 ====
289 Additionally, when operating in this mode the compaction process will seek to avoid writing MOB
290 files that are over the max file threshold. As it is writing out a additional MOB values into a MOB
291 hfile it will check to see if the additional data causes the hfile to be over the max file size.
292 When the hfile of MOB values reaches limit, the MOB hfile is committed to the MOB storage area and
293 a new one is created. The hfile with reference cells will track the complete set of MOB hfiles it
294 needs in its metadata.
296 .Be mindful of total time to complete compaction of a region
297 [WARNING]
298 ====
299 When using the write amplification optimized compaction mode you need to watch for the maximum time
300 to compact a single region. If it nears an hour you should read through the troubleshooting section
301 below <<mob.troubleshoot.cleaner.toonew>>. Failure to make the adjustments discussed there could
302 lead to dataloss.
303 ====
305 [[mob.cache.configure]]
306 ==== Configuring the MOB Cache
309 Because there can be a large number of MOB files at any time, as compared to the number of HFiles,
310 MOB files are not always kept open. The MOB file reader cache is a LRU cache which keeps the most
311 recently used MOB files open. To configure the MOB file reader's cache on each RegionServer, add
312 the following properties to the RegionServer's `hbase-site.xml`, customize the configuration to
313 suit your environment, and restart or rolling restart the RegionServer.
315 .Example MOB Cache Configuration
316 ====
317 [source,xml]
318 ----
319 <property>
320     <name>hbase.mob.file.cache.size</name>
321     <value>1000</value>
322     <description>
323       Number of opened file handlers to cache.
324       A larger value will benefit reads by providing more file handlers per mob
325       file cache and would reduce frequent file opening and closing.
326       However, if this is set too high, this could lead to a "too many opened file handers"
327       The default value is 1000.
328     </description>
329 </property>
330 <property>
331     <name>hbase.mob.cache.evict.period</name>
332     <value>3600</value>
333     <description>
334       The amount of time in seconds after which an unused file is evicted from the
335       MOB cache. The default value is 3600 seconds.
336     </description>
337 </property>
338 <property>
339     <name>hbase.mob.cache.evict.remain.ratio</name>
340     <value>0.5f</value>
341     <description>
342       A multiplier (between 0.0 and 1.0), which determines how many files remain cached
343       after the threshold of files that remains cached after a cache eviction occurs
344       which is triggered by reaching the `hbase.mob.file.cache.size` threshold.
345       The default value is 0.5f, which means that half the files (the least-recently-used
346       ones) are evicted.
347     </description>
348 </property>
349 ----
350 ====
352 ==== Manually Compacting MOB Files
354 To manually compact MOB files, rather than waiting for the
355 periodic chore to trigger compaction, use the
356 `major_compact` HBase shell commands. These commands
357 require the first argument to be the table name, and take a column
358 family as the second argument. If used with a column family that includes MOB data, then
359 these operator requests will result in the MOB data being compacted.
361 ----
362 hbase> major_compact 't1'
363 hbase> major_compact 't2', 'c1’
364 ----
366 This same request can be made via the `Admin.majorCompact` Java API.
368 === MOB Troubleshooting
370 [[mob.troubleshoot.cleaner.toonew]]
371 ==== Adjusting the MOB cleaner's tolerance for new hfiles
373 The MOB cleaner chore ignores all MOB hfiles that were created more recently than an hour prior to
374 the start of the chore to ensure we don't miss the reference metadata from the corresponding regular
375 hfile. Without this safety check it would be possible for the cleaner chore to see a MOB hfile for
376 an in progress flush or compaction and prematurely archive the MOB data. This default buffer should
377 be sufficient for normal use.
379 You will need to adjust the tolerance if you use write amplification optimized MOB compaction and
380 the combination of your underlying filesystem performance and data shape is such that it could take
381 more than an hour to complete major compaction of a single region. For example, if your MOB data is
382 distributed such that your largest region adds 80GB of MOB data between compactions that include
383 rewriting MOB data and your HDFS cluster is only capable of writing 20MB/s for a single file then
384 when performing the optimized compaction the Region Server will take about a minute to write the
385 first 1GB MOB hfile and then another hour and seven minutes to write the remaining seventy-nine 1GB
386 MOB hfiles before finally committing the new reference hfile at the end of the compaction. Given
387 this example, you would need a larger tolerance window.
389 You will also need to adjust the tolerance if Region Server flush operations take longer than an
390 hour for the two HDFS move operations needed to commit both the MOB hfile and the normal hfile that
391 references it. Such a delay should not happen with a normally configured and healthy HDFS and HBase.
393 The cleaner's window for "too recent" is controlled by setting `hbase.mob.min.age.archive` to a
394 positive integer number of milliseconds.
396 ====
397 [source,xml]
398 ----
399 <property>
400     <name>hbase.mob.min.age.archive</name>
401     <value>86400000</value>
402     <description>Example of tuning the cleaner to only archive files older than a day.</dscription>
403 </property>
404 ----
405 ====
407 ==== Retrieving MOB metadata through the HBase Shell
409 While working on troubleshooting failures in the MOB system you can retrieve some of the internal
410 information through the HBase shell by specifying special attributes on a scan.
412 ----
413 hbase(main):112:0> scan 'some_table', {STARTROW => '00012-example-row-key', LIMIT => 1,
414 hbase(main):113:1*     CACHE_BLOCKS => false, ATTRIBUTES => { 'hbase.mob.scan.raw' => '1',
415 hbase(main):114:2*     'hbase.mob.scan.ref.only' => '1' } }
416 ----
418 The MOB internal information is stored as four bytes for the size of the underlying cell value and
419 then a UTF8 string with the name of the MOB HFile that contains the underlying cell value. Note that
420 by default the entirety of this serialized structure will be passed through the HBase shell's binary
421 string converter. That means the bytes that make up the value size will most likely be written as
422 escaped non-printable byte values, e.g. '\x03', unless they happen to correspond to ASCII
423 characters.
425 Let's look at a specific example:
427 ----
428 hbase(main):112:0> scan 'some_table', {STARTROW => '00012-example-row-key', LIMIT => 1,
429 hbase(main):113:1*     CACHE_BLOCKS => false, ATTRIBUTES => { 'hbase.mob.scan.raw' => '1',
430 hbase(main):114:2*     'hbase.mob.scan.ref.only' => '1' } }
431 ROW                        COLUMN+CELL
432  00012-example-row-key     column=foo:bar, timestamp=1511179764, value=\x00\x02|\x94d41d8cd98f00b204
433                            e9800998ecf8427e19700118ffd9c244fe69488bbc9f2c77d24a3e6a
434 1 row(s) in 0.0130 seconds
435 ----
437 In this case the first four bytes are `\x00\x02|\x94` which corresponds to the bytes
438 `[0x00, 0x02, 0x7C, 0x94]`. (Note that the third byte was printed as the ASCII character '|'.)
439 Decoded as an integer this gives us an underlying value size of 162,964 bytes.
441 The remaining bytes give us an HFile name,
442 'd41d8cd98f00b204e9800998ecf8427e19700118ffd9c244fe69488bbc9f2c77d24a3e6a'. This HFile will most
443 likely be stored in the designated MOB storage area for this specific table. However, the file could
444 also be in the archive area if this table is from a restored snapshot. Furthermore, if the table is
445 from a cloned snapshot of a different table then the file could be in either the active or archive
446 area of that source table. As mentioned in the explanation of MOB reference cells above, the Region
447 Server will use a server side tag to optimize looking at the mob and archive area of the correct
448 original table when finding the MOB HFile. Since your scan is client side it can't retrieve that tag
449 and you'll either need to already know the lineage of your table or you'll need to search across all
450 tables.
452 Assuming you are authenticated as a user with HBase superuser rights, you can search for it:
453 ----
454 $> hdfs dfs -find /hbase -name \
455     d41d8cd98f00b204e9800998ecf8427e19700118ffd9c244fe69488bbc9f2c77d24a3e6a
456 /hbase/mobdir/data/default/some_table/372c1b27e3dc0b56c3a031926e5efbe9/foo/d41d8cd98f00b204e9800998ecf8427e19700118ffd9c244fe69488bbc9f2c77d24a3e6a
457 ----
459 ==== Moving a column family out of MOB
461 If you want to disable MOB on a column family you must ensure you instruct HBase to migrate the data
462 out of the MOB system prior to turning the feature off. If you fail to do this HBase will return the
463 internal MOB metadata to applications because it will not know that it needs to resolve the actual
464 values.
466 The following procedure will safely migrate the underlying data without requiring a cluster outage.
467 Clients will see a number of retries when configuration settings are applied and regions are
468 reloaded.
470 .Procedure: Stop MOB maintenance, change MOB threshold, rewrite data via compaction
471 . Ensure the MOB compaction chore in the Master is off by setting
472 `hbase.mob.compaction.chore.period` to `0`. Applying this configuration change will require a
473 rolling restart of HBase Masters. That will require at least one fail-over of the active master,
474 which may cause retries for clients doing HBase administrative operations.
475 . Ensure no MOB compactions are issued for the table via the HBase shell for the duration of this
476 migration.
477 . Use the HBase shell to change the MOB size threshold for the column family you are migrating to a
478 value that is larger than the largest cell present in the column family. E.g. given a table named
479 'some_table' and a column family named 'foo' we can pick one gigabyte as an arbitrary "bigger than
480 what we store" value:
482 ----
483 hbase(main):011:0> alter 'some_table', {NAME => 'foo', MOB_THRESHOLD => '1000000000'}
484 Updating all regions with the new schema...
485 9/25 regions updated.
486 25/25 regions updated.
487 Done.
488 0 row(s) in 3.4940 seconds
489 ----
491 Note that if you are still ingesting data you must ensure this threshold is larger than any cell
492 value you might write; MAX_INT would be a safe choice.
494 . Perform a major compaction on the table. Specifically you are performing a "normal" compaction and
495 not a MOB compaction.
497 ----
498 hbase(main):012:0> major_compact 'some_table'
499 0 row(s) in 0.2600 seconds
500 ----
502 . Monitor for the end of the major compaction. Since compaction is handled asynchronously you'll
503 need to use the shell to first see the compaction start and then see it end.
505 HBase should first say that a "MAJOR" compaction is happening.
507 ----
508 hbase(main):015:0> @hbase.admin(@formatter).instance_eval do
509 hbase(main):016:1*   p @admin.get_compaction_state('some_table').to_string
510 hbase(main):017:2* end
511 “MAJOR”
512 ----
514 When the compaction has finished the result should print out "NONE".
516 ----
517 hbase(main):015:0> @hbase.admin(@formatter).instance_eval do
518 hbase(main):016:1*   p @admin.get_compaction_state('some_table').to_string
519 hbase(main):017:2* end
520 “NONE”
521 ----
522 . Run the _mobrefs_ utility to ensure there are no MOB cells. Specifically, the tool will launch a
523 Hadoop MapReduce job that will show a job counter of 0 input records when we've successfully
524 rewritten all of the data.
526 ----
527 $> HADOOP_CLASSPATH=/etc/hbase/conf:$(hbase mapredcp) yarn jar \
528     /some/path/to/hbase-shaded-mapreduce.jar mobrefs mobrefs-report-output some_table foo
530 19/12/10 11:38:47 INFO impl.YarnClientImpl: Submitted application application_1575695902338_0004
531 19/12/10 11:38:47 INFO mapreduce.Job: The url to track the job: https://rm-2.example.com:8090/proxy/application_1575695902338_0004/
532 19/12/10 11:38:47 INFO mapreduce.Job: Running job: job_1575695902338_0004
533 19/12/10 11:38:57 INFO mapreduce.Job: Job job_1575695902338_0004 running in uber mode : false
534 19/12/10 11:38:57 INFO mapreduce.Job:  map 0% reduce 0%
535 19/12/10 11:39:07 INFO mapreduce.Job:  map 7% reduce 0%
536 19/12/10 11:39:17 INFO mapreduce.Job:  map 13% reduce 0%
537 19/12/10 11:39:19 INFO mapreduce.Job:  map 33% reduce 0%
538 19/12/10 11:39:21 INFO mapreduce.Job:  map 40% reduce 0%
539 19/12/10 11:39:22 INFO mapreduce.Job:  map 47% reduce 0%
540 19/12/10 11:39:23 INFO mapreduce.Job:  map 60% reduce 0%
541 19/12/10 11:39:24 INFO mapreduce.Job:  map 73% reduce 0%
542 19/12/10 11:39:27 INFO mapreduce.Job:  map 100% reduce 0%
543 19/12/10 11:39:35 INFO mapreduce.Job:  map 100% reduce 100%
544 19/12/10 11:39:35 INFO mapreduce.Job: Job job_1575695902338_0004 completed successfully
545 19/12/10 11:39:35 INFO mapreduce.Job: Counters: 54
547         Map-Reduce Framework
548                 Map input records=0
550 19/12/09 22:41:28 INFO mapreduce.MobRefReporter: Finished creating report for 'some_table', family='foo'
551 ----
553 If the data has not successfully been migrated out, this report will show both a non-zero number
554 of input records and a count of mob cells.
556 ----
557 $> HADOOP_CLASSPATH=/etc/hbase/conf:$(hbase mapredcp) yarn jar \
558     /some/path/to/hbase-shaded-mapreduce.jar mobrefs mobrefs-report-output some_table foo
560 19/12/10 11:44:18 INFO impl.YarnClientImpl: Submitted application application_1575695902338_0005
561 19/12/10 11:44:18 INFO mapreduce.Job: The url to track the job: https://busbey-2.gce.cloudera.com:8090/proxy/application_1575695902338_0005/
562 19/12/10 11:44:18 INFO mapreduce.Job: Running job: job_1575695902338_0005
563 19/12/10 11:44:26 INFO mapreduce.Job: Job job_1575695902338_0005 running in uber mode : false
564 19/12/10 11:44:26 INFO mapreduce.Job:  map 0% reduce 0%
565 19/12/10 11:44:36 INFO mapreduce.Job:  map 7% reduce 0%
566 19/12/10 11:44:45 INFO mapreduce.Job:  map 13% reduce 0%
567 19/12/10 11:44:47 INFO mapreduce.Job:  map 27% reduce 0%
568 19/12/10 11:44:48 INFO mapreduce.Job:  map 33% reduce 0%
569 19/12/10 11:44:50 INFO mapreduce.Job:  map 40% reduce 0%
570 19/12/10 11:44:51 INFO mapreduce.Job:  map 53% reduce 0%
571 19/12/10 11:44:52 INFO mapreduce.Job:  map 73% reduce 0%
572 19/12/10 11:44:54 INFO mapreduce.Job:  map 100% reduce 0%
573 19/12/10 11:44:59 INFO mapreduce.Job:  map 100% reduce 100%
574 19/12/10 11:45:00 INFO mapreduce.Job: Job job_1575695902338_0005 completed successfully
575 19/12/10 11:45:00 INFO mapreduce.Job: Counters: 54
577         Map-Reduce Framework
578                 Map input records=1
580         MOB
581                 NUM_CELLS=1
583 19/12/10 11:45:00 INFO mapreduce.MobRefReporter: Finished creating report for 'some_table', family='foo'
584 ----
586 If this happens you should verify that MOB compactions are disabled, verify that you have picked
587 a sufficiently large MOB threshold, and redo the major compaction step.
588 . When the _mobrefs_ report shows that no more data is stored in the MOB system then you can safely
589 alter the column family configuration so that the MOB feature is disabled.
591 ----
592 hbase(main):017:0> alter 'some_table', {NAME => 'foo', IS_MOB => 'false'}
593 Updating all regions with the new schema...
594 8/25 regions updated.
595 25/25 regions updated.
596 Done.
597 0 row(s) in 2.9370 seconds
598 ----
599 . After the column family no longer shows the MOB feature enabled, it is safe to start MOB
600 maintenance chores again. You can allow the default to be used for
601 `hbase.mob.compaction.chore.period` by removing it from your configuration files or restore
602 it to whatever custom value you had prior to starting this process.
603 . Once the MOB feature is disabled for the column family there will be no internal HBase process
604 looking for data in the MOB storage area specific to this column family. There will still be data
605 present there from prior to the compaction process that rewrote the values into HBase's data area.
606 You can check for this residual data directly in HDFS as an HBase superuser.
608 ----
609 $ hdfs dfs -count /hbase/mobdir/data/default/some_table
610            4           54         9063269081 /hbase/mobdir/data/default/some_table
611 ----
613 This data is spurious and may be reclaimed. You should sideline it, verify your application’s view
614 of the table, and then delete it.
616 ==== Data values over than the MOB threshold show up stored in non-MOB hfiles
618 Bulk load and WAL split-to-HFile don't consider MOB threshold and write data into normal hfile (under /hbase/data directory).
620 [NOTE]
621 This won't cause any functional problem, during next compaction such data will be written out to the MOB hfiles.
623 === MOB Upgrade Considerations
625 Generally, data stored using the MOB feature should transparently continue to work correctly across
626 HBase upgrades.
628 ==== Upgrading to a version with the "distributed MOB compaction" feature
630 Prior to the work in HBASE-22749, "Distributed MOB compactions", HBase had the Master coordinate all
631 compaction maintenance of the MOB hfiles. Centralizing management of the MOB data allowed for space
632 optimizations but safely coordinating that management with Region Servers resulted in edge cases that
633 caused data loss (ref link:https://issues.apache.org/jira/browse/HBASE-22075[HBASE-22075]).
635 Users of the MOB feature upgrading to a version of HBase that includes HBASE-22749 should be aware
636 of the following changes:
638 * The MOB system no longer allows setting "MOB Compaction Policies"
639 * The MOB system no longer attempts to group MOB values by the date of the original cell's timestamp
640   according to said compaction policies, daily or otherwise
641 * The MOB system no longer needs to track individual cell deletes through the use of special
642   files in the MOB storage area with the suffix `_del`. After upgrading you should sideline these
643   files.
644 * Under default configuration the MOB system should take much less time to perform a compaction of
645   MOB stored values. This is a direct consequence of the fact that HBase will place a much larger
646   load on the underlying filesystem when doing compactions of MOB stored values; the additional load
647   should be a multiple on the order of magnitude of number of region servers. I.e. for a cluster
648   with three region servers and two masters the default configuration should have HBase put three
649   times the load on HDFS during major compactions that rewrite MOB data when compared to Master
650   handled MOB compaction; it should also be approximately three times as fast.
651 * When the MOB system detects that a table has hfiles with references to MOB data but the reference
652   hfiles do not yet have the needed file level metadata (i.e. from use of the MOB feature prior to
653   HBASE-22749) then it will refuse to archive _any_ MOB hfiles from that table. The normal course of
654   periodic compactions done by Region Servers will update existing hfiles with MOB references, but
655   until a given table has been through the needed compactions operators should expect to see an
656   increased amount of storage used by the MOB feature.
657 * Performing a compaction with type "MOB" no longer has special handling to compact specifically the
658   MOB hfiles. Instead it will issue a warning and do a compaction of the table. For example using
659   the HBase shell as follows will result in a warning in the Master logs followed by a major
660   compaction of the 'example' table in its entirety or for the 'big' column respectively.
662 ----
663 hbase> major_compact 'example', nil, 'MOB'
664 hbase> major_compact 'example', 'big', 'MOB'
665 ----
667 The same is true for directly using the Java API for
668 `admin.majorCompact(TableName.valueOf("example"), CompactType.MOB)`.
669 * Similarly, manually performing a major compaction on a table or region will also handle compacting
670   the MOB stored values for that table or region respectively.
672 The following configuration setting has been deprecated and replaced:
674 * `hbase.master.mob.ttl.cleaner.period` has been replaced with `hbase.master.mob.cleaner.period`
676 The following configuration settings are no longer used:
678 * `hbase.mob.compaction.mergeable.threshold`
679 * `hbase.mob.delfile.max.count`
680 * `hbase.mob.compaction.batch.size`
681 * `hbase.mob.compactor.class`
682 * `hbase.mob.compaction.threads.max`