Instrumentation Manifests for Event Publishers
Instrumentation manifests contain event publisher metadata, event definitions and templates, channel definitions, and the localized event messages. Events that will be published through an event publisher are first defined in an instrumentation manifest. For more information about event publishers and their metadata, see Event Publishers in Windows Event Log.
Structure of an Instrumentation Manifest
Instrumentation manifests are created in a particular structure and can be validated against the EventManifest Schema.
The instrumentation manifest includes the following information:
- The identity of the publisher and the location of the publisher's resources.
- The definition and settings of any channels which are created by the application. For more information on channels, see Event Logs and Channels in Windows Event Log.
- The definition, XML shape, message text and destination channel of the events which are reported by the publisher.
- Localized event messages.
The following XML example shows how a manifest that contains event definitions is structured.
<!-- <?xml version="1.0" encoding="UTF-16"?> -->
<instrumentationManifest
xmlns="https://schemas.microsoft.com/win/2004/08/events"
xmlns:win="https://manifests.microsoft.com/win/2004/08/windows/events"
xmlns:xs="https://www.w3.org/2001/XMLSchema">
<instrumentation>
<events>
<!--Publisher Info -->
<provider name="Microsoft-Windows-EventLogSamplePublisher"
guid="{1db28f2e-8f80-4027-8c5a-a11f7f10f62d}"
symbol="MICROSOFT_SAMPLE_PUBLISHER"
resourceFileName="C:\temp\Publisher.exe"
messageFileName="C:\temp\Publisher.exe">
<!--Channel to which this Publisher can publish -->
<channels>
<!--Pre-Existing channel can be imported, but not required. -->
<importChannel chid="C1" name="Application"/>
<!--New Channel can be declared for this Publisher-->
<channel chid="MyChannel"
name="Microsoft-Windows-EventLogSamplePublisher/Operational"
type="Operational"
symbol="SAMPLE_PUBLISHER"
isolation="Application" enabled="true"/>
</channels>
<!--Event Templates -->
<templates>
<template tid="MyEventTemplate">
<data name="Prop_UnicodeString" inType="win:UnicodeString" />
<data name="Prop_AnsiString" inType="win:AnsiString" outtype="xs:string" />
<data name="Prop_Int8" inType="win:Int8" />
<data name="Prop_UInt8" inType="win:UInt8" />
<data name="Prop_Int16" inType="win:Int16" />
<data name="Prop_UInt16" inType="win:UInt16" />
<data name="Prop_Int32" inType="win:Int32" />
<data name="Prop_UInt32" inType="win:UInt32" />
<data name="Prop_Int64" inType="win:Int64" />
<data name="Prop_UInt64" inType="win:UInt64" />
<data name="Prop_Float" inType="win:Float" />
<data name="Prop_Double" inType="win:Double" />
<data name="Prop_Boolean" inType="win:Boolean" />
<data name="Prop_GUID" inType="win:GUID" />
<data name="Prop_Pointer" inType="win:Pointer" />
<data name="Prop_FILETIME" inType="win:FILETIME" />
<data name="Prop_SYSTEMTIME" inType="win:SYSTEMTIME" />
<data name="Prop_SID_Length" inType="win:UInt32" />
<data name="Prop_SID" inType="win:SID" length="Prop_SID_Length"/>
<data name="Prop_Binary" inType="win:Binary" length="11" />
<UserData>
<MyEvent2 xmlns="myNs">
<Prop_UnicodeString> %1 </Prop_UnicodeString>
<Prop_AnsiString> %2 </Prop_AnsiString>
<Prop_Int8> %3 </Prop_Int8>
<Prop_UInt8> %4 </Prop_UInt8>
<Prop_Int16> %5 </Prop_Int16>
<Prop_UInt16> %6 </Prop_UInt16>
<Prop_Int32> %7 </Prop_Int32>
<Prop_UInt32> %8 </Prop_UInt32>
<Prop_Int64> %9 </Prop_Int64>
<Prop_UInt64> %10 </Prop_UInt64>
<Prop_Float> %11 </Prop_Float>
<Prop_Double> %12 </Prop_Double>
<Prop_Boolean> %13 </Prop_Boolean>
<Prop_GUID> %14 </Prop_GUID>
<Prop_Pointer> %15 </Prop_Pointer>
<Prop_FILETIME> %16 </Prop_FILETIME>
<Prop_SYSTEMTIME> %17 </Prop_SYSTEMTIME>
<Prop_SID_Length> %18 </Prop_SID_Length>
<Prop_SID> %19 </Prop_SID>
<Prop_Binary> %20 </Prop_Binary>
</MyEvent2>
</UserData>
</template>
</templates>
<!--All the Events that can be published by this Publisher -->
<events>
<event value="1"
level="win:Informational"
template="MyEventTemplate"
opcode="win:Info"
channel="MyChannel"
symbol="PROCESS_INFO_EVENT"
message="$(string.Publisher.EventMessage)"/>
</events>
</provider>
</events>
</instrumentation>
<localization>
<resources culture="en-US">
<stringTable>
<!--This is how event data can be used as part of Message String -->
<string id="Publisher.EventMessage"
value="Prop_UnicodeString=%1;%n
Prop_AnsiString=%2;%n
Prop_Int8=%3;%n
Prop_UInt8=%4;%n
Prop_Int16=%5;%n
Prop_UInt16=%6;%n
Prop_Int32=%7;%n
Prop_UInt32=%8;%n
Prop_Int64=%9;%n
Prop_UInt64=%10;%n
Prop_Float=%11;%n
Prop_Double=%12;%n
Prop_Boolean=%13;%n
Prop_GUID=%14;%n
Prop_Pointer=%15;%n
Prop_FILETIME=%16;%n
Prop_SYSTEMTIME=%17;%n
Prop_SID_Length=%18;%n
Prop_SID=%19;%n
Prop_Binary=%20"/>
</stringTable>
</resources>
</localization>
</instrumentationManifest>
Provider metadata and event information are found in the manifest in the following elements:
-
This is the top level element in an instrumentation manifest. This element contains the elements that configure event publishers, create and configure new channels, disclose what events a publisher is planning to publish (and into which channels the events are published), and provide localized strings to be used in event rendering (displaying the event message).
-
Contains the elements that configure event publishers and disclose what events a publisher is planning to publish. This element contains a list of all the publishers in the manifest.
<events> (parent element: <instrumentation>)
Defines a list of event publishers that is defined in the manifest. This element also allows you to create a list of event messages.
-
Contains provider metadata for an event publisher. The metadata contains information such as the provider's name, channels that are used by the provider, opcodes, and other data in the provider. For more information about the metadata that can be defined, see ProviderType Complex Type.
-
Contains the list of channels into which this provider publishes events. You can create a channel in the manifest or import a channel from a previously created manifest. The channels that are referenced in the event definitions must be declared or imported in the manifest. When a channel is referenced by an event definition, the event will be published into this channel. For more information about channels, see Event Logs and Channels in Windows Event Log.
-
Contains the definitions of opcodes to be used by the events published by this provider. For more information about opcodes, see OpcodeType Complex Type.
-
Contains the definitions of keywords to be used by the events published by this provider. For more information about keywords, see KeywordType Complex Type.
-
Contains the data-rendering templates used by the events published by this provider.
Templates specify the names and the types of data that the event publisher supplies with an event. Additionally, a template may specify a UserData element that contains custom XML that will be used when the data is rendered for the event.
Note The substitution parameter %1 specifies that a string value will be dynamically supplied by the publisher when the event is raised. For more information about the event template element, see template(TemplateListType) and TemplateItemType Complex Type.
<events> (parent element: <provider>)
Contains the definitions of the events published by a provider. Each event has a 16-bit integer ID associated with it. Additionally, each event has a set of classifiers present even when they are not explicitly identified in the event definition (there are default values for all classifiers): task, opcode, keywords, version, and level. The combination of the value and version of the event uniquely identifies an event. For more information about defining an event in the manifest, see EventDefinitionType Complex Type. For more information about how the ID and the classifiers appear in the XML event representation, see Event Representation for Event Consumers.
-
Specifies a list of event messages or references to strings in the localization section of the manifest.
The event message is a readable description of the event. This description is localized. The message can also contain substitution parameters (similar to template) that specify user supplied values from the event to substitute into the message so that the full description suitable for display to the user can be formed.
The following XML example shows how to use substitution parameters in event messages. A printer name value can be substituted into the message (as it is the first parameter) during an event.
Print Spooler has failed to connect to %1 printer. All further print jobs to this printer will fail. Ping the printer to check if it is online.
Send comments about this topic to Microsoft
Build date: 5/7/2009