> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enable Maia runner heap dumps

export const m_runner = "Maia runner";

export const maia = "Maia";

export const RunnerMetadata = ({runnerType, platforms = []}) => {
  return <div style={{
    background: 'var(--colors-background-light, #f9fafb)',
    border: '1px solid var(--colors-border-default, #e5e7eb)',
    borderRadius: '12px',
    padding: '20px 28px',
    marginBottom: '28px'
  }}>
      <table style={{
    width: '100%',
    borderCollapse: 'collapse'
  }}>
        <tbody>
          <tr>
            <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    paddingBottom: '14px',
    whiteSpace: 'nowrap',
    verticalAlign: 'middle',
    width: '180px'
  }}>Runner type</td>
            <td style={{
    paddingBottom: '14px',
    verticalAlign: 'middle'
  }}>{runnerType}</td>
          </tr>
          <tr>
            <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    whiteSpace: 'nowrap',
    verticalAlign: 'middle'
  }}>Runner platform</td>
            <td style={{
    verticalAlign: 'middle'
  }}>
              <div style={{
    display: 'flex',
    flexWrap: 'wrap',
    gap: '8px'
  }}>
                {platforms.map((platform, i) => <span key={i} style={{
    background: '#dcfce7',
    color: '#15803d',
    border: '1px solid #bbf7d0',
    borderRadius: '9999px',
    padding: '3px 12px',
    fontSize: '0.85rem',
    fontWeight: '500',
    whiteSpace: 'nowrap'
  }}>
                    {platform} ✅
                  </span>)}
              </div>
            </td>
          </tr>
        </tbody>
      </table>
    </div>;
};

<RunnerMetadata runnerType={`${maia} Hybrid`} platforms={["AWS", "Azure"]} />

A heap dump can be a useful tool for diagnosing out of memory (OOM) events in the {m_runner}. If you enable heap dumps for a {m_runner}, they can be sent to Matillion for analysis in the event of errors. This document provides instructions on how to enable heap dumps for the {m_runner}, as well as options for sanitizing heap dumps and creating heap dump reports to protect sensitive data.

***

## Enable Maia runner heap dumps

Heap dumps can be enabled for Java OOM events by configuring an environment variable for your {m_runner}. Set the following environment variable:

```
ENABLE_HEAP_DUMP = TRUE
```

Setting this will create heap dumps in the {m_runner} service, writing them to `/home/agentuser/heap-dump` by default. To change this location, set the environment variable `HEAP_DUMP_PATH` to the required directory.

Read [Adding or updating AWS environment variables](/docs/guides/optional-runner-parameters#adding-or-updating-aws-environment-variables) or [Adding or updating Azure environment variables](/docs/guides/optional-runner-parameters#adding-or-updating-azure-environment-variables) for instructions on how to set environment variables for your {m_runner}.

***

## Storing heap dumps

With the {m_runner} deployed in a containerized environment, heap dumps won't persist when the container restarts. To persist the heap dump, it will have to be stored externally to the {m_runner} container. This will require `HEAP_DUMP_PATH` to be mapped externally.

The method used for storing heap dumps externally will depend on your environment and setup. The following documents describe your options:

* Options for AWS (mounting Amazon EFS and transferring files to S3):

  * [Use Amazon EFS volumes with Amazon ECS - Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/efs-volumes.html).
  * [What is AWS DataSync? - AWS DataSync](https://docs.aws.amazon.com/datasync/latest/userguide/what-is-datasync.html).
  * [Configuring AWS DataSync transfers with Amazon EFS - AWS DataSync](https://docs.aws.amazon.com/datasync/latest/userguide/create-efs-location.html).
  * [Configuring AWS DataSync transfers with Amazon S3 - AWS DataSync](https://docs.aws.amazon.com/datasync/latest/userguide/create-s3-location.html).

* Options for Azure (ACI):

  * [Mount Azure Files volume to container group - Azure Container Instances](https://learn.microsoft.com/en-us/azure/container-instances/container-instances-volume-azure-files).

Your DevOps team will be able to advise on the best option for your environment.

***

## Sanitize heap dumps

Before sending heap dumps externally, we recommend sanitizing the heap dump files. This process removes variable data to protect sensitive information.

We recommend the Java application **Heap Dump Tool** is used to sanitize heap dump files. You will need Java installed to use the tool.

To download the tool:

1. Browse to `https://mvnrepository.com/artifact/com.paypal/heap-dump-tool`.
2. Choose the latest version.
3. Select the `jar` download link.

To run the tool, use the following command, replacing `<heapdump-file-name>` with the name of your heap dump file:

```
java -jar heap-dump-tool.jar sanitize <heapdump-file-name>.hprof heapdump-sanitised.hprof
```

Running this command creates a new file called `heapdump-sanitised.hprof` with variable data removed. This file can be shared with Matillion for analysis without exposing sensitive data.

***

## Create heap dump report

If preferred, you can further reduce the data sent to Matillion by creating a heap dump report. This process uses the **Eclipse Memory Analyzer Tool** (MAT) to create a report from the heap dump file, which can be shared with Matillion for analysis.

You can obtain the MAT from the Eclipse Foundation website at [https://eclipse.dev/mat/](https://eclipse.dev/mat/).

To use the tool:

1. Move your sanitized heap dump file to a new directory, so it's the only file in the directory. The MAT will create additional files in this directory.
2. Open your sanitized heap dump with the MAT.
3. Once the heap dump has loaded, select **Leak Suspects Report** in the **Getting Started Wizard**. This will create report files in the same directory as the heap dump.
4. The file `heapdump-sanitised_Leak_Suspects.zip` contains an HTML Leak Suspects report. You can send just this zip file to Matillion for analysis.

For more information on using the tool, read the [MAT documentation](https://eclipse.dev/mat/documentation/).