Class
HeapProfilerService
NotCreatableService
Generates and retrieves Luau heap memory profiles from the client and server Luau virtual machines for memory debugging.
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.
Methods 2#
| ClientRequestDataAsync | Yields until the Luau heap profile of the specified player's client is available, then returns it as a JSON string.PluginSecurity securityYields |
| ServerRequestDataAsync | Yields until the server's Luau heap profile is available, then returns it as a JSON string.PluginSecurity securityYields |
ClientRequestDataAsync(player: Player): string#
YieldsPluginSecurity security
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).
Returns
string— A JSON-encoded string containing the client's Luau heap profile.
ServerRequestDataAsync(): string#
YieldsPluginSecurity security
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().
Returns
string— A JSON-encoded string containing the server's Luau heap profile.
Events 1#
| OnNewData | Fires on the requesting machine with the compressed Luau heap profile produced for an earlier request.PluginSecurity security |
OnNewData(player: Player, jsonString: buffer, id: int, compressedLength: int, uncompressedLength: int)#
PluginSecurity security
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.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The Player the profile is being delivered to, or nil when
the data is replicated to the server. | |
jsonString | buffer | A buffer holding the zstd-compressed JSON heap profile. | |
id | int | The identifier of the request this data corresponds to. | |
compressedLength | int | The size, in bytes, of the compressed profile buffer. | |
uncompressedLength | int | The size, in bytes, of the heap profile JSON after decompression. |
Inherited members#
Inherited from Instance 58
Properties (10)
Archivable, archivable, Capabilities, IsInSandbox, Name, Parent, PredictionMode, RobloxLocked, Sandboxed, UniqueId
Methods (39)
AddTag, children, ClearAllChildren, Clone, clone, Destroy, destroy, FindFirstAncestor, FindFirstAncestorOfClass, FindFirstAncestorWhichIsA, FindFirstChild, findFirstChild, FindFirstChildOfClass, FindFirstChildWhichIsA, FindFirstDescendant, GetActor, GetAttribute, GetAttributeChangedSignal, GetAttributes, GetChildren, getChildren, GetDebugId, GetDescendants, GetFullName, GetStyled, GetStyledPropertyChangedSignal, GetTags, HasTag, IsAncestorOf, IsDescendantOf, isDescendantOf, IsPropertyModified, QueryDescendants, Remove, remove, RemoveTag, ResetPropertyToDefault, SetAttribute, WaitForChild