Actuators: Types, Operation, Selection, and Control

Heapdump Endpoint

Learn how to enable, secure, download, and analyze the Spring Boot Actuator heapdump endpoint, including HPROF files, retained heap, GC roots, and production risks.

The Spring Boot Actuator heapdump endpoint generates a binary snapshot of objects and memory relationships in a running Java Virtual Machine (JVM). Operators can download that snapshot and inspect it with tools such as Eclipse Memory Analyzer (MAT) or VisualVM.

A heap dump is valuable when memory usage grows unexpectedly, a suspected memory leak exists, or the application reports OutOfMemoryError. It is also highly sensitive: the dump may contain application data, credentials, tokens, request content, and personal information.

What a heap dump contains

A heap dump records information about objects currently allocated in the JVM heap. Depending on the JVM and dump options, it can include object classes, object fields, arrays, object sizes, and references between objects. These references show why an object is still reachable and therefore cannot be collected.

The common HPROF format is a Java profiling and heap-dump format. The exact contents, supported options, file format, and generation behavior depend on the JVM implementation and runtime configuration. A heap dump is not normally a readable text report; it is a binary diagnostic file.

Heap dump versus runtime metrics

Metrics can indicate that memory is a problem. A heap dump can help explain which objects are consuming memory and what references retain them. Because dump generation can pause or burden an application, metrics and logs should normally be used to identify an appropriate capture time.

Spring Boot Actuator heapdump endpoint

Spring Boot Actuator provides management and monitoring endpoints. The heap dump endpoint has the endpoint ID heapdump and, by default, is addressed over HTTP at /actuator/heapdump.

When requested on a supported JVM and correctly exposed, the endpoint asks the JVM to generate a heap dump and returns the resulting file in the HTTP response. The operation may take substantial time and resources, especially for a large heap.

Availability and web exposure

Two separate questions determine whether an Actuator endpoint can be used:

1. Availability: Is Actuator present, and does the application and runtime provide the endpoint?
2. Web exposure: Is the endpoint reachable through the HTTP management interface?

Adding Actuator does not mean every endpoint is automatically reachable over HTTP. Web exposure is controlled with management.endpoints.web.exposure.include. For example:

management.endpoints.web.exposure.include=heapdump

To expose a selected group of operational endpoints:

management.endpoints.web.exposure.include=health,info,heapdump

Expose only the endpoints that are operationally required. Broad exposure settings can unintentionally publish sensitive management functions.

Management base path and port

The default management base path is /actuator. It can be changed, for example:

management.endpoints.web.base-path=/manage

With that setting, the endpoint becomes /manage/heapdump. A separate management server port also changes the host and port used to request it. A reverse proxy may add another external path prefix, so verify the effective route in the deployment rather than assuming the application URL.

Endpoint access controls

Exposure is not authorization. An exposed endpoint still needs authentication and authorization when management access is protected. Spring Security rules, a gateway, firewall rules, and network segmentation can all affect access.

Current Spring Boot versions may also support endpoint-specific access settings. The exact options and semantics are version-dependent; where supported, a restricted policy can be illustrated with:

management.endpoint.heapdump.access=restricted

Check the Spring Boot version documentation and the application's effective configuration before relying on this property. Use it together with authentication, authorization, and network controls rather than as a replacement for them.

Development environments may expose the endpoint temporarily on localhost. Production environments should generally keep it unexposed until an authorized diagnostic capture is required, and should use a dedicated management port or network where practical. See the general Spring Boot Actuator overview for related endpoint configuration concepts.

Requesting and saving a heap dump

Request the endpoint with an HTTP client that writes the binary response directly to a file. For a protected local endpoint:

curl -u username:password -o application-heap.hprof http://localhost:8080/actuator/heapdump

With a custom management base path:

curl -u username:password -o application-heap.hprof http://localhost:8080/manage/heapdump

In real environments, avoid placing long-lived passwords in shell history or process listings. Prefer the credential mechanism approved for the environment, such as a short-lived token or service identity. Confirm that the identity has permission to invoke this diagnostic operation.

The response is binary. Opening the URL in a browser may start a download, display meaningless characters, or be intercepted by an authentication page. A command-line client or an approved diagnostic tool makes it easier to verify the status code, headers, and saved file.

Verify the download

• Check that the HTTP response indicates success rather than an error.
• Confirm that the file is not suspiciously small and that its size is plausible for the application's heap.
• Ensure the client, proxy, and load balancer completed the transfer.
• Keep the original file unchanged if it may be needed for investigation.
• Store it in an access-controlled location and record when and from which instance it was captured.

Heap dump analysis workflow

