Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Defining Channels

Events can be written to event log channels, event tracing log files, or both. A channel is basically a sink that collects events. If the target audience for your events uses event consumers such as the Windows Event Viewer, you must define the channels to where your events are written or import an existing channel that another provider defined.

To define your own channels, use the channel element. To define an imported channel, use the importChannel element. You can specify up to eight channels in any combination of imported channels or channels that you provider define.

The channel must be of one of four types: Admin, Operational, Analytic, and Debug. Each channel type has an intended audience, which determines the type of events that you write to the channel. For a description of each type, see the ChannelType complex type.

To specify the channel to which an event is written, set the event definition's channel attribute to the same value as the channel definition's chid attribute. The event is always written to the channel, regardless of whether an ETW tracing session enabled the provider. If the event does not specify a channel, that event can be written only to an ETW tracing session.

The following example shows how to import a channel. You must set the chid and name attributes. The chid attribute uniquely identifies the channel—each channel identifier in your list of channels must be unique. Set the name attribute to the same name that the provider used when it defined the channel.


<instrumentationManifest
    xmlns="http://schemas.microsoft.com/win/2004/08/events" 
    xmlns:win="http://manifests.microsoft.com/win/2004/08/windows/events"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"    
    >

    <instrumentation>
        <events>
            <provider name="Microsoft-Windows-SampleProvider" 
                guid="{1db28f2e-8f80-4027-8c5a-a11f7f10f62d}" 
                symbol="PROVIDER_GUID" 
                resourceFileName="<path to the exe or dll that contains the metadata resources>" 
                messageFileName="<path to the exe or dll that contains the string resources>"
                message="$(string.Provider.Name)">

                <channels>
                    <importChannel chid="c1" 
                                   name="Microsoft-Windows-BaseProvider/Admin"
                                   symbol="CHANNEL_BASEPROVIDER_ADMIN">
                </channels>

                . . .
            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources culture="en-US">
            <stringTable>
                <string id="Provider.Name" value="Microsoft-Windows-SampleProvider"/>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>

Although Winmeta.xml defines legacy channels that you can import, you should not use them unless you are supporting legacy consumers that consume events out of the legacy channels (for example, Application or System). The Winmeta.xml file is included in the Windows SDK.

The following example shows how to define a channel. You must set the chid, name, and type attributes. The chid attribute uniquely identifies the channel—each channel identifier in your list of channels must be unique. Set the chid attribute to a value that is unique for the channels that your provider lists; the channel identifier is referenced in one or more of your event definitions. The convention for naming the channel is to use the provider name and channel type in the form, providername/channeltype.


<instrumentationManifest
    xmlns="http://schemas.microsoft.com/win/2004/08/events" 
    xmlns:win="http://manifests.microsoft.com/win/2004/08/windows/events"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"    
    >

    <instrumentation>
        <events>
            <provider name="Microsoft-Windows-SampleProvider" 
                guid="{1db28f2e-8f80-4027-8c5a-a11f7f10f62d}" 
                symbol="PROVIDER_GUID" 
                resourceFileName="<path to the exe or dll that contains the metadata resources>" 
                messageFileName="<path to the exe or dll that contains the string resources>"
                message="$(string.Provider.Name)">

                <channels>
                    <importChannel chid="c1" 
                                   name="Microsoft-Windows-BaseProvider/Admin"
                                   symbol="CHANNEL_BASEPROVIDER_ADMIN">

                    <channel chid="c2" 
                             name="Microsoft-Windows-SampleProvider/Operational"
                             type="Operational"
                             enabled="true">
                </channels>

                . . .

            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources culture="en-US">
            <stringTable>
                <string id="Provider.Name" value="Microsoft-Windows-SampleProvider"/>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>

 

 

Community Additions

Show:
© 2014 Microsoft