Enterprise Instrumentation ReadMe

You must be running Windows XP Professional, Windows 2000 SP2 or later (all editions), or Windows Server 2003 to use Enterprise Instrumentation. It is recommended that you upgrade to Windows XP Professional SP1 or later, Windows 2000 SP3 or later, or Windows Server 2003, in order to address some of the known issues described below.

If you are using Windows XP Professional or Windows 2000 SP2, please review the following known issue:

Security: Cannot fire WMI events from Web Applications using default ASP.NET security settings

If you are using Windows 2000 SP2, please review the following known issue:

Cannot change Windows Event Trace log filename on Windows 2000 SP2 while trace session is enabled

If you will be installing Enterprise Instrumentation on a computer with both the .NET Framework 1.0 and .NET Framework 1.1 installed, please review the following known issue:

Installing .NET Framework 1.0 and 1.1 on a single machine can cause setup failure or break existing applications

Development Workstations: Install Visual Studio .NET or Visual Studio .NET 2003

Enterprise Instrumentation includes assemblies which you reference within your Visual Studio .NET projects, in order to instrument your applications. It also includes sample Visual Studio .NET projects and source files which demonstrate how to instrument and configure applications and how to use various Enterprise Instrumentation features.

Enterprise Instrumentation is compatible with either Visual Studio .NET, or Visual Studio .NET 2003. Enterprise Instrumentation will register itself with either version of Visual Studio if it is installed. Installation of the .NET Framework is always included when you install Visual Studio .NET or Visual Studio .NET 2003.

If you are installing Visual Studio .NET, you will need to install Service Pack 2 or later for the .NET Framework 1.0, in order to install and run Enterprise Instrumentation. The latest .NET Framework Service Pack can be downloaded here: http://msdn.microsoft.com/netframework/downloads/sp/download.asp

If Visual Studio is installed after Enterprise Instrumentation, Enterprise Instrumentation should be un-installed and re-installed to ensure that it is registered correctly with Visual Studio. Without this, Enterprise Instrumentation assemblies will not show up in the Add Reference dialog box, and no Intellisense will be available when editing Enterprise Instrumentation configuration files.

Application Servers: Install the .NET Framework

Enterprise Instrumentation requires the .NET Framework in order to install and run, and is compatible with both the .NET Framework 1.0 SP2 or later, and the .NET Framework 1.1.

See http://go.microsoft.com/fwlink/?LinkId=5201 for information on deploying the .NET Framework, which Enterprise Instrumentation requires.

Install Enterprise Instrumentation

Note: If you install either Visual Studio .NET or Visual Studio .NET 2003 after installing Enterprise Instrumentation, you will need to un-install and then re-install Enterprise Instrumentation in order to register correctly with Visual Studio. Without this, Enterprise Instrumentation assemblies will not be displayed in the Add Reference dialog box, and Visual Studio will not provide Intellisense when editing Enterprise Instrumentation configuration files.

You must have Administrative privileges in order to install Enterprise Instrumentation. The setup includes installation of a Windows Service, performance counters, and Windows Event Log event sources, all of which require an administrator-level account.

Double-click the EnterpriseInstrumentation.exe file and follow the on-screen instructions. The following command-line parameters can be used for unattended installation:

Parameter Default Value Description

INSTALLDIR %ProgramFiles%\Microsoft Enterprise Instrumentation\ Installation folder for Enterprise Instrumentation.

INSTALL_RUNTIME 1 Installs just the Enterprise Instrumentation core assemblies and Windows Trace Session Manager service.

INSTALL_SCHEMA_SOURCE 1 Installs the source code for the Standard Event Schema, which is used to build custom schemas.

INSTALL_SAMPLES 1 Installs Enterprise Instrumentation code samples.

These parameters should be specified using the following syntax:

EnterpriseInstrumentation.exe /c:"MSIEXEC.EXE /q /i EnterpriseInstrumentation.msi <command_line_parameters>"

For example, to silently install just the core components on a server which will host instrumented applications, the following command-line options can be specified:

EnterpriseInstrumentation.exe /c:"MSIEXEC.EXE /q /i EnterpriseInstrumentation.msi INSTALL_SCHEMA_SOURCE=0 INSTALL_SAMPLES=0"

In this example, Enterprise Instrumentation would install into the default folder as specified in the above table, since the INSTALLDIR parameter was not specified.

