Links : Part 1, Part 3, Part 4
Working with Windows Instrumentation Manifest file
In this article, we will see how to create an instrumentation manifest file from scratch by defining a custom provider metadata and its supported events metadata in an xml file. We will use predefined xml elements and attributes for doing this.
Let’s create a blank xml file and add required elements one by one.
Add Element to Identify Provider: You can put more than one Provider information in single instrumentation manifest. To identify a particular provider, we use <Provider/> element and specify the values for following attributes.
Name: Name of your provider.
Guid: GUID to uniquely identity this provider in the system.
resourceFileName: Path of assembly in which the resource file generated after the compilation of
manifest file is embedded. We will see how the compile the manifest file.
messageFileName: Path of assembly in which the message file generated after the compilation of manifest file is embedded. We will see how the compile the manifest file.
Symbol: Used to refer the class of this provider in the code generated by MC.exe (manifest compiler).
Message: The localized display name for the provider. The message string references a localized string in the stringTable section of the manifest.
Sample xml snippet:
Add Element to define channels: Channels are used by Consumer applications like Windows Event Viewer to collect events for certain group of audiences. You use <channel />Element to define new channels. Values for the following attributes must be provided in each <channel/> element.
Chid: An id to uniquely identify the channel in the list of channels defined under a provider. This same attribute is used to attach the channel with specific event type defined using <Instrumentation\Events\Provider\Event/> element.
Name: Name of channel, must be unique among all the channels defined in same provider element.
Type: This value can be set to one the four types: Admin, Analytic, Debug and Operational. Component should write events under correct channel types, as each channel type is used by different set of audiences to analyses the application issues.
Enabled: To specify if the channel is enabled or not.
Isolation: Isolation level defines access permissions for the channel. There are three isolations are available: Application, System and Custom.
Message: The localized display name for the channel. The message string references a localized string in the stringTable section of the manifest.
Sample xml snippet:
Add Element to define Severity levels: Severity levels are used to group the published events. These are also used by consumer applications to query the events and trace session uses them to limit the events which are provided to consumer applications in real time or written in log files. You use <level />Element to define new levels. Values for following attributes must be provided in each new level element.
Name: Name of the Level. Must be unique among all the levels defined under same provider.
Value: Level value. It can be between 16 to 225.
Symbol: Used to refer the constant created for this Level in the code generated by MC.exe (manifest compiler).
Message: The localized display name for the channel. The message string references a localized string in the stringTable section of the manifest.
Sample xml snippet:
Add Element to define task and opcodes: Tasks and opcodes (operation codes) are used to logically group the published events. You define new tasks for each component of your application and a new opcode for each type of operation performed in that component. Because of this grouping consumer applications can easily query for events published for particular operations performed in particular component. You use <task />Element to define a new tasks and use <opcode /> element to define task specific operation codes. Values for the following attributes must be provided in each new <Task/> element.
Name: Name of the Task. Must be unique among all the levels defined under same provider.
Symbol: Used to refer the constant created for this Task in the code generated by MC.exe (manifest compiler).
Value: Value assigned to the Task. It can be between 1 to 239.
Message: The localized display name for the channel. The message string references a localized string in the stringTable section of the manifest.
Sample xml snippet:
Add Element to define Keywords: Keywords are used to classify different types of events. You might create one keyword to classify all your database accesses in your application and another one to classify write accesses to the database. You associate keywords with events when you define new events using <event> element. Keywords are used by consumer applications to limit the number of events it listens for. You use <keyword /> element to define a new keywords. Values for the following attributes must be provided in each new <keyword /> element.
Name: Name of the Keyword. Must be unique among all the Keywords defined under same provider.
Mask: Bit value assigned to the Keyword. This value is checked by Trace Sessions to limit category of events they want to listen for. You can specify bit values in the range from 0x0000000000000001 through 0x0000800000000000 (bits 0 through 47).
Symbol: Used to refer the constant created for this Keyword in the code generated by MC.exe (manifest compiler).
Message: The localized display name for the channel. The message string references a localized string in the stringTable section of the manifest.
Sample xml snippet:
Add Element to define event data Template: Each published event carry some data with it. This data has specific meaning in the context of published event. You use <template /> element to define a new data template. Values for the following attributes must be provided in each new <template /> element and use <data /> element to define template specific data items.
Attributes of Template element
Tid: unique identifier of the template defined in the provider.
Attributes of Data element.
Name: Name assigned to the data item.
Type: Data type for the data item.
Sample xml snippet:
Add element to define Events: Each provider defines all the events it can publishes in manifest file. You use <event/> element to define each new event. Attributes you set in <event/> element are based on who is going to consume your published events. Following are attributes you set in <event/> element.
Value: The event identifier. The identifier must be unique within the list of events that you define for your provider.
Level: Level of verbosity. This value either comes for the Levels you have defined or from the level predefined in winmeta.xml. If your event is targeting Admin channel, you cannot use your custom level value. Only possible values for Admin channel events are win:Critical, win:Error,win:Warning and win:Information.
Symbol: Used to refer the event descriptor created for the event in the code generated by MC.exe (manifest compiler).
Message: The localized display name for the channel. The message string references a localized string in the stringTable section of the manifest. To add event specific data items in message use substitution parameters. For Example to use third data item in you message use %3.
Template: An identifier of the template that defines all the data items an event can carry along with it. Specify the identifier of a template that you defined in the manifest.
Task: The name of a task that identifies the component or subcomponent that generates this event. Specify the name of a task that you defined in the manifest.
Opcode: The name of an opcode that identifies an operation within the task. Specify the name of an opcode that you defined in the manifest or one of the opcodes defined in Winmeta.xml.
Channel: If your users are going to Windows Event Viewer to view your published events, this attribute should be set with one of the channel you have defined manifest.
Sample xml snippet:
Download complete manifest file from sample code.
At this stage, we have successfully completed an instrumentation manifest file. Next step is to register all the information defined in manifest file with Operating system. Once registered, operating system can fetch this information at the time you create new trace sessions or in inside Event Viewer to parse your message data elements and show them at proper places in the view.
Follow these steps to register the manifest with operating system.
1. Compile the manifest file and generate message file. Use following command in visual studio 2010 command prompt.
MC.exe -r <target location> <manifest file path>
MC.exe -r c:\ProviderFiles EventProviderManifest.xml
You will see the generated files in your target location. Something similar to the following
2. Generate native resource file from message file you just created in above step. Use following command in visual studio 2010 command prompt.
RC.exe <message file path>
RC.exe c:\ProviderFiles\EventProviderManifest.rc
You will see the generated native resource file in your target location. Something similar to the following.
3. Generate a .NET assembly and embed the native resource file you have just created in above step. Use the following command in visual studio 2010 command prompt.
csc.exe /out:<target assembly path> /win32Res:<resource file path> /t:library <some .cs file path>
csc.exe /out:c:\ProviderFiles\EventProviderManifest.dll /win32Res:c:\ProviderFiles\EventProviderManifest.res /t:library c:\ProviderFiles\temp.cs
You will see the generated assembly in your target location. Something similar to the following.
4. Next step is to update the instrumentation manifest file by updating the resourceFileName and messageFileName attributes of Provider element. Something similar to following.
5. Last step is to register manifest xml file with operating system by running the following command. Use visual studio 2010 command prompt to run this command.
Wevtutil im <instrumentation manifest file path>
Wevtutil im c:\ProviderFiles\EventProviderManifest.xml
If the above command runs successfully, you have registered the manifest with operating system successfully.
Till now we have seen how to work with instrumentation manifest and register it with the operating system. In part 3 of this series, I will show you how to create a provider assembly, which can be used in your applications to publish all the events you have defined in instrumentation manifest file.
No comments:
Post a Comment