Manifest
Generator Tool Reference

Quick Start Guide

Events

Performance Counters

Reference

Quick
Start Guide

The
following quick start guide illustrates the steps needed to create an event and
performance counter manifest. The scenarios illustrated in both cases are
simple, but demonstrate the procedure to create an event and counter provider.

Creating Events

Scenario: The function entry
and exit points of the application “sample.exe” need to be logged
to a trace file in order to analyze code paths. A single event provider will be
created that will log two trace events: one which indicates function entry and
the other which indicates function exit. The information that will be logged
with the events includes the function name and the total number of parameters.

Set
Event Provider Information

1)
Create
a new Event Provider by clicking the “Events
Section” on the left-pane and then clicking “New Provider” on
the right-pane. There will only be one provider which will be needed to log
these two types of events (function entry and exit).

2)
Enter
the provider Name “Function-Entry-Exit-Provider”.

3)
Enter
the provider Symbol
“FunctionTraceProvider”.

4)
Create
a provider GUID for the provider by pressing the “New” button.

5)
Enter
%systemroot%\System32\sample.exe in both the Resources and Messages box since
this trace provider will be running in “sample.exe” which will run
from the System32 folder,

6)
Click
“Save”.

Set
the Channel

1)
Create
a new Channel by clicking “Channels” on
the left-pane and then clicking “New Channel” on the right-pane.
Since the event provider we are creating only logs trace events that are of
concern only during debugging, then we can log these events to a Debug channel.

2)
Enter
the channel Name “Function-Entry-Exit-Provider-Debug” in the name
box.

3)
Enter
the channel Symbol “FunctionDebugChannel”.

4)
Select
the “Debug” channel Type from the dropdown since we are creating a
Debug channel to log debug events during development of
“sample.exe”.

5)
Leave
the “Enabled” checkbox un-checked since it is not recommended to keep
Analytic and Debug channels on by default and only turn them on when needed.

6)
Enter
the channel Description: “This is the Debug channel to which events that
indicate function entry and exit will be raised”.

7)
Click
“Save”.

Set
the Task

1)
Create
a new Task by clicking “Tasks” on the
left-pane and then clicking “New Task” on the right-pane. The event
provider is raising two events which indicate function entry and function exit. Since these events are related to the
activity of “function tracing”, we need to create a single task for
this activity.

2)
Enter
the task Name “FunctionTracing” in the
name box.

3)
Enter
the task Symbol “_task_function” in the
symbol box.

4)
Enter
the task Value “1”.

5)
Enter
the task Description “This task has events that describe elements of
tracing functions like entry and exit”.

6)
Click
“Save”.

Set
the Opcodes

1)
Create
a new Opcode by clicking
“Opcodes” on the left-pane and then
clicking “New Opcode” on the right-pane.
There are two actions that will raise events: entering the function and exiting
the function. Therefore, two opcodes are needed since
one will illustrate the function entry and the other function exit. The
pre-defined opcodes do not map cleanly to the actions
being conveyed and so new opcodes will need to be
created.

2)
Enter
the opcode Name “Entry”.

3)
Enter
the opcode Symbol “_opcode_entry_function”.

4)
Enter
the opcode Value “10”.

5)
Enter
the opcode Description “This opcode describes function entry points”.

6)
Click
“Save”.

7)
Repeat
steps 1-6 for the second opcode. For the opcode Name, specify
“Exit”, for the Symbol “_opcode_exit_function”,
the Value “11” and the opcode Description
“This opcode describes function exit
points”.

Set
the Keywords

1)
Create
a new Keyword by clicking “Keywords” on
the left-pane and then clicking “New Keyword” on the right-pane.
There may be cases when events are enabled where only the function entry or
only the function exit events are needed. Therefore, the provider needs to
define two keywords which can allow function entry and exit events to be
separately enabled.

2)
Enter
the keyword Name “Function_Tracing_Entry”

3)
Enter
the keyword Symbol “_keyword_function_entry”

4)
Keep
the slider at the default setting of keyword Value “0x0000000000000001”

5)
Enter
the keyword Description “This keyword enables events that trace function
entry”

6)
Click
“Save”.

7)
Repeat
steps 1-6 for the second keyword. For the keyword Name, specify “Function_Tracing_Exit”, for the Symbol “_keyword_function_exit”, move the slider to set the
keyword Value “0x0000000000000002” and enter the keyword
Description “This keyword enables events that trace function exit”.

Define
the Event Payload

1)
Create
a new Template by clicking “Templates”
on the left-pane and then clicking “New Template” on the
right-pane. In this simple example, the information that needs to be logged
with which function was entered and exited includes the name of the function
and the number of parameters that are passed into the function. The function
name can be logged as an ANSI string, and the number of parameters can be
logged as an unsigned integer.

2)
Enter
the template Symbol “_template_function_trace”

3)
Add
the field that corresponds to the function name: Set the Name box to be “FunctionName”.

4)
Set
the InType of the field “FunctionName”
as “win:AnsiString”
since we are logging this as an ANSI string.

