Event Metrics benefit from a more thoughtful design process than Sampled Metrics because the best event metrics record raw data that can be analyzed to answer a range of questions instead of just recording a single metric to answer a single question like Sampled Metrics do.

Conceptually, an Event Metric should record a set of values that describe an event that occurred.  The exact Timestamp of the event and its sequence in the session are automatically captured by the Agent.  During analysis, the Loupe Desktop can provide a range of charts and graphs of this information, as well as a copy of the raw event data.  For some examples of event metric usage, see Developer's Guide - Metrics - Event Metrics.  In many ways, you could consider each event metric definition to be a database table that you describe at runtime, complete with typed columns and a unique key (the sequence number in the session). 

The basic approach to designing event metrics is:

1. Determine the primary value and secondary characteristics you want to store for each event:  These are the values that fundamentally characterize the event, such as the name of the stored procedure or query called or the web page requested or the operation performed.  Any numeric value that's recorded can be aggregated in a variety of ways (sum, average, etc.) and string values are generally grouped and counted.  Recording additional string values is generally very cheap.  For example, you may want to record database connection options or the name of the database, file being accessed, etc.  The Loupe Agent employs a compression methodology that is particularly good with repeating strings, so record any characteristics that may be of value during analysis.
2. Identify the easiest point of capture and recording in your application:  Look for a place in your code where the event has finished and the information is readily available to record.  Because Event Metrics emphasize recording the data about each event it isn't necessary to have common data elements shared between threads.  This makes Event Metrics particularly useful in multithreaded and stateless applications, such as those in ASP.NET or that run in the .NET ThreadPool.
3. Determine Event Metric recording approach:  For any single metric you can either record it programmatically or declaratively.  Programmatic event metrics work by having your code specifically define the event metric and each sample.  It requires more lines of code to implement, but offers more opportunity for optimization and doesn't require creating any new objects.  The declarative approach requires adding attributes to a new or existing object which is used to define and record the event metrics.  This approach tends to be cleaner to use and easier to integrate but requires creating a new object or interface for each metric.
4. Create your initial implementation and verify:  Once you've integrated your initial metric implementation, be sure to review and experiment with the metric results in the Loupe Desktop both graphing and charting values.  This will help you understand what you might be able to adjust for the best results. 

Check out the Developer's Guide - Metrics - Database Query Event Metric Example for a complete walkthrough that uses this approach to define a metric.

Summary Functions for Event Metrics

Each Event Metric Value needs to specify a default summary function.  This function is used to summarize together the values within a sampling interval, similar to the Sampling Type used with Sampled Metrics.  This allows any event metric value to be treated as if it were a sampled metric and graphed accordingly.  When charting, the summary function can be overridden as required, so it isn't necessary to record the same value multiple times if all that's changing is the summary function.

The summary functions available are:

• Count:  This is the default and is the only valid option for non-numeric values.  When selected, the number of non-null values will be used as the summary value.
• Average:  The arithmetic mean of the non-null values within each sample range. 
• Sum:  The sum of all of the non-null values within each sample range.
• RunningAverage:  The arithmetic mean of all of the non-null values in the session file from the start to the end of each sample range.
• RunningSum:  The sum of all of the non-null values in the session file from the start to the end of each sample range.

Tips and Tricks for Event Metrics

Use Summary Function to translate what you Have to what you Need

Often you can use the right summary function to get the value you want to ultimately see in the Loupe Desktop from a value that's readily available at runtime. 

• The Running Sum function adds all the values through the session:  Because it's doing a simple add, if you record positive and negative values in your metric samples you get a running total without having to track on your own.  For example, if you want to know the total number of users in the application you could record +1 every time someone logs in and -1 whenever they log out.  This can be done similarly to track the performance of a Queue. 
• The Average function can track hit ratio:  By recording 1 for a hit and 0 for a miss, since there is an event recorded for every hit or miss the average is the cumulative hit ratio.  If you use Running Average then it's the hit ratio since the start of the session, the regular Average would give you the hit ratio for the period of time that is being graphed.
• Everything can be Counted:  Each event metric sample increments the count of events for each value recorded on it.  Using the Loupe Desktop you can view the count of the number of events in any period, or count the number of occurrences of each unique string value. 

Pick Consistent Unit Captions

The charts and graphs determine if two values can share the same axis (and be scaled together) based on whether they have the same unit caption.  If you use different unit captions (ignoring case) for the same type of data (for example "ms" and "milliseconds" for millisecond time) they will not be graphed on the same axis even though they should be.  The unit caption should reflect the effective unit after the summary function is applied, not the raw value that is provided.

Performance

Writing an Event Metric to the Session File takes about the same amount of time as writing a log message and is largely independent of how many values included in the event metric.  Metric values tend to have good compression ratios as well.  Event metrics have significantly less overhead than writing to a database (locally or remote) and do most of their work asynchronously on a background thread, ensuring that they won't affect the throughput, parallelism, or responsiveness of your application.