Loupe - Log - Monitor - Resolve
Gibraltar.Agent.PostSharp Namespace / GFeature Class
Members Example

In This Topic
    GFeature Class
    In This Topic
    A PostSharp aspect used to record how often a particular method in your application is used, how long it takes to run, and whether it was ultimately successful or not. It record both log messages and metrics to enable powerful analysis.
    Syntax
    'Declaration
     
    
    <DebuggerNonUserCodeAttribute()>
    <PostSharp.Extensibility.MulticastAttributeUsageAttribute(MulticastTargets.Constructor Or  _
        MulticastTargets.InstanceConstructor Or  _
        MulticastTargets.Method Or  _
        MulticastTargets.StaticConstructor, 
       AllowMultiple=True, 
       TargetMemberAttributes=MulticastAttributes.NonAbstract)>
    <PostSharp.Serialization.SerializerAttribute()>
    <PostSharp.Aspects.Configuration.AspectConfigurationAttributeTypeAttribute(PostSharp.Aspects.Configuration.OnMethodBoundaryAspectConfigurationAttribute)>
    <AttributeUsageAttribute(AttributeTargets.Assembly Or  _
        AttributeTargets.Class Or  _
        AttributeTargets.Constructor Or  _
        AttributeTargets.Event Or  _
        AttributeTargets.Interface Or  _
        AttributeTargets.Method Or  _
        AttributeTargets.Property Or  _
        AttributeTargets.Struct, 
       AllowMultiple=True, 
       Inherited=False)>
    <PostSharp.Extensibility.HasInheritedAttributeAttribute()>
    <XmlTypeAttribute("http://schemas.postsharp.net/2.0/aspects")>
    <SerializableAttribute()>
    Public NotInheritable Class GFeature 
       Inherits GAspectBase
       Implements Gibraltar.Agent.IMessageSourceProvider, PostSharp.Aspects.IAspect, PostSharp.Aspects.IAspectBuildSemantics, PostSharp.Aspects.IMethodLevelAspect, PostSharp.Aspects.IMethodLevelAspectBuildSemantics, PostSharp.Aspects.IOnMethodBoundaryAspect, PostSharp.Extensibility.IValidableAnnotation 
    [DebuggerNonUserCode()]
    [PostSharp.Extensibility.MulticastAttributeUsage(MulticastTargets.Constructor | 
        MulticastTargets.InstanceConstructor | 
        MulticastTargets.Method | 
        MulticastTargets.StaticConstructor, 
       AllowMultiple=true, 
       TargetMemberAttributes=MulticastAttributes.NonAbstract)]
    [PostSharp.Serialization.Serializer()]
    [PostSharp.Aspects.Configuration.AspectConfigurationAttributeType(PostSharp.Aspects.Configuration.OnMethodBoundaryAspectConfigurationAttribute)]
    [AttributeUsage(AttributeTargets.Assembly | 
        AttributeTargets.Class | 
        AttributeTargets.Constructor | 
        AttributeTargets.Event | 
        AttributeTargets.Interface | 
        AttributeTargets.Method | 
        AttributeTargets.Property | 
        AttributeTargets.Struct, 
       AllowMultiple=true, 
       Inherited=false)]
    [PostSharp.Extensibility.HasInheritedAttribute()]
    [XmlType("http://schemas.postsharp.net/2.0/aspects")]
    [Serializable()]
    public sealed class GFeature : GAspectBase, Gibraltar.Agent.IMessageSourceProvider, PostSharp.Aspects.IAspect, PostSharp.Aspects.IAspectBuildSemantics, PostSharp.Aspects.IMethodLevelAspect, PostSharp.Aspects.IMethodLevelAspectBuildSemantics, PostSharp.Aspects.IOnMethodBoundaryAspect, PostSharp.Extensibility.IValidableAnnotation  
    Remarks

    GFeature is a PostSharp aspect used to record detailed information about how a particular feature in your application is used. By associating the GFeature attribute with a method it will automatically record:

    • A log message on method invocation with the input parameters and the feature caption.
    • If the method is exiting because an exception is being thrown out of the method that is noted and the exception details are recorded on an error log message.
    • The log messages are attributed to the source code location that invoked the method, if source code location information is available.
    • An event metric sample is recorded with information on how long the method ran, what each of its input parameters were, whether it ended with an exception, and its categorization. Using Loupe Desktop you can dissect this information to understand what features are used most often (or least often), how they're used, and how well they perform.

    Log Message Categorization

    Each log message is recorded in an automatically generated category in the form {BaseCategory}.{Caption}. See the BaseCategory property for more information on changing the log message category. The Caption will be Feature Usage by default unless you set an alternate value using the Caption Property.

    Log Message Severity

    By default GFeature will log messages as Informational unless the method is exiting due to an exception. In these cases an Error will be recorded. These defaults were optimized for the high level Feature use case, however if you are using GFeature at multiple levels in your application (like to record each Data Access Layer call) you may want to turn these severities down. You can adjust them using the MessageSeverity Property and ExceptionMessageSeverity Property.

    Metric Categorization

    Each event metric is recorded in an automatically generated category in the form {BaseCategory}.{Caption}.{Category}. See the BaseCategory property for more information on how the BaseCategory can be set. You can set the Caption Property or leave it alone to use the default of Feature. You can set the Category Property to change the subcategory used or leave it alone to use the default of the class name.

    Enabling and Disabling at Runtime

    You can globally enable and disable GFeature at runtime. To do this just set the Enabled property which will affect all methods instrumented with GFeature in the current process. When disabled GFeature has minimal performance impact even in high volume scenarios.

    Refining Data Captured

    You can manually set the category used to record this specific feature within all of the features with the Category property. By default each feature is recorded in a generated category composed of the BaseCategory Property (Gibraltar.Agent.PostSharp.GAspectBase) along with "Feature Usage" and the fully qualified class name. By setting the Category property you can put a specific feature into a subcategory underneath "Feature Usage".

    This aspect is also useful for recording each time your application moves between tiers, such as for web service calls or calls to an external database. In those cases you'll probably want to change "Feature Usage" to something else, like "Web Server" or "Database". You can do this using the Caption property.

    You can override the default name for each feature by setting the Name property. Within a given category features that share the same name will be analyzed together in the Gibraltar Analyst. Therefore, they must have the same method signatures or the metric may not be recorded successfully. Alternately, you can disable parameter recording in these cases by setting the LogParameters Property to false. By default the Name is set to the name of the method being timed.

    Example
    You can associate the GFeature attribute with a single method, a property, or an entire class to time all methods in that class. You can also use attribute multicasting to apply it to all matching methods in your assembly.
    Monitoring one method within a class
    public class SampleApplication
    {
        [GFeature]
        private void InterestingMethod(int valueOne, String anotherValue)
        {
            //Do something interesting here
        }
    }
    Monitoring all methods within a class
    [GFeature]
    public class SampleApplication
    {
        private void InterestingMethod(int valueOne, String anotherValue)
        {
            //Do something interesting here
        }
     
        private void AnotherInterestingMethod(int valueTwo, String anotherValue)
        {
            //Do something even more interesting here
        }
    }
    Inheritance Hierarchy

    System.Object
       System.Attribute
          PostSharp.Extensibility.MulticastAttribute
             PostSharp.Aspects.Aspect
                PostSharp.Aspects.MethodLevelAspect
                   PostSharp.Aspects.OnMethodBoundaryAspect
                      Gibraltar.Agent.PostSharp.GAspectBase
                         Gibraltar.Agent.PostSharp.GFeature

    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