5)
Set
the OutType of the field “FunctionName”
as “xs:string”
since it should display as a string.

6)
Since
only a single string will be logged, the count can remain
“Default”; also, since the string will be null-terminated, the
length can remain “Default” as well.

7)
Click
“Add”; this now adds the field “FunctionName”
to the payload template.

8)
Now
the field that represents the number of parameters needs to be added to the
template; edit the Name box to say “NumberOfParams”.

9)
Set
the InType of the field “NumberOfParams”
to “win:UInt32” since the variable that
represents the number of parameters is an unsigned integer.

10)  Set the OutType of the field “NumberOfParams”
to “xs:unsignedInt”
since this field should show as an unsigned integer.

11)  Since this is a
single value, leave the count as “Default”

12)  Click
“Add”; the “Current fields” box should show the FunctionName string field and the “NumberOfParams” unsigned integer field.

13)  Click
“Save”.

Define
the Events

1)
Create
a new Event by clicking “Events” on
the left-pane and then clicking “New Event” on the right-pane. The
event payload and the event metadata that have been defined in the previous
steps need to be combined to form the event. Two events need to be created: one
that will represent the function entry with payload function name and number of
parameters, and another that will signify function exit with the same payload.

2)
Enter
the event Symbol “FunctionEntry”.

3)
Set
the event ID to 1 and keep the version 0 since this is the first event we are
defining.

4)
Click
the checkbox which corresponds to the “Function_Tracing_Entry”
keyword since this event will be enabled when that keyword is set.

5)
Choose
the “Function-Entry-Exit-Provider-Debug” channel from the channel
dropdown in order to raise the event into the debug channel defined earlier.

6)
Specify
the level of the event as “win:Informational”
since the events being raised are informational events meant to convey state;
if a custom level had been defined, then that could be selected instead.

7)
Choose
the task “FunctionTracing” from the
dropdown since the event being defined corresponds to that task.

8)
Select
the opcode “Entry” since this event
corresponds to function entry.

9)
Pick
the template “_template_function_trace”
from the drop-down; this is they symbol of the template (function name as
string and the number of parameters as unsigned integer) defined in the
Templates section.

10)  Specify the event
description “This event is logged when a function is entered”.

11)  Click
“Save”; this creates the first event. Repeat steps 2-10 for the
second event which represents function exit. The event symbol should be “FuntionExit”, the event ID can be “2”
with version “0”, the keyword is “Function_Tracing_Exit”,
the channel is the same “Function-Entry-Exit-Provider-Debug”
channel, the level is also “win:Informational”,
the task is “FunctionTracing”, the opcode now becomes “Exit”, the template is
still the same since the payload does not change and the event description is
now “This event is logged when a function is exited”.

12)  Click
“Save” and now both events have been created that correspond to the
event provider. FileàSave As and place
the name of the manifest, and now the event manifest is complete.

Creating
Counters

Scenario: The total number
of bytes that are read and written to the computer hard-disk need to be
monitored. There will be two counters defined:  one to denote the number of bytes read
from the disk, the other to denote the number of bytes written to disk. The
disk driver DiskDriver.sys will be updating the
counter values, and the consumer (such as Performance Monitor) can aggregate,
or add, all the counter values of a certain type to find the total number of
bytes. For example, to see the total number of bytes read, the values of all
instances of that counter will be added to retrieve the aggregate amount of
bytes read from the disk.

NOTE:
Currently only user-mode applications can correctly expose performance
counters. This example uses a driver for illustrative purposes.

Creating
the Provider

1)
Create
a Counter Provider by selecting
“Performance Counters Section” on the left-pane and then clicking
“New Provider” on the right-pane. This will create the counter
provider which is the entity that the system will use to retrieve counter
information when a consumer determines which counter values need to be
obtained.

2)
Enter
the provider Name “DiskProvider”

3)
Click
the “New” button to generate a provider GUID; this will be used by
the system to transfer counter information back to the counter consumer.

4)
Enter
the Application Identity “DiskDriver.sys”;
this is the driver that is defining the counters and will be updating the
counter values.

5)
Leave
the “Custom Callback” checkbox unchecked; since there is no need to
perform special calculations before the counter data is sent back to the
consumer, there does not need to be a callback function.

6)
Keep
the “Resource Base” at its default value of “1” since
there is no need to merge multiple resources into a single resource file.

7)
Click
“Save”.

Creating
the Counterset

1)
Create
a new CounterSet by
clicking “New Counter Set” on the right-pane. The Counterset represents a logical grouping of counters: since
the counter which will maintain the bytes read and the counter which will
maintain the bytes written are related (namely they indicate disk activity),
they will belong to the same counterset.

2)
Enter
the CounterSet Name “Disk Counters”.

3)
Click
the “New” button to generate a new CounterSet
GUID; all countersets are uniquely identified by a
GUID.

4)
Enter
the URI “DiskDriver.DiskCounterset”; the
URI is a unique identifier that can be used to refer to a particular counterset.

5)
Write
the Description “This counterset contains two
counters: one which tells the number of bytes read from the disk and the other
the number of bytes written to the disk”.