Troubleshooting Installation Issues

If an installation error occurs, a more detailed error is typically logged to the Application event log. Please review this log when troubleshooting installation issues.

Note: Please see the following known issue, which describes a case where Enterprise Instrumentation setup fails due to the Trace Session Manager service being unable to start:

Installing .NET Framework 1.0 and 1.1 on a single machine can cause setup failure or break existing applications

Enterprise Instrumentation setup always creates or appends to several log files which provides information about each step of the install process. These log files are found in the current user's temp folder (corresponding to the %temp% environment variable). These files are made up of the following:

Filename Description

EnterpriseInstrumentationSetup.log Created by the self-extracting EXE as it extracts and runs the Enterprise Instrumentation installer file.

EnterpriseInstrumentationInstall.log Created by the Enterprise Instrumentation installer file. Contains information on each installation step.

EnterpriseInstrumentationInstallUtil.log Contains the output of each InstallUtil command, which is used to register and install Enterprise Instrumentation assemblies.

Note: If you receive an error dialog box containing the text "Runtime Error has occurred in script", or find an Application Event Log event which includes the text "Microsoft JScript runtime error: Permission denied", this usually indicates that Enterprise Instrumentation cannot write to its log files. This can be caused by the following:

The existing log files (from a prior Enterprise Instrumentation install) are locked or marked read-only

Another instance of the Enterprise Instrumentation installer has been launched and has locked the log files

There is no temp folder defined for the current user

Review Enterprise Instrumentation Documentation

A help file for Enterprise Instrumentation is located in the \Docs subfolder of the installation folder.

Getting Support for Enterprise Instrumentation

To report issues and get help with Enterprise Instrumentation, contact Product Support Services. When reporting an issue or describing a problem you're having, please provide as much information as possible, including the following:

Operating System version and Service Pack, if any

Installed versions of Visual Studio, including Visual Studio .NET or Visual Studio .NET 2003

Any installed Service Packs for the .NET Framework 1.0

Known Issues

Please review the following known issues which affect Enterprise Instrumentation:

Installing .NET Framework 1.0 and 1.1 on a single machine can cause setup failure or break existing applications
Security: Cannot register Windows Event Log event sources within ASP.NET Web Application under default security settings
Security: Cannot Fire WMI Events from Web Applications using Default ASP.NET security settings
Security: Events logged to remote Event Log are sent in clear text over the network
COM+ Application ID is not logged on Windows 2000
Duplicate EventSequenceNumber when firing events on multiple threads
Cannot change Windows Event Trace log filename on Windows 2000 SP2 while trace session is enabled
Registering an instrumented assembly may fail if the assembly is not in the current working directory
Cannot register Event Schema assembly with duplicate nested class names
Trace Sessions may not be synchronized with TraceSessions.Config if service is stopped
RequestEventSource InternalErrors/Sec _total performance counter instance is always zero
No events are raised in Windows Event Trace log file when it reaches its maximum size
Validation errors not always logged for invalid EnterpriseInstrumentation.Config files
Default WMI SDK installation folder is incorrect in Enterprise Instrumentation documentation

Installing .NET Framework 1.0 and 1.1 on a single machine can cause setup failure or break existing applications

There is a known issue with using Performance Counters via the System.Diagnostics namespace in the .NET Framework, on a machine which has versions 1.0 and 1.1 installed. This has been identified as a problem in the .NET Framework 1.0, and may result in a setup failure when installing Enterprise Instrumentation. If impacted by this issue, please contact Product Support Services to request a hotfix which can be referenced by article ID 813350.

If a .NET Framework 1.1 application reads or writes performance counter information via the PerformanceCounter class, any subsequent attempt to read or write performance counter information by a .NET Framework 1.0 application will fail with an exception. This can occur even if the applications are referencing completely unrelated performance counters. However, if a .NET Framework 1.0 application reads or writes performance counter information first, all subsequent attempts by .NET Framework 1.1 applications will succeed.

On a machine which has both versions of the .NET Framework installed, Enterprise Instrumentation configures the Trace Session Manager Windows Service to use the .NET Framework 1.0 when loading. If another application or service which runs on the .NET Framework 1.1 (and which reads or writes performance counters) is executed before the Trace Session Manager service, it might result in the Trace Session Manager being unable to start. The following error usually indicates that the Trace Session Manager or other .NET Framework 1.0 application is being affected by this issue:

System.InvalidOperationException: Cannot create file mapping.

at System.Diagnostics.FileMapping.Initialize() at System.Diagnostics.FileMapping..ctor()

at System.Diagnostics.SharedPerformanceCounter.get_FileView()

at System.Diagnostics.SharedPerformanceCounter.ResolveOffset(Int32 offset)

at System.Diagnostics.SharedPerformanceCounter.GetCounter(String categoryName, String counterName, String instanceName)

at System.Diagnostics.SharedPerformanceCounter..ctor(String categoryName, String counterName, String instanceName)

at System.Diagnostics.PerformanceCounter.Initialize()

at System.Diagnostics.PerformanceCounter..ctor(String categoryName, String counterName, String instanceName, Boolean readOnly)

...

If a .NET Framework 1.1 application is running and publishing performance counters when Enterprise Instrumentation is installed, it may result in a setup failure due to the Trace Session Manager being unable to start as part of the initial setup. In this case, the error described above will be written to the Application Event Log, indicating that the Trace Session Manager service was unable to start. In this scenario, Enterprise Instrumentation setup will not roll-back, and has been completed with the exception of starting this service. There are a number of ways to workaround this issue:

After the installation completes (indicating failure), ensure that the Trace Session Manager service is configured to start before any .NET Framework 1.1 application or service which use performance counters, and reboot the machine. Confirm that the Trace Session Manager has started successfully.

Modify the Trace Session Manager configuration file to use the .NET Framework 1.1 when loading. This must be done only when there is no risk that a .NET Framework 1.0 application might subsequently run on the same machine, and publish performance counters. This configuration change should be made to the TraceSessionManager.exe.config file, which is located in the \bin\trace service\ subfolder of the Enterprise Instrumentation installation folder. The two <supportedRuntime ...> elements need to be reversed, as follows, in order to ensure the Trace Session Manager uses the .NET Framework 1.1, when both versions are installed:

In addition to potentially affecting the Trace Session Manager, this issue could affect instrumented applications running against the .NET Framework 1.0. For instance, when an instrumented assembly is installed using installutil.exe, Enterprise Instrumentation registers performance counters for the event sources within the assembly. This will fail if a .NET Framework 1.1 application is currently running and reading or writing performance counter information. The following installutil.exe console output provides an example of this error:

Creating an EnterpriseInstrumentation configuration file for this assembly and its referenced assemblies...

Unhandled Exception: System.TypeInitializationException: The type initializer for "Microsoft.EnterpriseInstrumentation.EventSource" threw an exception. ---> System.TypeInitializationException: The type initializer for "EventSourceCounters"threw an exception. ---> System.InvalidOperationException: Cannot create file mapping.

at System.Diagnostics.FileMapping.Initialize()

at System.Diagnostics.FileMapping..ctor()

at System.Diagnostics.SharedPerformanceCounter.get_FileView()

at System.Diagnostics.SharedPerformanceCounter.ResolveOffset(Int32 offset)

at System.Diagnostics.SharedPerformanceCounter.GetCounter(String categoryName, String counterName, String instanceName)

...

Security: Cannot register Windows Event Log event sources within ASP.NET Web Application under default security settings

By default, ASP.NET Web applications run under the ASPNET account, which does not have sufficient privileges to register a Windows Event Log event source, but does have sufficient privileges to write events to the Application Event Log assuming the event source has already been registered by an administrator.

To ensure events are logged as expected to the Application Event Log, make sure that the local user is a local administrator before executing InstallUtil to install the application's instrumented assemblies, as described further in the Enterprise Instrumentation documentation.

Enterprise Instrumentation automatically registers Event Log event-sources for you as it scans your instrumented assemblies during this installation phase (provided you have implemented a standard ProjectInstaller, as described in the documentation). This means that it is not sufficient to deploy an application to a server with a pre-generated EnterpriseInstrumentation.Config file. You must run installutil against the application's instrumented assemblies in order to ensure the Event Log event-sources are registered.

For more information on the ASPNET account and how it affects application permissions, see the following Microsoft support article: http://support.microsoft.com/default.aspx?scid=kb;en-us;q317012

Security: Cannot fire WMI events from Web Applications using default ASP.NET security settings

