# Export Heap Dump

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.

- Choose the output file name, extension '.hprof'.
- The compress option allows the HPROF file to be compressed using the Gzip format. The file should be given an extension of .hprof.gz. The HPROF file will take up less disk space, but will take longer to read when parsed in Memory Analyzer.
- 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 redact option has several choices:
  NONE
    No redaction - all data is available in the new HPROF file.
  NAMES
    char and byte 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 char and byte 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 map option, as sometimes class and field names are held in strings referenced by the Class object. It is only approximate, as class and field names which are just part of a char or byte array will not be changed. All other field and array values are unchanged.
  BASIC
    char arrays, byte arrays, int arrays, char fields and byte fields are redacted. This removes some sensitive data, such as passwords and the majority of BigInteger object contents, which might hold private keys. It leaves other data such as int fields, and boolean , long , float , double 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.
  FULL
    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.

  Notice
  | Information disclosure 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. Review the correct use of these options. Examine the newly generated HPROF file, for example with Memory Analyzer, to confirm that no sensitive data is visible.

- Class names, field names and method names can hold sensitive information about the nature of the application. The map 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 redact=NAMES or redact=BASIC option as well to hide class, field and method names held in byte and char arrays.

  The map 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.

  It is normally better to retain the names of Java API classes, or at least those of the 'java.lang.' package, as all applications use them, and having the true names available makes the analysis of the new HPROF file a little easier. The skip option allows this to be controlled.

  The exclude 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.

  The undo 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.

  Notice

  Information disclosure
  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.
  Review the correct use of these options.
  Examine the newly generated HPROF file, for example with Memory Analyzer, to confirm that no sensitive data is visible.
  Do not pass the mapping file to an unauthorised person as it contains the true names of classes, fields and methods of the application.

  Notice
  | Offensive content As the class, method and field names are randomly generated there is the possibility of offensive words occuring in the names. Use the avoid option to filter out words. 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.

- 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 keep unreachable objects option the unreachable objects will be retained by some created dummy UNREACHABLE roots. It might be desired to create a new smaller HPROF file without these objects.

  To create a HPROF file without the unreachable objects, either reparse without the keep unreachable objects option then export the entire snapshot, or else run the GC Roots query, then select all roots except the UNREACHABLE 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.

  Use this option with care - a dump exported without many objects such as classes, or class loaders, or objects from the 'java.lang.' package may have broken links and be hard to interpret.

- The export query can be run in batch mode. To export a new copy of the heap dump with redactions use `./mat/ParseHeapDump.sh myheapdump.hprof -output=myheapdump2.hprof -redact=BASIC -map=myheapdump2.map org.eclipse.mat.hprof:export` Other options to consider are: `-skip="java\\..*|boolean|byte|char|short|int|long|float|double|void" -avoid=".*ae.*|.*oe.*|.*uu.*|.*kr.*|.*kw.*|.*[cC]ie.*|.*[^c]ei.*" -options="-compress"`