6)
Select
the Instance type “globalAggregate” from
the drop-down. In order to obtain the total number of bytes read and written to
the disk by the driver, we need to add, or aggregate, the specific counter
values across all instances of the counterset, with
each instance corresponding to the driver being loaded into a particular
process. For example, to calculate the total number of bytes read at a
particular time, we need to find all the active instances of the “Bytes
Read” counter and add the values together to obtain an aggregate value.
However, from the consumer perspective, it should only be a single value that
is seen for disk metrics.

7)
Click
“Save”.

Creating
the Counters

1)
Create
a new Counter by clicking “New Counter” on
the right-pane. The counter represents the particular entity whose value is of importance
to a consumer. In this example, two counters will be defined. The first counter
that will be defined will represent the bytes read while the second counter
will represent the bytes written.

2)
Enter
the counter Name “Number of Bytes Read”.

3)
Press
the up-arrow key to select the counter ID “1”.

4)
Enter
the URI “DiskDriver.DiskCounterset.BytesRead

5)
Write
the Description “This counter represents the number of bytes read by this
instance of the counter”.

6)
Leave
the Detail Level at its default value of “Standard”.

7)
Leave
the Type at its default value of “Counter raw count” since the
value of the counter “Number of Bytes Read” does not depend on any
other counter. In other words, the value of the counter at any moment
represents the number of bytes read by that instance of the counter.

8)
Leave
the Default Scale at its current setting of “0” since we
don’t have a need to scale the counter value when displaying it.

9)
Select
the Aggregate as “Sum” from the drop-down, since we want to add all
the instance of the “Number of Bytes Read” counter to find the
total number of bytes read by all loaded instances of the driver at any single
time.

10)  Click
“Save”.

11)  Repeat the steps 2
through 10 for the second counter: the name is “Number of Bytes
Written”, the Counter ID is “2”, the URI is “DiskDriver.DiskCounterset.BytesWritten”, the
Description is “This counter represents the number of bytes written by
this instance of the counter”, the Detail Level is
“Standard”, the Type is “Counter raw count”, the
Default Scale is “0” and the Aggregate is “Sum”.

12)  Click
“Save”. The creation of the counter manifest is now complete.

Reference

The
reference section is divided into two parts: the first part is a reference
section for the events portion of the tool, while the second part is a
reference section for the counters part of the tool. The reference section
contains the definition of the various parameters that can be attributed to
both events and counters; required fields are specified in bold. The Manifest Generator tool only supports running on Windows
Vista.

Events
Reference

Provider

Channels

Task

Opcode

Level

Keywords

Maps

Templates

Events

Performance
Counters Reference

Provider

Counterset

Counter

Event Reference Background

The
design steps to instrument code to raise events are as follows: the events are defined
in the XML-format manifest file. Once complete, the message compiler is then
run against the manifest to generate a resource file and a header file. The
header file is included with the sources that call the event logging API; the
resource is compiled with the executable.

The
manifest needs to be registered with the system. All events that are raised to
a global channel will be automatically enabled when the provider registers with
the system (using the registration function). By default, all the other events
are not enabled and must be explicitly enabled by a controller. The controller
can enable events raised by the provider either using channels or using the
level/keywords combination.

The
events themselves are divided into two sections: the first corresponds to
standard event header information that is shared by all events, while the
second section is an optional variable payload portion that can vary between
events. The standard header information includes event ID, version, channel,
task, opcode, level and keywords. The variable
payload section is described by the event template.

NOTE:
For the Manifest Generator Tool to function correctly, the file winmeta.xml (which contains pre-defined metadata values)
must either be in the Include directory of the SDK or in the same directory as
the Manifest Generator tool.

Event Provider

The
Event Provider is the entity which will be raising events on the system. An
executable may have one or more event providers. There can be at most 16
providers defined in a single manifest file. Certain tools such as Logman.exe
and Perfmon.exe enable events for a particular provider. To get to the pane to
create the provider, click “Events Section” on the left-pane and
then click “New Provider” on the right-pane. The table below
describes the different attributes for the even provider.

Name

The name of the provider is an English-only user-friendly identifier which
can be used to enable/disable tracing for the provider. The recommended guidance
for provider names is the following pattern: <CompanyName>--<ProductName>--<ComponentName>.
The name must be shorter than 260 characters and can only contain
alpha-numeric, underscore and hyphen characters.

Symbol

The symbol of the provider is the code-friendly name which can be used to
refer to the provider in the code; this generally is a variable name for the
provider and can only contain alpha-numeric and underscore characters.

GUID

The GUID of the provider is a unique identifier which will be used to
register the event provider with the system; the provider cannot log events
unless it has registered the GUID with the system.

Resources

(Decoding
File Location)

This
is the full path of the file that contains the event metadata in its
resources. When the manifest is compiled during build, the metadata
information is compiled as a resource and attached to the file contained in
this parameter. In most cases, this will be the full path to the executable
that has the code to log the events.

Messages

(String
File Location)

