Often when you are tracking a count or a value, you want to record that value in multiple stats. For example, if you would like to track HTTP request times on all your webservers it would be nice to know the average request time for all webservers, the request time for a particular server, and the request time for an intensive service. You could send StatHat three stats:

ezkey=ZZZZ&stat=request time - overall&value=23.098
ezkey=ZZZZ&stat=request time - ws03&value=23.098
ezkey=ZZZZ&stat=request time - match&value=23.098

This is fine, but if you want to cut down on your HTTP traffic, you can do this all with one call:

ezkey=ZZZZ&stat=request+time~overall,ws03,match&value=23.098

This call above will send the value of 23.098 to “request time overall”, “request time ws03”, and “request time match”.

The ~ character is special in stat names. StatHat splits a stat name at the ~ character, then uses that as a prefix to build a list of stats that should receive the value. The format is:

[prefix]~[name1],...,[nameX]

There are many places where this is useful: segment your sign ups by continent, track messages sent by gender and orientation, collect error counts overall and by the host and service where the error occurred.

For more information, see the API docs.