Telemetry Power Tips #1: Managing Real-time Event Volume

One of the most common questions that comes up from Telemetry users is "What if I don't want all this data all the time?" or, put another way, "What if I only want to collect some types of data, some of the time?"

While you can use the tmPause API to turn off events, it's a heavyweight solution since it shuts down almost all data collection.  A finer grain solution that provides precise control of detail or specific coverage is often desired.

Simple Telemetry integrations have a single global HTELEMETRY context which is passed into Telemetry markup, and if NULL then the function is not called.  (Technically they're passed into Telemetry macros which dispatch after the check, saving a little performance in the NULL case).

We can leverage this property by keeping a set of HTELEMETRY variables that alternate between NULL and the real Telemetry context.

For example, let's say you have separate markup for your rendering, game logic, physics, and audio, and you want to enable/disable profiling for each of those categories independently.

HTELEMETRY telemetry_context;
enum { TCAT_AUDIO, TCAT_RENDERING, TCAT_PHYSICS, TCAT_GAME, NUM_TCATS };
HTELEMETRY telemetry_categories[ NUM_TCATS ];

Your markup can then use the appropriate category:

void playSound( char const *kpSoundName )
{
   tmZone( telemetry_categories[ TCAT_AUDIO ], TMZF_NONE, "playSound %s", kpSoundName );
   // ... play audio
}

In the above code, if telemetry_categories[ TCAT_AUDIO ] is NULL then the zone is never created and sent.

Now you just hook up some method to control the categories (console command, hot keys, controller input, etc.) which sets those array entries appropriately:

void enableTelemetryCategory( int which, bool enable )
{
   telemetry_categories[ which ] = enable ? telemetry_context : NULL;
}

You can obviously extend this to other things like markup 'levels', with the default being very light markup that has low overhead and going all the way up to a dense markup setting that generates tens of thousands of events per frame.

Just remember to avoid dangling (and invalid) references by clearing your arrays before you shut everything down!