This
is a semi-colon separated list of full paths to the files that contain the localized
string resources; the actual strings may be stored separately from the file
pointed to by the Resource attribute which contains event metadata such as
event templates. In most cases, this will be the same full path to the
executable specified in the Resources attribute above.

Parameters

This
is an optional file name which contains the double-substitution parameters.
Please see MSDN for further information since this is an advanced topic.

Event Channels

Channels
refer to streams of events that specify a particular destination. For example,
events can flow into the global “Application” channel system
administrators can monitor through the Event Viewer. Events can also flow into
an Analytic channel which directs the events to a trace file. Tools such as
Wevtutil.exe and Event Viewer enable events based upon channels.

The
channel is a mechanism of distinguishing between different types of events.
Events that are raised into Admin or Operational channels are usually specifically
targeted at the end-user and are usually actionable events with deterministic
resolution (for example, a “Printer Out of Paper” event). Events
that are raised in an Analytic or Debug channel tend to be much more frequent
and less actionable; analysis can only take place when viewing a collection or
flow of events into these channels rather than a single event for
Admin/Operational channels.

To
define a channel, either click on the provider name or
“Levels” on the left-pane and then click “New Channel”
on the right-pane.

NOTE:
Global and pre-defined channels such as “System” or
“Application” can be accessed directly in the event section when
defining events.

Name

The
name of the channel is an English-only user-friendly string identifier which
uniquely identifies that channel for a particular provider. The recommended
pattern for the channel name is <ProviderName>/<ChannelType>. The channel name cannot be longer than
260 characters, must not conflict with reserved names and can only contain
alpha-numeric, underscore, forward slash and hyphen characters.

Symbol

This
is a variable name which will be used to refer to the channel in code; it must
be in the form of a variable identifier and can only contain alpha-numeric
and underscore characters and cannot exceed 260 characters in length.

Type

This
refers to the audience of the events which will be raised into this channel.
The following list of channel types is in order of increasing event frequency
(how many events are raised per second?) / decreasing deterministic
resolution (can the user take specific action on receiving that event?):
Admin, Operational, Analytic, Debug.

Enabled

This refers to whether the channel will be enabled by default or not. It is not recommended to enable analytic and
debug channels by default because doing so will create an autologger
(please see MSDN for further details); rather, analytic and debug channels
should only be turned on when needed. Admin and Operational channels can
remain either enabled or disabled by default, depending on the type of events
that are raised into these channels. Admin/Operational channels that do not
use custom security will be delivered to the EventLog
service, while Analytic/Debug channel events will be written to a trace file.

Description

This
is a string description which informs readers about this channel and events that
are raised to this channel; this string can be localized and must not be more
than 260 characters in length. The actual string will be in the string table
section of the manifest; the string table culture will be the current system
locale.

Channel Security

Default

There
are no special permissions needed to write events to this channel (inherits
from Application isolation). This is the default security on any channel
created by the tool.

Isolation

There
are currently two options for isolation: Application and System. These
isolations can be specified on Admin and Operational channels. Application
isolation specifies that no special permissions are needed to write events to
that channel. System isolation means that only providers running under system
service accounts can write events to that channel.

Access
(SDDL)

This
specifies custom security on the channel in the form of an SDDL string. This
will indicate under what security an event can be raised to the channel.
Creating a channel with custom security will raise trace events to a trace
file rather than to the EventLog service.

Event Tasks

Tasks
are logical grouping of events that indicate a similar activity is taking place.
There are no pre-defined tasks on the system; all tasks are user-defined. An
example of a task would be setting up a TCP connection; there would be a set of
events that would be raised related to the activity of setting-up a TCP
connection. To create a task, either click on the provide name or
“Tasks” on the left-pane and then click “New Task” on
the right-pane.

Name

The
name is an English-only user-friendly identifier for the task which uniquely identifies
the task for a particular provider. The task name cannot be more than 260
characters in length and can only contain alpha-numeric and underscore
characters.

Symbol

The
symbol of the task is a variable-identifier which can be used to refer to the
task in code and can only contain alpha-numeric and underscore characters and
cannot exceed 260 characters in length.

Value

The
value of the task; it must be a number between 1 and 65536

Description

This
is a string description which informs readers about this task and events that
are raised with this task attribute; this string can be localized and must
not be more than 260 characters in length. The actual string will be in the
string table section of the manifest; the string table culture will be the
current system locale.

Event Opcode

The
opcode refers to a specific action that is taking
place within a task. An example opcode in the task
“Setting up a TCP Connection” would be “Sending
Acknowledgement Packet”. There are certain predefined opcodes
that indicate specific actions which can be used in event definitions; any
user-defined opcodes must not have the same name or
values as the pre-defined opcodes. To create an opcode, either click on the
provider name or “Opcodes” on the
left-pane and then click “New Opcode” on
the right-pane.

NOTE:
Pre-defined opcodes such as “Start” can
be accessed directly in the event section when defining events.

Name

The
name is an English-only user-friendly identifier for the opcode
which uniquely identifies the opcode for a
particular provider. The opcode name cannot be more
than 260 characters in length, must not conflict with reserved names and can
only contain alpha-numeric and underscore characters.