By default, ASP.NET Web applications run under the ASPNET account, which does not have sufficient privileges to fire WMI events on Windows XP (prior to SP1) and Windows 2000 (prior to SP3).

To resolve this issue, install SP1 or later for Windows XP Professional, or SP3 or later for Windows 2000 (all editions). To workaround this issue on Windows XP without SP1 or later, or on Windows 2000 without SP3 or later, follow these steps:

Open the Computer Management MMC snap-in

Expand Services and Applications and select WMI Control.

Right-click on WMI Control and select Properties.

In the WMI Control Properties dialog, select the Security tab.

Expand the Root namespace.

Now complete these steps for both the CIMV2 and EnterpriseInstrumentation namespaces:

Select the namespace and click Security.

Click Advanced in the Security dialog.

If the 'aspnet_wp account' name does not appear in the list, click Add, enter '{machine name}\aspnet' and click OK.

If the 'aspnet_wp account' is already in the list, select this entry and click Edit.

Ensure the Apply Onto listbox is set to 'This Namespace and Subnamespaces'.

Ensure the Allow 'Enable Account' and 'Remote Enabled' checkboxes are checked.

Click OK on all dialogs until you are returned to the WMI Control Properties dialog's Security tab.

After completing these steps for both namespaces, click OK to close the dialog. It is recommended that you restart all IIS services (using IISRESET from the command line) to ensure this change takes effect.

For more information on the ASPNET account and how it affects application permissions, see the following Microsoft support article: http://support.microsoft.com/default.aspx?scid=kb;en-us;q317012

Security: Events logged to remote Event Log are sent in clear text over the network

If you define an event sink to log events directly to a the Windows Event Log on a remote machine, the information is sent in clear text over the network. This action can constitute a potential security risk if the network traffic is subject to inspection and you are logging sensitive information. It is recommended that you only log events locally, and allow management tools to securely aggregate and analyze event log events in a single location.

COM+ Application ID is not logged on Windows 2000

On Windows 2000 (regardless of Service Pack), the COM+ Application ID is not available from managed code. Therefore, regardless of whether the COM+ Property Group Filter is enabled for an event source or Request event source, the COM+ Application ID will not be logged. There is no workaround available on Windows 2000.

Duplicate EventSequenceNumber when firing events on multiple threads

If an application raises multiple events simultaneously across multiple threads from the same event source (such as the Application event source), several events may get the same EventSequenceNumber property value, even though each event should get an incrementing sequence number in the order they were raised. This can lead to some uncertainty when attempting to sequence events using this property. This has been identified as a known issue in this release of Enterprise Instrumentation. To workaround this issue, it is recommended that you use the RequestSequenceNumber property for sequencing events, in conjunction with the Request Tracing feature of Enterprise Instrumentation.

Cannot change Windows Event Trace log filename on Windows 2000 SP2 while trace session is enabled

While a trace session is enabled, events continue to be logged to the same log file, even if the log filename is changed in the TraceSessions.Config file. This is a known issue on Windows 2000 with SP2 and earlier.

To workaround this issue, disable the trace session before changing its filename. To resolve this issue and allow the filename to be changed while the session is enabled, install Windows 2000 SP3 or later. To resolve this issue on Windows 2000 SP2, please contact Product Support Services for an installable hotfix. This issue does not exist with Windows XP Professional or Windows Server 2003.

Registering an instrumented assembly may fail if the assembly is not in the current working directory

When running Installutil.exe or an equivalent installer against an instrumented assembly, the current working directory must be the folder containing the instrumented assembly. If installutil.exe is invoked with an explicit reference to an instrumented assembly in another directory, installutil.exe will be unable to load types from the assembly, and will not generate the EnterpriseInstrumentation.config file or register event-sources with the Windows Event Log. To workaround this issue, change the current working directory to the location of the instrumented assembly.

Cannot register Event Schema assembly with duplicate nested class names

There is a known issue with the way an event schema assembly is registered when running InstallUtil.exe against it, resulting in the inability to properly register the Event Schema. This issue occurs when two nested classes with the same name are defined in the Event Schema assembly within the same CLR namespace. It should be valid to define a nested class within an event class with the same name as another nested class within a different event class, as in the following example:

namespace MyNamespace

{

class MyEvent1 : BaseEvent

{

public class MyNestedEvent : BaseEvent

{

}

}

class MyEvent2 : BaseEvent

{

public class MyNestedEvent : BaseEvent

{

}

}

}

