Querying Properties in Custom Usage Events

This short post will demonstrate query syntax to display custom event properties in the App Insights Analytics page and display properties in multi-layered charts. I have demonstrated simple events and more complex ones with properties in past posts. If you implemented events with properties like in my last post then you probably noticed that those properties do not appear “out of the box” in the analytics reports.

This post:

  1. Provides a little background on why you might want to add properties, especially in the case of O365 sites or apps.
  2. Shows you how to use Custom Event properties in App Insights Analytics.

If you want to skip to the end, the key line in a query is this:

extend refine= tostring(customDimensions.refiner)

…where “refine” is a term that you invent to hold the propery values, and “refiner” is the label of the property that is in your custom event. Now you can work with the “refine” value just like any other in Analytics.

In my first example, I submitted the “clicked refiner” as the Event Name. Reporting was simple but this only provides me with one dimension of data- the thing that was clicked. This information is interesting and useful in the simplest cases, but I really need to know more about the context of the event to make the best decisions. For example, to add context to the Refiners example from previous posts I modified the custom event to be called Refinement and submitted the actual refiner value that was clicked as a property instead of as the Event name. Then I added some extra data to the event from User Profiles, also as properties, and did a little clicking. Now instead of gathering info about which refiners are popular, I also know which refiners are popular among users in specific Departments and with specific Titles.

The resulting table looks like this in Analytics:

…and yields a quick chart like this which tells me that the Refinements are in use, but not much else.

Important Note: The spaces in the property names which you can see above caused me headaches- keep things simple if you can and use labels without spaces.

Selecting “Chart” from the menu shows me that my informative properties are simply absent from the view since I have not told Analytics how to read them yet:

I started reading these pages on the query syntax some months back and I quickly went from being very impressed with the depth of query features in Application Insights to being slightly overwhelmed by the depth of the query features in Application Insights!

It was not so difficult though. After some reading, a little watching, a little trial and error, and a few conversations with more advanced users I quickly got to writing queries that allowed me to easily digest complicated event data laden with useful context from Office 365 User Profiles.

The starting query was very simple, show me custom events where the name of the event is Refinement.

As I hinted at the beginning, the only thing needed to query the custom event properties, is to tell Analytics that the property is something that can be queried, and to summarize the data on these values. The result is the much more readable table here:

Which is also two clicks (Chart->Doughnut), from looking like this:

Nice, but as I mentioned, a little context would be better. To get the other interesting data that mentioned in the first section, I just need to add more “extend” statements for the additional properties as shown here:

I clicked the “Split by” tab for a reason in this screen capture- you can see that I can now select the UserTitle as an additional dimension.

My chart gets very interesting when I select the UserTitle box. Especially because there is some trial-and-error data in my test tenant!

Only one of my test users actually had a Title in his User Profile at the time of this test, “Marketing Assistant”. While there is only one unique value here, the opportunity to add context to events is clear. Not only while developing a solution, but while developing a story, I can gather simple contextual usage data from an O365 solution and further target my story or solution to an audience like Marketing Assistants, Researchers in Sri Lanka, Developers in the Automotive Division in Sweden, etc.