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

In This Topic
    GField Class
    In This Topic
    A PostSharp aspect used to monitor the state of a field (member variable), recording a log message and metric when it changes.

    Enables the logging of method entry and exit at runtime complete with parameter information and results.

    Syntax
    'Declaration
     
    <DebuggerNonUserCodeAttribute()>
    <PostSharp.Extensibility.MulticastAttributeUsageAttribute(ValidOn=MulticastTargets.Field, 
       TargetMemberAttributes=MulticastAttributes.NonLiteral, 
       TargetParameterAttributes=MulticastAttributes.NonLiteral)>
    <PostSharp.Extensibility.HasInheritedAttributeAttribute()>
    <SerializableAttribute()>
    Public Class GField 
       Inherits PostSharp.Aspects.LocationInterceptionAspect
       Implements Gibraltar.Agent.IMessageSourceProvider, PostSharp.Aspects.IAspect, PostSharp.Aspects.IAspectBuildSemantics, PostSharp.Aspects.ILocationInterceptionAspect, PostSharp.Aspects.ILocationLevelAspect, PostSharp.Aspects.ILocationLevelAspectBuildSemantics, PostSharp.Extensibility.IValidableAnnotation 
    [DebuggerNonUserCode()]
    [PostSharp.Extensibility.MulticastAttributeUsage(ValidOn=MulticastTargets.Field, 
       TargetMemberAttributes=MulticastAttributes.NonLiteral, 
       TargetParameterAttributes=MulticastAttributes.NonLiteral)]
    [PostSharp.Extensibility.HasInheritedAttribute()]
    [Serializable()]
    public class GField : PostSharp.Aspects.LocationInterceptionAspect, Gibraltar.Agent.IMessageSourceProvider, PostSharp.Aspects.IAspect, PostSharp.Aspects.IAspectBuildSemantics, PostSharp.Aspects.ILocationInterceptionAspect, PostSharp.Aspects.ILocationLevelAspect, PostSharp.Aspects.ILocationLevelAspectBuildSemantics, PostSharp.Extensibility.IValidableAnnotation  
    Remarks

    GField is a PostSharp aspect used to monitor changes to fields within classes. It writes a message to the whenever an associated member variable is changed. Additionally:

    • The previous value is recorded in the log message
    • The source code location that caused the change is recorded with the log message if source code location information is available.
    • A sampled metric is recorded for numeric or boolean fields to enable graphing and quantitative analysis in the Gibraltar Analyst.

    Categorization

    Each log message is recorded in an automatically generated category in the form {BaseCategory}.Trace Exit. See the BaseCategory property for more information on changing the log message category.

    Each metric is automatically recorded in a category in the form {BaseCategory}.Field Monitoring.{Category}. See the BaseCategory property for more information on changing the category root and the Category property for more information on how the full category name is determined.

    Enabling and Disabling at Runtime

    Because GField messages are voluminous and detailed it's often useful to enable and disable them at runtime. To do this just set the Enabled property which will affect all methods instrumented with GField in the current process. When disabled GField has minimal performance impact even in high volume scenarios.

    Differentiating Between Instances

    Since the GField attribute is applied to a field it will be tracked for all instances of the related class. With the exception of static classes this may be a potentially unbounded set of different objects. By default, every object has a unique runtime identifier which is recorded with the metric value to enable correlation during analysis but this value is not predictable or consistent. Instead, if an object has a property that represents a more useful, unique name for the object then that can be specified in the InstanceNamer property. Doing so will produce more useful log messages and graphs.

    Refining Data Captured

    You can turn down the amount of information captured for a given method by GField in log messages by setting the EnableSourceLookup property to false. This will reduce the performance overhead of GField at the expense of losing the information on what class & method caused the value to change.

    You can supply a Unit caption for fields that represent values in a common unit you want to enable comparative graphing of. For example, you might specify "ms" for times in milliseconds or "%" for percentages. This improves the overall experience graphing the values in Analyst.

    Advanced Usage

    You can supply your own methods for formatting individual values, captions, and descriptions by creating a new object that derives from GField and overriding the appropriate methods:

    • FormatValue: Overrides how objects are translated to strings for insertion into messages.
    • FormatCaption: Overrides how log message captions are generated.
    • FormatDescription: Overrides how log message descriptions are generated.
    Example
    You can associate the GField attribute with a single field or an entire class to trace all methods in that class. You can also use attribute multicasting to apply it to all matching fields or classes in your assembly (not generally recommended)
    Track changes for one field within a class
    public class SampleApplication
    {
        [GField]
        private int m_TrackedField;
        private void InterestingMethod(int valueOne, String anotherValue)
        {
            //Do something interesting here
            m_TrackedField = valueOne;
        }
    }
    Inheritance Hierarchy

    System.Object
       System.Attribute
          PostSharp.Extensibility.MulticastAttribute
             PostSharp.Aspects.Aspect
                PostSharp.Aspects.LocationLevelAspect
                   PostSharp.Aspects.LocationInterceptionAspect
                      Gibraltar.Agent.PostSharp.GField

    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