While this is valid code, the duplicated MyNestedEvent nested class name will result in a failure when this event schema assembly is registered. To workaround this issue, either change the nested class names to be unique, or separate the events out into separate CLR namespaces. Note that the use of CLR namespaces in an event schema assembly has no affect on the WMI namespace which the events are registered into. This is controlled by the assembly-level InstrumentationSchema attribute.

Trace Sessions may not be synchronized with TraceSessions.Config if service is stopped

The Trace Session Manager service should always be running in order to ensure proper trace session management. If the Trace Session Manager service is stopped and an existing trace session defined in the TraceSessions.Config file is set to enabled or disabled, the trace session may not be enabled or disabled as expected, once the service is re-started. To avoid this issue, only edit the TraceSessions.Config file while the service is running. Once the configuration file is re-saved while the service is running, all trace sessions will be synchronized properly.

RequestEventSource InternalErrors/Sec _total performance counter instance is always zero

Event Sources defined in the instrumented application each get their own performance counter instance, in addition to a _total instance. There is a known issue in Enterprise Instrumentation, in which the _total InternalErrors/Sec counter instance of the EventSources: Software Elements category incorrectly reports the total internal errors per second of both SoftwareElement and Request event sources. As a result, the _total InternalErrors/Sec counter instance of the EventSources: Request category always remains zero. All performance counters for individual event sources are reported correctly.

No events are raised in Windows Event Trace log file when it reaches its maximum size

By default, Windows Event Trace sessions have a log file mode set to "Sequential" within the TraceSessions.Config file, located in the \Bin\Trace Service\ sub-folder of the Enterprise Instrumentation installation folder. If the log file mode of an active Windows Event Trace session is set to "Sequential", no additional events are written to the trace session log file once the file reaches its maximum size. Furthermore, there are no errors and the user is not notified that an event could not be logged.

To work around this problem, set the log file mode to "Circular" and restart the trace session. The log file mode can be set either within the default settings for all trace sessions, or for any individual trace session. This ensures that all events are logged, although the oldest events will be overwritten as per normal circular log file functionality.

Validation errors not always logged for invalid EnterpriseInstrumentation.Config files

Normally, an event is logged to the Application log of the Windows Event Log when an application instrumentation configuration file (EnterpriseInstrumentation.Config) is successfully or unsuccessfully loaded and validated. However, there are specific scenarios where the file will be invalid but will still be successfully loaded. For instance, the following XML fragment describes a filter element:

<filter name="defaultSoftwareElementFilter" description="A default filter for the Software Element event sources." />
    <eventCategoryRef name="All Events">
        <eventSinkRef name="wmiSink" />
        <eventSinkRef name="traceSink" />
        <eventSinkRef name="logSink" />
    </eventCategoryRef>

Note that the filter tag has both the start and end tags thus excluding the eventCategoryRef tag. This does not cause a validation error. Instead, the "defaultSoftwareElementFilter" contains no event categories or event sinks. The "All Events" event category reference is ignored.

Default WMI SDK installation folder is incorrect in Enterprise Instrumentation documentation

The Enterprise Instrumentation documentation includes a walkthrough titled Adding Simple Instrumentation, which describes the default WMI SDK installation folder as %SystemRoot%\System32\WBEM. This is incorrect in newer versions of the WMI SDK, as the default installation folder was later changed to %ProgramFiles%\WMI tools.

Return to top

Parameter	Default Value	Description
INSTALLDIR	%ProgramFiles%\Microsoft Enterprise Instrumentation\	Installation folder for Enterprise Instrumentation.
INSTALL_RUNTIME	1	Installs just the Enterprise Instrumentation core assemblies and Windows Trace Session Manager service.
INSTALL_SCHEMA_SOURCE	1	Installs the source code for the Standard Event Schema, which is used to build custom schemas.
INSTALL_SAMPLES	1	Installs Enterprise Instrumentation code samples.

Filename	Description
EnterpriseInstrumentationSetup.log	Created by the self-extracting EXE as it extracts and runs the Enterprise Instrumentation installer file.
EnterpriseInstrumentationInstall.log	Created by the Enterprise Instrumentation installer file. Contains information on each installation step.
EnterpriseInstrumentationInstallUtil.log	Contains the output of each InstallUtil command, which is used to register and install Enterprise Instrumentation assemblies.