Symbol

The
symbol of the opcode is a variable-identifier which
can be used to refer to the opcode in code and can
only contain alpha-numeric and underscore characters.

Value

The
value of the opcode; it must be a number between 10
and 239, since the values 1-10 are reserved and 240-255 are reserved.

Description

This
is a string description which informs readers about this opcode
and events that are raised with this opcode
attribute; this string can be localized and must not be more than 260
characters in length. The actual string will be in the string table section
of the manifest; the string table culture will be the current system locale.

Event Level

The
level is a numeric value which corresponds to the severity of the event. There
are 5 pre-defined level values ranging in severity from “Critical”
to “Verbose”; an event that has no level (level 0) is always
logged.

Controllers
such as logman.exe and perfmon.msc, in addition to
providing keywords that correspond to which events to enable, can also specify
the severity of events. For example, a controller may say that only events with
severity Error or higher (Error and Critical events) should be logged; this is
another form of source filtering. Events that have no level (level 0) will
always be logged regardless of the severity the controller enables. Moreover,
each level that the controller specifies will enable events with a severity at
that level or higher. If the controller enables a provider with level Warning,
then events that have level Critical (value 1), Error (value 2), Warning (value
3) or no Level (value 0) will all be successfully logged.

To
create a new level, click on the provider name or click “Levels” on
the left-pane and then click “New Level” on the right-pane.

NOTE:
Pre-defined levels such as “Error” can be accessed directly in the
event section when defining events.

Name

The
name is an English-only user-friendly identifier for the level which uniquely
identifies the level for a particular provider. The level name cannot be more
than 260 characters in length, must not conflict with reserved level names
and can only contain alpha-numeric and underscore characters.

Symbol

The
symbol of the level is a variable-identifier which can be used to refer to
the level in code and can only contain alpha-numeric and underscore
characters.

Value

The
value of the level; it is a value between 16 and 255 (the values 0-5 are
pre-defined levels and 6-15 are reserved).

Description

This
is a string description which informs readers about this level and events
that are raised with this level attribute; this string can be localized and
must not be more than 260 characters in length. The actual string will be in
the string table section of the manifest; the string table culture will be
the current system locale.

Event Keywords

The
keyword is a 64-bit mask that denotes event categories; each bit in the 64-bit
keywords corresponds to a different event category. The top 8 bits in the
keyword mask are reserved, and the 8 high-order bits of the keyword mask
correspond to pre-defined keywords; therefore, only 48 user-defined keywords
are allowed.

Events
may correspond to more than one category. For example, there may be three
keywords defined for a provider: fileRead, fileWrite, remoteFile, localFile. In such a case, events can be raised that
correspond to two keywords; for example, there may be an event that is raised
when a user tries to write to a local file (fileWrite
and localFile) or read from a remote file (fileRead and remoteFile).

Controllers
such as logman.exe and perfmon.msc use keywords to
enable events for a particular provider. Creating a logical expression of
keywords using bitwise-AND and bitwise-OR, control applications which enable
events can use the keyword flags to specify which events to enable; this
provides a form of source filtering which can reduce the number of events that
are logged rather than going through all the events in post-processing to find
the ones that correspond to particular keywords.

To
create a keyword, either click on the provider name
click “Keywords” on the left-pane and then click “New
Keyword” on the right-pane.

NOTE:
Pre-defined keywords such as “WDIContext”
can be accessed directly in the event section when defining events. The
Manifest Generator tool does not support the EventlogClassic
keyword.

Name

The
name is an English-only user-friendly identifier for the keyword which
uniquely identifies the keyword for a particular provider. The keyword name
cannot be more than 260 characters in length, must not conflict with reserved
names and can only contain alpha-numeric and underscore characters.

Symbol

The
symbol of the keyword is a variable-identifier which can be used to refer to
the keyword in code and can only contain alpha-numeric and underscore
characters.

Value

The
value of the keyword; it is a hex value between 0x0000000000000001 and
0x0000800000000000 (since the keyword values 0x0001000000000000 to
0x8000000000000000 are reserved)

Description

This
is a string description which informs readers about this keyword and events
that are raised with this keyword attribute; this string can be localized and
must not be more than 260 characters in length. The actual string will be in
the string table section of the manifest; the string table culture will be
the current system locale.

Event Maps

Event
maps allow design of either Value maps or Bit maps which create a mapping or
translation between values and message strings. For example, in a Value map the
value “1” can be mapped to the string “Hello World”.
When consumers get the event that contains the map, they will see “Hello
World” in place of the value “1”. If it was defined as a Bit
map, then the map “0x00000001” can be mapped to the string
“Hello World”.

Once
the map is defined, it is then included in the template definition. Both the
value map and bit maps can only be used for a single payload field; it cannot
be used in an array. The map can be used in a structure field, as long as that
field does not correspond to an array. In both cases, when defining the
template that includes the map field, the inType for
the template field must be a “UInt32”

To
create a new map, click on the provider name or click “Maps” on the
left-pane and then click “New Map” on the right-pane.

Name

