Monday, June 3, 2013

Telemetry 2 Migration Notes #2: Pseudo Paths

Telemetry 1.x had an object identification system based on pseudo-paths, however as new features were added the pathing became inconsistent.  For example, plots and memory allocations used plots like this:

tmPlot( cx, TMPT_NONE, 0, value, "enemies/active" );
tmAlloc( cx, r, size_r, "meshes/players/current" );

Whereas zones and messages used parentheses to delimit the paths from the leaves:

tmZone( cx, TMZF_NONE, "(game/render)draw mesh" );
tmMessage( cx, TMMF_SEVERITY_LOG, "(game/net) client connected!\n" );

With Telemetry 2 everything uses the parenthetical form, so the above would look like this:

tmPlot( cx, TMPT_NONE, 0, value, "(enemies)active" );
tmAlloc( cx, r, size_r, "(meshes/players)current" );
tmZone( cx, TMZF_NONE, "(game/render/draw mesh)" ); // will explain this in a moment
tmMessage( cx, TMMF_SEVERITY_LOG, "(game/net)client connected!\n" );

The part within parentheses is considered the path, and the part outside is the leaf.  Paths are not required, however.

The one potential problem area are zones, mostly due to a change in how we handle zone time collation for profiling.  With Telemetry 1 we would use a kind of hazy heuristic about what zones were combined into a single time category.  It worked for the most part but was a little opaque and customers often didn't understand how or why it worked the way it did.

With Telemetry 2 the aggregation of zones for profiling purposes is now explicitly managed by you.  If there is an explicit path, then everything in that path will be combined.  So for example if there are different zones specified like this:

tmZone( .., "(render/mesh) %s", mesh_name );

Then they will all be combined and displayed as "(render/mesh)" in the profile view.

If for some reason you didn't want different meshes combined together and instead wanted them shown individually, you would do:

tmZone( ..., "render mesh %s", mesh_name );

And now the profile view would show a separate row for each individual mesh_name that was rendered.