Oso Corporation | 2.5 - Event attributes

Attributes are a way for applications to add custom data to profile events.

Before an application can start adding attribute data to events, the attribute types must first be registered in the profile itself. This is done through calling OsoMP_NewAttribute. It is recommended you do this in your implementation of OsoMP_InitialiseCallback.

Attribute types consist of the following pieces of information:

ID	Application defined unique identifier. Attribute IDs are 8-bit values and must be greater than or equal to ATTRIBUTEID_FirstUser (defined as 20 in the Oso Memory Profiler SDK) and less than or equal to ATTRIBUTEID_Last (255).
Type	An attribute type defines the data format of an attribute. Attribute data can be one of the following types: ATTRIBUTETYPE_Integer32 - A 32-bit signed integer. ATTRIBUTETYPE_Integer64 - A 64-bit signed integer. ATTRIBUTETYPE_Float - A 32-bit float number. ATTRIBUTETYPE_String - UTF8 encoded text. ATTRIBUTETYPE_Filename - UTF8 encoded path. Paths can be absolute or relative. ATTRIBUTETYPE_URL - UTF8 encoded URL. ATTRIBUTETYPE_Time - Signed 64-bit Unix timestamp. ATTRIBUTETYPE_Duration - Signed 64-bit integer denoting microseconds. ATTRIBUTETYPE_Frequency - 32-bit unsigned integer denoting Hz.
Name	A friendly name to help identify attributes within the Oso Memory Profiler. An attribute's name is also the basis for its simple name when attributes are referenced in block type format strings or expressions. An attribute's simple name is the lowercase form of its name with all punctuation and spacing removed. For example, the simple name of "Frame Number" is "framenumber".

Once attribute types have been registered, an application can pass an array of OsoMPAttribute structures containing attribute values to any of the profile event functions in the Oso Memory Profiler SDK:

The OsoMPAttribute structure is defined as follows:

typedef struct OsoMPAttribute
{
    UInt8              mID;        // Application defined unique identifier.
    OsoMPAttributeType mType;

    union mData
    {
        SInt32         mInt32;     // ATTRIBUTETYPE_Integer32, or ATTRIBUTETYPE_Frequency.
        float          mFloat;     // ATTRIBUTETYPE_Float.
        const char*    mText;      // ATTRIBUTETYPE_String, ATTRIBUTETYPE_Filename, or ATTRIBUTETYPE_URL.
        SInt64         mInt64;     // ATTRIBUTETYPE_Integer64, ATTRIBUTETYPE_Time, or ATTRIBUTETYPE_Duration.
    }
    mData;
}
OsoMPAttribute;

Attribute values are always optional. It is perfectly valid to omit some values from some events if it doesn't make sense to include them.

Any attributes that have been added to an event will be listed in the [PAGE=infoattributes'>attributes information pane[/PAGE] for an event.

While custom attributes are a great way to provide additional context to help you understand what your application was doing at any given time, they can also be used to help validate your application's behaviour. More information regarding this can be found on the page explaining expressions.

Attributes can also be used to control grouping of blocks in the Blocks overview pane in the Oso Memory Profiler. See the page on Block Types for more information about this.