The
name of the map is what will be used to link the map definition to the
payload field in the template definition. This is a variable-style identifier
which can only contain alpha-numeric and underscore characters.

Type

The
type of map currently supported by the tool is either Value Map or Bit Map.
The Value Map maps unsigned integer values to strings. The Bit Map maps hex
values to strings.

Value

This
is the value of a map field; there cannot be duplicate values in a map. For a
Value Map, the value must be an unsigned 32-bit integer. For Bit map, the
value can be adjusted using the slider.

Message

This
is the message string which will be mapped to the value defined above. This
message string will be stored in the manifest and decoding tools will
correctly map the value above to this string; this message string can be
localized and must be shorter than 260 characters. The actual string will be
in the string table section of the manifest; the string table culture will be
the current system locale.

Event Payload (Template)

The
event template describes the optional variable payload section of the event.
When the event is logged using the APIs, the payload is packed closely together
for efficiency and performance. Therefore, there are no markers that are logged
to distinguish between different fields in the payload. Tools and applications
which need to consume the events must look at the templates for the event in
order to distinguish the different fields of the event payload. The correct
template is found by looking at the standard header information (event ID,
version, etc) and find the corresponding event definition in the manifest which
links the standard event header with the templates.

The
template can be shared by multiple events, since different events can have the
same payload and the template describes the payload. The template can define a
single field or a data structure such as a structure or an array. The structure
is defined in a separate section in the tool from the template, and must be included
in the template.

The
symbol of the template is what is
used to link the event definitions to the proper template definitions; it is
only used by tools to link these two sections together and is not logged with
the event. The symbol can only contain alpha-numeric and underscore characters.

Defining a Single
Data Field

Name

This
is the English-only name of the data field, as it will show in the output of
the event when a consumer is viewing this event. For example, a field that
represents an IP address might have the name “IPAddress”.
The name cannot be more than 260 characters long and can only contain
alpha-numeric and underscore characters.

inType

This
is how the data field will be logged as part of the event; the
“raw” form of the data without being formatted for display. An
example of an inType would be an unsigned integer
which actually represents an IPv4 address; when the event is logged, this
field of the payload will be an integer.

Structures
that are defined will also show in the inType list.
To select a structure as a field in the template, simply select the structure
name (note that structures are defined in a different section of the tool).

outType

This
is a hint to consumers of the event on how to display this field of the event
payload. In the example of an IPv4 address, the outType
will be “IPv4”; thus, when tools receive the data that has inType unsigned integer, it will display it as an IP
address.

If
the inType is a UInt32, then a map can also be used
in place of the outType.
Both Bit maps and Value maps are enabled only when the inType
is UInt32; the map that will show in the drop-down will be the Map name
attribute.

Length

Certain
inTypes don’t have any inherent length
associated with them. For example, unlike an unsigned integer which has
length 4 bytes, the inType win:Binary does not have a fixed length; this property
specifies the length of the data field. Likewise, if Unicode and ANSI strings
are not null-terminated, then the length must be specified.

Defining an Array

The
same fields that are described above must be defined for an array as well. The
array can be of single field default inTypes or of
structures. The count field describes
the length of the array. An array can have either a fixed length or a variable
length where the length of the array is defined by another variable. If the
array length is variable, the length of the array must be defined by either a UInt8 or UInt16 single payload field that is defined before the array is
defined in the “Current Fields” view of the payload.

Defining a
Structure

A
structure is a combination of single data fields or data arrays; it can be
considered a template except that unlike a template which can contain a
structure, a structure cannot contain another structure. The structure is
defined by clicking “New Struct” after
defining a provider or clicking “Structs”
on the left-pane and then clicking “New Struct”
on the right-pane.

The
symbol will be used to tie the
structure definition in with the proper template. When a field in the template
needs to be indicated as a structure, the inType will
have the symbol of the structure. The symbol can only contain alpha-numeric and
underscore characters.

Just
like defining a single field in the template case, a field in the structure
must have a name, inType, outType
and length (in some cases). If the field is an array, then the count attribute
must additionally be defined.

The
list of inType and their corresponding outType is listed in the file winmeta.xml
and can be found on MSDN.

NOTE:
When saving a structure to be included in a template, the structure must be included in the template and the
manifest must be saved before closing or exiting the tool. If this is not done,
then the structure definition will be
lost.

Event Definitions

The
event is divided into two sections: the standard header information and the
optional variable payload section. The header information includes the Event
ID, Version, Task, Opcode, Channel, Level and
Keywords; this information is standard across all defined events. The optional
variable section which describes the event payload is defined by templates; the
payload is any arbitrary data is that is logged in addition to the standard
header information.

To
create a new event, click on the provider name or click “Events” on
the left-pane and then click “New Event” on the right-pane.

ID

This
is a numeric identifier for the event; it can be a value between 0 and 65535.
Two separate event definitions cannot have the same ID and Version number
combination since the ID/Version must uniquely identify an event for that
provider.

Version

This
is a numeric identifier which indicates the version of the event; by default the
version is 0. Two separate event definitions cannot have the same ID and
Version number combination since the ID/Version must uniquely identify an
event for that provider.

