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

Visual Basic
C#

'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

Reference

GFeature Members
Gibraltar.Agent.PostSharp Namespace

Send Feedback