HeapProfilerService
Generates and retrieves Luau heap memory profiles from the client and server Luau virtual machines for memory debugging.
| Memory category | Instances |
|---|
Member index 4
Description
HeapProfilerService captures snapshots of the Luau heap so that
memory-profiling tools can analyze script memory usage. Requesting a profile
runs a full garbage-collection cycle and then walks the heap of the target
Luau virtual machine, producing a JSON report that breaks memory down by value
type, memory category, and userdata class, together with an aggregated
ownership graph and a list of unique and unparented instance references.
Profiles can be requested for either the server or a specific client. HeapProfilerService:ServerRequestDataAsync() returns the server's profile and HeapProfilerService:ClientRequestDataAsync() returns a given player's client profile. When the profiled machine differs from the caller, the data is generated remotely, compressed, and replicated back through the HeapProfilerService.OnNewData event before the yielding call resolves.
History 7
- 731 Add
- 726 Remove
- 661 Add
- 661 Add OnNewData
- 661 Add ServerRequestDataAsync
- 661 Add ClientRequestDataAsync
- 661 Add HeapProfilerService
Members 4
ClientRequestDataAsync
| Parameters (1) | ||
|---|---|---|
| player | Player | |
| Returns (1) | ||
| string | ||
Requests a Luau heap profile from the client belonging to player. When
called on that client itself, the profile is generated locally and
returned immediately. When called from the server, a request is sent to
the client and this function yields until the compressed profile is
replicated back through HeapProfilerService.OnNewData,
decompressed, and returned. If the client does not respond within 10
seconds, the request fails.
The returned string is JSON containing a Report section (heap memory
broken down by value type, memory category, and userdata class, plus an
aggregated size graph) and a Refs section (unique and unparented
instance references).
| Security | PluginSecurity |
|---|---|
| Thread safety | Unsafe |
History 1
OnNewData
| Parameters (5) | |
|---|---|
| player | Player |
| jsonString | buffer |
| id | int |
| compressedLength | int |
| uncompressedLength | int |
Delivers a Luau heap profile that was generated on a remote machine in
response to a HeapProfilerService:ClientRequestDataAsync() or
HeapProfilerService:ServerRequestDataAsync() call. The profile
JSON is zstd-compressed and carried in jsonString; the receiving service
decompresses it, matches it to the pending request by id, and resolves
the yielding call. The compressedLength and uncompressedLength
arguments report the buffer's size before and after decompression.
| Security | PluginSecurity |
|---|---|
| Thread safety | Unsafe |
ServerRequestDataAsync
| Parameters (0) | ||
|---|---|---|
| No parameters. | ||
| Returns (1) | ||
| string | ||
Requests a Luau heap profile from the server. When called on the server, the profile is generated locally and returned immediately. When called from a client, a request is sent to the server and this function yields until the compressed profile is replicated back through HeapProfilerService.OnNewData, decompressed, and returned. If the server does not respond within 10 seconds, the request fails.
The returned string has the same JSON structure as HeapProfilerService:ClientRequestDataAsync().
| Security | PluginSecurity |
|---|---|
| Thread safety | Unsafe |