Task

This
is an optional field which indicates the logical activity being performed by
the component emitting the event; there are no pre-defined tasks. Please see Tasks for how to define a new task.

Opcode

This
is an optional field which indicates a specific action being performed by the
component emitting the event; there are 10 pre-defined opcodes
which can be used; winmeta.xml and MSDN list the
definitions. Please see Opcodes
for how to define a new opcode. Both pre-defined opcodes and new opcodes will
show in the drop-down list.

Channel

This
is an optional field which indicates a logical grouping of events for a
specific target audience. There are four pre-defined channels; winmeta.xml and MSDN list the definitions. Please see Channels for how to define a new channel. Both
pre-defined channels and new channels will show in the drop-down list.

Level

This
is an optional field which indicates the severity of the event. There are
five pre-defined channels; winmeta.xml and MSDN
list the definitions. Please see Level for how to
define a new level. Both pre-defined levels and new levels will show in the
drop-down list.

Keywords

This
is an optional list of checkboxes that indicates to which categories the
event belongs. Each keyword will enable a bit in the keyword bitmask; there are 5 pre-defined keywords; winmeta.xml and MSDN list the definitions. Please see Keywords for how to define a new keyword. Both
pre-defined keywords and new keywords will show as checkboxes in the list.

Template

This
is an optional field which defines the variable payload section of the event;
the drop-down list shows all of the template symbols that are defined for the
provider. Please see Event Payload for how to
define a new template.

Message

This
is a field which indicates the message of the event; this can also be
considered a description for an event. Note that the description is required for events that are raised
into an Admin-type channel; otherwise it is optional. The message can also
contain substitution parameters to place payload fields in the message itself
when the event is being consumed. The actual string will be in the string
table section of the manifest; the string table culture will be the current
system locale.

PERFORMANCE
COUNTERS REFERENCE

The
design steps to instrument code with performance counters are as follows: the
performance counters are defined in the XML-format manifest file. Once complete,
the CTRPP tool is run against the manifest to generate a header file which
contains the counter definitions and a source file which has function
signatures. The header file needs to be included in all code that updates
values of the counters or creates instances of the counterset.

The
LODCTR tool needs to be run against the manifest during installation in order
to modify the registry with the necessary attributes to find the counter
information that was defined in the manifest. This will be used by consumer
applications that retrieve the counter information for analysis.

The
performance counters themselves are use to provide information and status to
consumers or monitoring applications. Counter provider applications design
different counters for different tasks and then register these counters with
the system. When a consumer application wishes to retrieve performance metrics,
the system will query the counter values and send them back to the application
which requested them; the counter values can also be sent to remote machines.
Consumers and monitoring applications, upon receiving the counter data, can
then perform the necessary analysis needed to determine the state of the
providing application or system.

The
counter provider is the entity that will be updating the counter values; the
provider notion is strictly used by the system to convey the counter
information to the consumer. The provider can define one or more countersets, which are logical groupings of counters. Each counterset can contain one or more individual counters.

Provider

CounterSet

Counter

Performance Counter Provider

The
counter provider is strictly used to provide counter data and allow consumers
to retrieve performance counter data. The new Performance Counter Library is
built upon the same system used to deliver events; consumers that want to
retrieve counter data specify the counter, and the system maps which counters
are updated by which providers. Therefore, the provider is hidden from the end
consumer of counter data even though the system uses it to retrieve and send
counter data.

To
create a provider, click on the “Performance Counters Section” on
the left-pane and click “New Provider” on the right-pane.

Name

The
name of the provider. The provider name is an English-only string, must not
be more than 260 characters in length and can only contain alpha-numeric and
hyphen characters.

GUID

This
is the GUID of the provider which will be used by the system to relay counter
queries between the provider and the consumer actually querying for the
counter data.

Application
Identity

This
is the name of the application which will be exposing counter data; this
generally will be the name of the executable (for example,
CounterProvider.exe).

Callback

The
callback is used when the provider wishes to be notified that the consumer wants
to query counter data; this may be used to perform any necessary calculations
to update counter values when a query comes for counter data. By default, the
provider will not be notified. Note that simply checking this box will
generate the framework of the callback function which will be called on a
counter query.

Resource
Base

This
attribute specifies at which numeric value the string identifiers will start.
The default is set at 1 and should not be adjusted unless multiple resource
files will be merged, in which case the string
identifier numeric values may conflict thus making it necessary to start the
identifier numeric values from a different starting value (specified using
this attribute).

Performance Counter CounterSet

The
Counterset refers to a logical grouping of counters
and is the basis for how consumers of performance counters retrieve counter
data. The CounterSet consists of one or more counters
that are related in an aspect that the consumer would understand. Countersets can either be single or multiple instance countersets. For example, there can be a counterset which monitors disk activity for the entire hard
disk (this would be a single instance counterset
assuming one hard disk) or an instance of a counterset
for each DLL loaded into a process. In addition, aggregate countersets
define how counter values across the countersets
should be manipulated. For example, there can be a DiskRead
counter belonging to an aggregate counterset that
will sum all DiskRead counter values across the
different volumes on the disk to provide a total DiskRead
value.

