Stats API Usage Guide

api
stats
service

#1

image

Since the new members on this class page haven’t been put up yet and I am unable to edit the member pages, I’ve decided to inform you guys myself about the new APIs under this service and how you can utilize them. This API is now enabled on production so you should be able to use it. I’m not 100% sure if it’s available on mobile platforms, so use this with caution.

For some of these properties, there are stats that measure data related to something called Primitives. Just for reference, a primitive can be described as the internal physics simulation component of a part. It is the abstract descriptor for an individual physics body in Roblox’s physics engine.

Also note that some of these descriptions are merely speculation on my part, and they may not be 100% accurate.

With all that said, lets begin!

GetMemoryUsageMbForTag

float Stats:GetMemoryUsageMbForTag(DeveloperMemoryTag tag)

GetMemoryUsageMbForTag returns the number of megabytes that are being consumed in the specified DeveloperMemoryTag category. There are 23 categories available for this:

Name Memory that is allocated to...
Internal General data that doesn't have any categorization. This could be due to either internal reasons, or because it simply isn't being tracked categorically.
HttpCache A cache of HTTP responses.
Instances All the Instances present in memory.
Signals Events, signals, connections, etc.
LuaHeap All of the data in Lua. this includes everything happening in CoreScripts, the built-in datatypes, etc.
Script All of the data in Lua scripts. This is similar to LuaHeap, but it excludes the memory that is specific to Lua itself.
PhysicsCollision Collision detection in the Workspace.
PhysicsParts Physics bodies and the components that control their behavior.
GraphicsSolidModels Rendering solid models (stuff made with Union, Negate, etc.)
GraphicsMeshParts Rendering of mesh parts.
GraphicsParticles Rendering of particles from ParticleEmitters.
GraphicsParts Rendering of regular parts.
GraphicsSpatialHash Spatial Hash lookup system, which I speculate is responsible for their frustrum culling? [citation needed]
GraphicsTerrain Rendering of terrain voxels.
GraphicsTexture Rendering of textures in the game world.
GraphicsTextureCharacter Rendering of texture composition maps that are generated for Humanoids.
Sounds Data of sounds in-game.
StreamingSounds Playback of sounds in-game.
TerrainVoxels Occupancy/Material data of the Terrain.
Gui Data and rendering of Gui elements.
Animation Playback of Animations on Humanoids and AnimationControllers.
Navigation Pathfinding for Humanoids via the PathfindingService.

Sample usage:

local memoryReportFormat = "\t%s - %.3f MBs"
print("~ BEGIN MEMORY REPORT ~")

for i,memoryTag in ipairs(Enum.DeveloperMemoryTag:GetEnumItems()) do
	local consumption = stats():GetMemoryUsageMbForTag(memoryTag)
	print(memoryReportFormat:format(memoryTag.Name, consumption))
end

print("~ END MEMORY REPORT ~")

ContactsCount

int Stats.ContactsCount [readonly]

ContactsCount describes how many primitives are currently in contact with each other, such that one of the two primitives are being physically simulated, and thus can be recognized by the GetTouchingParts method.

DataReceiveKbps

float Stats.DataReceiveKbps [readonly]

DataReceiveKbps describes roughly how many kilobytes of data are being received by the current instance per second. If from the server’s perspective, this represents the total amount of data being received from the clients connected to the server. If from the client’s perspective, this represents the total amount of data being received from the server.

DataSendKbps

float Stats.DataSendKbps [readonly]

DataSendKbps describes roughly how many kilobytes of data are being sent by the current instance per second. If from the server’s perspective, this represents the total amount of data being sent to the clients connected to the server. If from the client’s perspective, this represents the total amount of data being sent to the server.

HeartbeatTimeMs

float Stats.HeartbeatTimeMs [readonly]

HeartbeatTimeMs describes the total amount of time it takes long it takes for Roblox to update all of it’s Task Scheduler jobs in milliseconds. If this value is high, then it means something is hogging up a lot of resources.

InstanceCount

int Stats.InstanceCount [readonly]

InstanceCount describes how many Instances are currently present in memory. You can use this property to see if you have an Instance memory leak somewhere. The garbage collector runs frequently, and will try to drop this count if it sees an Instance is neither present in the DataModel, nor is being referenced by any active Lua threads.

MovingPrimitivesCount

int Stats.MovingPrimitivesCount [readonly]

MovingPrimitivesCount describes how many primitives are currently awake and being physically simulated in the current game instance. Moving objects are costly, so use them sparingly.

PhysicsReceiveKbps

float Stats.PhysicsReceiveKbps [readonly]

PhysicsReceiveKbps describes roughly how many kilobytes of physics data are being received by the current instance per second. If from the server’s perspective, this represents the total amount of physics data being received from the clients connected to the server. If from the client’s perspective, this represents the total amount of physics data being received from the server.

PhysicsSendKbps

float Stats.PhysicsSendKbps [readonly]

PhysicsSendKbps describes roughly how many kilobytes of physics data are being sent by the current instance per second. If from the server’s perspective, this represents the total amount of physics data being sent to the clients connected to the server. If from the client’s perspective, this represents the total amount of physics data being sent to the server.

PhysicsStepTimeMs

float Stats.PhysicsStepTimeMs [readonly]

PhysicsStepTimeMs describes how long it takes for the physics engine to update it’s current state.
If this value is high, then it means the game instance is under stress from the physics simulations taking place.

PrimitivesCount

int Stats.PrimitivesCount [readonly]

PrimitivesCount describes how many primitives are currently present in the Workspace. This includes all primitives that aren’t being physically simulated, but can still cause a contact interaction to occur.


How can I have 500MB of Untracked memory on a BRAND NEW Server?!
#2

This sounds like something that could have neat usages. (Such as throttling ingame events if mem goes over x megabytes.)


#3

Cool stuff! I’ll have to try this out.


#4

Great documentation :smiley:


#5

@UristMcSparks @bakmamba74


#6

Looks good.

There’s something irritating about the method signature using “Mb” when it returns megabytes and not megabits, but it makes sense due to naming conventions at the same time.


#7

Seems very good for optimization.


#8

This looked like a good way to get memory usage stats on mobile since we don’t have F9, but I notice that on PC it seems to disagree with the F9 client memory report. Maybe it’s reporting server stats instead of client, I don’t know, but it’s not what I want.


#9

@CycloneUprising


#10

Also I’ll note that you can activate the dev console on mobile by chatting /console.


#11

Also located in escape menu


#12

Possible use case: More detailed crash reports.