1. Choose the capture moment. Use JVM memory metrics, garbage-collection behavior, logs, and application symptoms to capture when memory is elevated or the suspected objects are present.
2. Open the file. Use Eclipse Memory Analyzer (MAT), VisualVM, or another tool that supports the JVM's dump format. Large dumps require substantial local disk space and often additional analysis memory.
3. Start with retained size. Locate classes, collections, caches, sessions, listeners, or request-related structures with unusually high retained memory.
4. Inspect the dominator tree. This view groups objects by the references that keep other objects reachable. It helps prioritize object graphs that account for the largest amount of memory.
5. Follow GC-root paths. A GC root is a reference source that keeps an object reachable and prevents garbage collection. Trace the path from a suspicious object to a root to understand why it remains alive.
6. Compare evidence. Match the object graph with request rates, deployment changes, cache behavior, thread activity, logs, and JVM metrics. One dump shows a state; repeated captures or controlled reproduction help establish growth over time.

Retained heap is especially useful because a small reference object may retain a very large collection. A high retained size is evidence for investigation, not automatic proof of a leak. A cache with an intended bound can look large but be correct; an unbounded map or forgotten listener may indicate a memory leak.

Operational and security considerations

Heap dump generation can consume CPU, I/O, memory, and container disk space. The response can be large and may take a long time to transfer. A proxy timeout or download limit can leave an incomplete file. Capture planning is therefore part of the diagnosis, not an afterthought.

Heap contents can include passwords, access tokens, personal data, database results, request bodies, session information, and internal configuration values. Treat every dump as sensitive production data.

Do not expose /actuator/heapdump to the public internet. Prefer a dedicated management network or port, allow-listed operator access, strong authentication, and an authorization rule limited to trusted diagnostic personnel. If a dump must leave the production environment, encrypt it in transit and at rest, minimize distribution, and remove it when the retention policy permits.

JVM and deployment limitations

Generation depends on JVM support, the runtime version, available permissions, and configuration. A compatible Spring Boot application can still fail to produce a usable dump if the runtime does not support the operation or if the process cannot write the file because of disk, permission, or container restrictions.

• Containers: Verify writable temporary storage, ephemeral-disk capacity, memory limits, and whether the downloaded file is written inside or outside the container.
• Large heaps: Reserve enough space for the dump and for analysis. The dump can be comparable to the live heap and may require additional overhead.
• Timeouts: Review curl, reverse-proxy, gateway, and load-balancer timeouts.
• Response limits: Check maximum response sizes and buffering behavior in intermediaries.
• Managed platforms: Platform restrictions may prevent direct access to the JVM process, management port, filesystem, or diagnostic endpoint.
• Runtime differences: Local development, containers, and managed production services may use different JVMs, flags, security policies, and storage behavior.

When the endpoint is unavailable or unsuitable, use an approved JVM-level diagnostic method supported by the deployment platform and JVM. Alternatives may include a platform-provided heap capture, a JVM diagnostic command, Java Flight Recorder for allocation and runtime evidence, or continuous memory metrics. Choose the least disruptive method that answers the diagnostic question.

Troubleshooting

HTTP 404 for /actuator/heapdump

• Actuator may not be on the application classpath.
• The endpoint may not be exposed over HTTP.
• A custom management base path or management port may be in use.
• The application version or runtime may not provide the endpoint.

Review Actuator exposure configuration, the effective management port and base path, and the available Actuator endpoint links. The endpoint list can also reveal that the request is using the wrong route.

HTTP 401 or 403

Management endpoints may require authentication, or the authenticated identity may lack the required role or authority. Check the credentials or service identity, Spring Security rules, and any gateway or network policy enforcing access restrictions.

The file cannot be opened

The saved response may actually be an HTML error page, or the download may be truncated. Check the HTTP status and response headers before saving, compare the file size with expectations, and download again if needed. Confirm that the analysis tool supports the JVM's dump format and use a current version.

Generation or download is slow

A large application heap, limited network bandwidth, or restrictive proxy and client timeouts can cause delays. Check disk space, plan an appropriate capture window, and review timeout and response-size settings across the entire request path.

The endpoint creates a security concern

Immediately review whether untrusted networks or users can reach it. Reduce exposure, enforce authorization, isolate the management interface, and apply secure storage, encryption, controlled sharing, and deletion procedures to existing diagnostic files.

Practical investigation example

Suppose memory usage rises after each batch of requests and remains high after garbage collection. First, verify the endpoint is exposed only on a protected management interface. Capture a dump while usage is elevated, save it with an .hprof extension, and open it in MAT or VisualVM. Use the dominator tree to find objects with high retained heap, then trace their paths to GC roots. If a collection is retained by a static field, unbounded cache, session registry, listener, or request state, compare that finding with application code, request patterns, logs, and metric trends. Capture another dump after controlled traffic or remediation to test whether the object population changes as expected.

Quick checklist

• Confirm Actuator and JVM support.
• Expose only heapdump or another deliberately selected endpoint.
• Verify the effective management path and port.
• Require authentication, authorization, and trusted network access.
• Check disk, memory, timeout, proxy, and response-size constraints.
• Download the binary response to a controlled location.
• Analyze shallow heap, retained heap, dominator trees, and GC-root paths.
• Correlate findings with metrics, logs, and application behavior.
• Encrypt, limit distribution, and delete the dump according to policy.

For adjacent management diagnostics, see the Actuator overview, mappings, configprops, env, logfile, and httptrace endpoints. These endpoints can provide context, but they do not replace a heap snapshot when object retention must be examined.