The
counterset is identified by a name which can be
localized; the system uses a GUID to identify the counterset.
To create a counterset, click on the counter provider
on the left-pane and click “New Counter Set” on the right-pane.

Name

The
name of the counterset is what counter consumers
will see to determine whether the counters contained within the counterset are of interest; the name can be localized but
must not be more than 1024 characters in length. Please see MSDN for reserved
characters. The actual string will be in the string table section of the
manifest; the string table culture will be the current system locale.

GUID

This
is what the system will use to uniquely identify the counterset.
Two countersets cannot have the same GUID.

URI

This
is a uniform resource identifier to uniquely identify the counterset
in a neutral manner. The URI is an English-only string, cannot be more than
1024 characters in length and cannot contain space characters.

Description

This
string describes the counterset and the counters
contained within the counterset; this string can be
localized. The string cannot be more than 1024 characters in length. The
actual string will be in the string table section of the manifest; the string
table culture will be the current system locale.

Instances

This
attribute indicates whether there can be more than one instance of the counterset created. In addition, this attribute can specify
whether aggregations should occur for the counters within the counterset.

Single

This
is the default setting; this enables only one instance of the counterset to exist. Consumers will only see this single
instance from which they can query data.

Multiple

This
enables multiple instances of the counterset to
exist; consumers of the counter data will be able to specify which instance
of the counterset they wish to query for data.

globalAggregate

This
is a single instance counterset from the consumer
perspective, but many providers may be contributing data. Each counter provider
will register an instance of this counterset, and
the system will perform the aggregation function across all these instances
such that the consumer will only see a single “global” instance
of the counterset.

multipleAggregate

This
is a multiple instance counterset from the consumer
perspective, but aggregation functions can be performed across the multiple
instances of the counterset when a consumer queries
from different instances.

globalAggregateHistory

This
is a single instance counterset from the consumer
perspective, but many providers may be contributing data. The data is
“historically” cached for the lifetime of the consumer and used
in aggregation functions. Note that all counters are cached and the
aggregation functions are performed to include the cached historical values.

Performance Counters Definition

This
is the counter entity which contains the value that is of interest to counter consumers.
The counter is defined to belong to a counterset,
which logically groups related counters. Applications and counter providers,
however, update individual counter values. If there are multiple instances of a
counterset, there will be multiple instances of the
counter on the system.

The
value of a counter will either be of interest to the counter consumer or it may
be a counter value which will be used in other calculations to create a
meaningful value for the counter consumer. In addition, the counter value might
be used in different scenarios (a timer versus a counter which monitors the
number of disk reads). This information is conveyed through a counter type;
there are counter types which indicate what operations the counter value can be
used for and how to calculate a meaningful value using the values of other
counters. The different counters and their dependencies are available on MSDN.

To
create a counter, click on the Counterset name on the
left-pane and then click “New Counter” on the right-pane.

NOTE:
The Manifest Generator tool does not support the Multi-timer, Inverse
Multi-timer, 100ns Multi-timer and the 100ns inverse Multi-timer.

Name

The
name of the counter is what counter consumers will use in order to determine whether
the counter value is of interest; this name can be localized but must not be
more than 1024 characters in length. Please see MSDN for reserved characters.
The actual string will be in the string table section of the manifest; the
string table culture will be the current system locale.

ID

This
is a unique numeric identifier which specifies a single counter in the counterset; there can be no duplicate counter IDs within
the same counterset.

URI

This
is a uniform resource identifier to uniquely identify the counter in a
neutral manner. The URI is an English-only string, cannot be more than 1024
characters in length and cannot contain space characters

Description

This
string describes the counter; this string can be localized. The string cannot
be more than 1024 characters in length. The actual string will be in the
string table section of the manifest; the string table culture will be the
current system locale.

Detail
Level

This
specifies whether the counter is intended for advanced consumption; by
default, the level is Standard.

Type

This
specifies the counter type, which is used to indicate the type of counter value
and whether the value is dependent on other counter types. Please see MSDN
for a complete list of the different counter types and their descriptions.
The default is a “Counter Raw Count” type counter.

Base
ID

This
ID identifies the ID field of another counter upon which the counter value
depends. This ID must point to an “Average Base” counter. Please
see MSDN for which counters require a base counter.

Default
Scale

This
attribute specifies a hint to consumer applications on how much to scale the
axis when displaying counter values.

perfTimeID

This
attribute identifies the ID field of another counter upon which the counter
value depends. This ID must point to a “Counter large raw count”
counter. Please see MSDN for which counters require a base timestamp counter.

perfFreqID

This
attribute identifies the ID field of another counter upon which the counter
value depends. This ID must point to a “Counter large raw count”
counter. Please see MSDN for which counters require a base timestamp value.

Aggregate

This
is the aggregate function to be performed on the counter value when the counterset type is specified as “globalAggregate”, “multipleAggregate”
or “globalAggregateHistory”.