| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE html |
| PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-us" lang="en-us"> |
| <head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| |
| <meta name="generator" content="DITA-OT" /><meta name="DC.type" content="task" /> |
| <meta name="DC.title" content="Export Heap Dump" /> |
| <meta name="copyright" content="Copyright (c) 2018,2020 IBM Corporation. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-2.0/ " type="primary" /> |
| <meta name="DC.rights.owner" content="Copyright (c) 2018,2020 IBM Corporation. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-2.0/ " type="primary" /> |
| <meta name="DC.format" content="XHTML" /> |
| <meta name="DC.identifier" content="task_exportdump" /> |
| <meta name="DC.language" content="en-us" /> |
| <link rel="stylesheet" type="text/css" href="../styles/commonltr.css" /> |
| <title>Export Heap Dump</title> |
| </head> |
| <body id="task_exportdump"> |
| |
| <h1 class="title topictitle1" id="ariaid-title1">Export Heap Dump</h1> |
| |
| |
| |
| <div class="body taskbody"> |
| <div class="section context"> |
| <p class="p">A whole snapshot can be exported as a new HPROF format file by |
| using |
| the 'Export Snapshot' query. |
| This query can be used to convert a DTFJ core dump to HPROF format, or to redact sensitive data, |
| or to obfuscate class and method names in a dump. |
| </p> |
| |
| <ul class="ul"> |
| <li class="li"> |
| Choose the |
| <span class="keyword parmname">output</span> |
| file name, extension '.hprof'. |
| </li> |
| |
| <li class="li"> |
| The |
| <span class="keyword parmname">compress</span> |
| option allows the HPROF file to be compressed using the Gzip |
| format. The file should be given an extension of <span class="ph filepath">.hprof.gz</span>. |
| The HPROF file will take up less disk space, but will take longer to read |
| when parsed in Memory Analyzer. |
| </li> |
| |
| <li class="li"> |
| If required then certain data can be redacted from the output file, |
| to reduce the risk of passwords or other sensitive data being read |
| by |
| anyone analyzing the newly generated HPROF file. The |
| <span class="keyword parmname">redact</span> |
| option has |
| several choices: |
| <dl class="dl"> |
| |
| <dt class="dt dlterm">NONE |
| </dt> |
| |
| <dd class="dd">No redaction - all data is available in the new HPROF file. |
| </dd> |
| |
| |
| |
| <dt class="dt dlterm">NAMES |
| </dt> |
| |
| <dd class="dd"><span class="keyword apiname">char</span> and <span class="keyword apiname">byte</span> arrays which match a class or field name which is to be obfuscated get changed to the |
| obfuscated name. |
| An attempt is also made to obfuscate class names in <span class="keyword apiname">char</span> and <span class="keyword apiname">byte</span> arrays which are a Java method |
| or type signature. |
| This helps hide the true class and field names when obfuscation of class and field names is selected by the <span class="keyword parmname">map</span> |
| option, as sometimes class and field names are held in strings referenced by the <span class="keyword apiname">Class</span> object. |
| It is only approximate, as class and field names which are just part of a <span class="keyword apiname">char</span> or <span class="keyword apiname">byte</span> array |
| will not be changed. |
| All other field and array values are unchanged. |
| </dd> |
| |
| |
| |
| <dt class="dt dlterm">BASIC |
| </dt> |
| |
| <dd class="dd"> |
| <span class="keyword apiname">char</span> |
| arrays, |
| <span class="keyword apiname">byte</span> |
| arrays, |
| <span class="keyword apiname">int</span> |
| arrays, |
| <span class="keyword apiname">char</span> |
| fields and |
| <span class="keyword apiname">byte</span> |
| fields are redacted. |
| This removes some sensitive data, such as passwords and the majority |
| of |
| <span class="keyword apiname">BigInteger</span> |
| object contents, |
| which might hold private keys. |
| It leaves other data such as |
| <span class="keyword apiname">int</span> |
| fields, and |
| <span class="keyword apiname">boolean</span> |
| , |
| <span class="keyword apiname">long</span> |
| , |
| <span class="keyword apiname">float</span> |
| , |
| <span class="keyword apiname">double</span> |
| fields and arrays. |
| which might also contain sensitive information such as personal ID |
| numbers or financial |
| information. Those fields might be useful however for solving some sorts of |
| problems. |
| </dd> |
| |
| |
| |
| <dt class="dt dlterm">FULL |
| </dt> |
| |
| <dd class="dd">All fields and arrays are set to zero or false values, so removing |
| many examples of sensitive data. |
| Object reference fields and arrays are preserved, together with array |
| sizes, as these |
| are necessary to identify causes of out of memory errors. There is |
| a chance that numbers of, |
| sizes, and links between objects might hold sensitive information. |
| </dd> |
| |
| |
| </dl> |
| |
| <table role="presentation" border="1" class="note hazardstatement"><tr><th colspan="2" class="hazardstatement--notice">Notice</th></tr><tr><td><img class="image hazardsymbol" src="../mimes/message_warning.png" alt="Warning triangle" /></td><td><div class="messagepanel"> |
| <div class="typeofhazard"> |
| Information disclosure |
| </div> |
| <div class="consequence"> |
| Incorrect use of these options may leave sensitive data in the new dump. |
| If this dump is then given to an unauthorised person the |
| sensitive data may |
| be extracted and disclosed. |
| </div> |
| <div class="howtoavoid"> |
| Review the correct use of these options. |
| </div> |
| <div class="howtoavoid"> |
| Examine the newly generated HPROF file, for example with Memory |
| Analyzer, to |
| confirm that no sensitive data is visible. |
| </div> |
| </div></td></tr></table> |
| </li> |
| |
| <li class="li"> |
| <p class="p">Class names, field names and method names can hold sensitive |
| information about the |
| nature of the application. The <span class="keyword parmname">map</span> option allows the names to be |
| mapped to obfuscated names, |
| hiding the true nature of the application when the new dump is inspected. |
| Consider using at least <span class="keyword cmdname">redact=NAMES</span> or |
| <span class="keyword cmdname">redact=BASIC</span> option as well to hide class, field and method names held in |
| <span class="keyword apiname">byte</span> and <span class="keyword apiname">char</span> arrays. |
| </p> |
| |
| <p class="p"> |
| The |
| <span class="keyword parmname">map</span> |
| option gives a file into which will be stored |
| the mapping from original class name to new class name. |
| This allows the results of analysis of the new HPROF file to be |
| manually converted back |
| to class names of the original file. |
| Any existing mappings in the file are read at the start and are used, |
| and the full list of old and any new mappings are output at the end. |
| Also if several related |
| snapshots are to be exported |
| then the same mapping file should be used so that all the new HPROF |
| files have the same new class names for the same old class names. |
| If this option is omitted, no obfuscation will be done. |
| </p> |
| |
| <p class="p"> |
| It is normally better to retain the names of |
| Java API classes, or at least those of the '<span class="keyword apiname">java.lang.</span>' package, as all |
| applications use them, |
| and having the true names available makes the analysis of the new |
| HPROF file a little easier. |
| The |
| <span class="keyword parmname">skip</span> |
| option allows this to be controlled. |
| </p> |
| |
| <p class="p"> |
| The |
| <span class="keyword parmname">exclude</span> |
| option allows certain phrases or words to be excluded from the |
| generated names. |
| This might be useful if the generated names might otherwise include |
| unpronouncable or unsuitable characer |
| sequences. |
| </p> |
| |
| <p class="p"> |
| The |
| <span class="keyword parmname">undo</span> |
| option allows the mapping operation to be reversed if |
| the original snapshot file has been lost and only the |
| mapped HPROF file and the mapping file are available. |
| </p> |
| |
| <table role="presentation" border="1" class="note hazardstatement"><tr><th colspan="2" class="hazardstatement--notice">Notice</th></tr><tr><td><img class="image hazardsymbol" src="../mimes/message_warning.png" alt="Warning triangle" /></td><td><div class="messagepanel"> |
| <div class="typeofhazard"> |
| Information disclosure |
| </div> |
| <div class="consequence"> |
| Incorrect use of these options may leave sensitive information about the |
| application design in the new dump. |
| If this dump is then given to an unauthorised person, sensitive |
| information about the application may |
| be extracted and disclosed. |
| </div> |
| <div class="howtoavoid"> |
| Review the correct use of these options. |
| </div> |
| <div class="howtoavoid"> |
| Examine the newly generated HPROF file, for example with Memory |
| Analyzer, to |
| confirm that no sensitive data is visible. |
| </div> |
| <div class="howtoavoid"> |
| Do not pass the mapping file to an unauthorised person as it contains |
| the true names of classes, fields and methods of the application. |
| </div> |
| </div></td></tr></table> |
| <table role="presentation" border="1" class="note hazardstatement"><tr><th colspan="2" class="hazardstatement--notice">Notice</th></tr><tr><td><img class="image hazardsymbol" src="../mimes/message_warning.png" alt="Warning triangle" /></td><td><div class="messagepanel"> |
| <div class="typeofhazard"> |
| Offensive content |
| </div> |
| <div class="consequence"> |
| As the class, method and field names are randomly generated there is the |
| possibility of offensive words occuring in the names. |
| </div> |
| <div class="howtoavoid"> |
| Use the <span class="keyword parmname">avoid</span> option to filter out words. |
| </div> |
| <div class="howtoavoid"> |
| Examine the generated mapping file to confirm that no offensive words |
| have been generated. If they have, delete the mapping file and |
| export the dump again. |
| </div> |
| </div></td></tr></table> |
| </li> |
| |
| <li class="li"> |
| <p class="p"> |
| Normally the whole snapshot is exported. Sometimes it might be |
| useful to export |
| a subset of all the objects. For example if the original dump was |
| parsed with the |
| <span class="keyword parmname">keep unreachable objects</span> |
| option the unreachable objects will be retained by some created |
| dummy |
| <a class="xref" href="../concepts/gcroots.html"><span class="keyword parmname">UNREACHABLE</span></a> |
| roots. It might be desired to create a new smaller HPROF file without |
| these objects. |
| </p> |
| |
| <p class="p"> |
| To create a HPROF file without the unreachable objects, either |
| reparse without the |
| <a class="xref" href="configure_mat.html"><span class="keyword parmname">keep unreachable objects</span></a> |
| option then export the entire snapshot, or else run the |
| <span class="keyword cmdname">GC Roots</span> |
| query, then |
| select all roots except the |
| <span class="keyword parmname">UNREACHABLE</span> |
| roots, find the retained set of those other |
| roots, then select all the objects and use the context menu to export |
| the snapshot for the selected objects. |
| </p> |
| |
| <p class="p"> |
| Use this option with care - a dump exported without many objects |
| such as classes, or class loaders, |
| or objects from the |
| '<span class="keyword apiname">java.lang.</span>' |
| package may have broken links and be hard to |
| interpret. |
| </p> |
| |
| </li> |
| |
| <li class="li"> |
| <p class="p">The export query can be run in <a class="xref" href="batch.html">batch mode</a>. |
| To export a new copy of the heap dump with redactions use |
| <kbd class="ph userinput"> |
| <span class="keyword cmdname">./mat/ParseHeapDump.sh</span> |
| <var class="keyword varname">myheapdump.hprof</var> |
| <span class="keyword option">-output=</span><var class="keyword varname">myheapdump2.hprof</var> |
| <span class="keyword option">-redact=BASIC</span> |
| <span class="keyword option">-map=</span><var class="keyword varname">myheapdump2.map</var> |
| <span class="keyword parmname">org.eclipse.mat.hprof:export</span> |
| </kbd> |
| Other options to consider are: |
| <kbd class="ph userinput"> |
| <span class="keyword option">-skip=</span><var class="keyword varname">"java\\..*|boolean|byte|char|short|int|long|float|double|void"</var> |
| <span class="keyword option">-avoid=</span><var class="keyword varname">".*ae.*|.*oe.*|.*uu.*|.*kr.*|.*kw.*|.*[cC]ie.*|.*[^c]ei.*"</var> |
| <span class="keyword option">-options=</span><span class="keyword parmname">"-compress"</span> |
| </kbd> |
| </p> |
| |
| </li> |
| |
| </ul> |
| |
| </div> |
| |
| </div> |
| |
| </body> |
| </html> |
