Loupe - Log - Monitor - Resolve
Gibraltar.Agent.Metrics Namespace / EventMetric Class
Members Example

In This Topic
    EventMetric Class
    In This Topic
    A single event metric instance object, representing one instance of an event metric definition.
    Object Model
    EventMetric ClassEventMetricDefinition Class
    Syntax
    'Declaration
     
    
    Public NotInheritable Class EventMetric 
    public sealed class EventMetric 
    Remarks

    An EventMetric instance can only be created for a specific EventMetricDefinition which has been previously registered.

    To protect against duplicates with the same instance name, EventMetric does not have public constructors. Instead, use the static EventMetric.Register method with appropriate arguments to identify the specific event metric definition under which to create an event metric instance with a designated instance name.

    Once created, you can record samples for an event metric by:

    1. Calling CreateSample to start a new metric sample.
    2. Populating the data by calling SetValue for each value column you wish to record.
    3. Call Write on the sample to have it be locked and written to the session file.

    Alternatively, for event metrics defined via attributes (see EventMetricAttribute and EventMetricValueAttibute), the event metric can be sampled directly from a user data object of the corresponding type which contained the attributes by simply calling WriteSample from the event metric definition or from the specific event metric instance. In this case all data is read and then written to the session file automatically.

    For more information on how to take advantage of Event Metrics, see Developer's Reference - Metrics - Designing Event Metrics.

    Sampled Metrics

    An alternative to Event Metrics are Sampled Metrics. Sampled Metrics are designed to record a single, summarized value on a periodic basis. For more information on the difference between Sampled and Event Metrics, see Developer's Reference - Metrics - Sampled and Event Metrics. For more information on Sampled Metrics, see SampledMetric Class.

    Viewing Metrics

    Metrics are visible in the Session Viewer of the Gibraltar Analyst. Metrics are not displayed in the Loupe Live Viewer.

    Example
    The following example creates an event metric entirely through code and then writes a sample.
    public static void RecordCacheMetric(int pagesLoaded)
    {
        EventMetricDefinition cacheMetric;
     
        //so we can be called multiple times we want to see if the definition already exists.
        if (EventMetricDefinition.TryGetValue("LoupeSample", "Database.Engine", "Cache", out cacheMetric) == false)
        {
            cacheMetric = new EventMetricDefinition("LoupeSample", "Database.Engine", "Cache");
     
            //add the values (that are part of the definition)
            cacheMetric.AddValue("pages", typeof(int), SummaryFunction.Average, "Pages", "Pages in Cache", "Total number of pages in cache");
            cacheMetric.AddValue("size", typeof(int), SummaryFunction.Average, "Bytes", "Cache Size", "Total number of bytes used by pages in cache");
     
            //and now that we're done, we need to register this definition.  This locks the definition
            //and makes it go live.  This is passed by ref because if another thread registered the same metric, we'll get the
            //true registered object (whoever won the race), not necessarily the one we've just created to pass in.
            EventMetricDefinition.Register(ref cacheMetric);
        }
     
        //Now we can get the specific metric we want to record samples under (this is an instance of the definition)
        EventMetric cacheEventMetric = EventMetric.Register(cacheMetric, null);
     
        //now go ahead and write that sample.
        EventMetricSample newSample = cacheEventMetric.CreateSample();
        newSample.SetValue("pages", pagesLoaded);
        newSample.SetValue("size", pagesLoaded * 8196);
        newSample.Write();
    }
    The same results can be achieved with a more declarative approach by defining a metric data object decorated with attributes to indicate what properties to store as part of the event metric. You can decorate an existing object if that's convenient. The values of the decorated properties are read during the call to Write so the same object can be repeatedly sampled safely.
    /// <summary>
    /// Record an event metric using an object
    /// </summary>
    /// <param name="pagesLoaded"></param>
    public static void RecordCacheMetricByObject(int pagesLoaded)
    {
        CacheEventMetric sample = new CacheEventMetric(pagesLoaded);
        EventMetric.Write(sample);
    }
     
    //The above code relies on the following class being defined.
     
    /// <summary>
    /// Log event metrics using a single object
    /// </summary>
    [EventMetric("LoupeSample", "Database.Engine", "Cache - Declarative", Caption = "Simple Cache", Description = "Performance metrics for the database engine")]
    public class CacheEventMetric
    {
        public CacheEventMetric(int pagesLoaded)
        {
            Pages = pagesLoaded;
            Size = pagesLoaded * 8192;
        }
     
        [EventMetricValue("pages", SummaryFunction.Average, "Pages", Caption = "Pages in Cache", Description = "Total number of pages in cache")]
        public int Pages { get; private set; }
     
        [EventMetricValue("size", SummaryFunction.Average, "Bytes", Caption = "Cache Size", Description = "Total number of bytes used by pages in cache")]
        public int Size { get; private set; }
    }
    Inheritance Hierarchy

    System.Object
       Gibraltar.Agent.Metrics.EventMetric

    Requirements

    Target Platforms: Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

    See Also