OCSTracer Options and Switches

  • Article

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

This section discusses the options and switches that can be used for each of the commands that can be used with OCSTracer. These commands are listed in OCSTracer. The options are grouped by the command with which they are used.

Export Options and Switches

The Export command exports the .TMF files for one or more Office Communications Server 2007 trace components.

Components Option

Option and Switch Description

/Components:<name(s)>

A comma-separated list, without spaces, of component names for which to export .TMF files. Use OCSTracer List /Filter:All to list valid component names. By default, .TMF files are exported for all components.

OutputFolder Option

Option and Switch Description

/OutputFolder:<txtFilePath>

The path to the folder in which to write the .TMF files. The folder will be created if it does not exist. By default, output goes to the current directory.

Example

The following example exports the .TMF files for the Collaboration and S4 components to the current directory.

OCSTracer Export /Components:Collaboration,S4

Flush Options and Switches

The Flush command flushes any partial buffers for all active Office Communications Server 2007 trace sessions.

There are no options for the Flush command.

Example

The following example flushes all buffers for any active Office Communications Server 2007 trace sessions.

OCSTracer Flush

Format Options and Switches

The Format option formats one or more .ETL files into their text representations.

DeleteEtl Option

Option and Switches Description

/DeleteEtl:Always

Always delete .ETL files if they have been successfully formatted and sent to the the file specified in the /OutputFile option.

/DeleteEtl:IfEmpty

Delete .ETL files if they contain no events. Not implemented.

/DeleteEtl:Never

(Default) Never delete .ETL files. This value comes from OCSTracer.ini.

EndTime Option

Option and Switch Description

/EndTime:MM-DD-YY,HH:MM:SS

An optional end time after which events will not be formatted. By default, all events through the end of the .ETL file are formatted.

LogFile Option

Option and Switch Description

/LogFile:<path>

The path to an existing .ETL log file. Wildcards are permitted. If used, a wildcard must match at least one file.

OutputFile Option

Option and Switch Description

/OutputFile:<txtFilePath>

The name of the file to create that will contain the text representation of the .ETL files specified by the /LogFilePath option(s), sorted in time order.

This option is required by the Format command and is optional with the Stop and Trace commands.

StartTime Option

Option and Switch Description

/StartTime:MM-DD-YY,HH:MM:SS

An optional end time before which events will not be formatted. By default, all events from the beginning of the .ETL file are formatted.

TmfSearchPath Option

Option and Switch Description

/TmfSearchPath:<searchPath>

A semicolon-separated list of paths in which to search for .TMF files if Default.tmx file does not contain the necessary formatting information for a trace event.

UTC Option

Option and Switches Description

/UTC:No

Display times in the formatted text file in local time.

/UTC:Yes

(Default) Display times in the formatted text file in Coordinated Universal Time (UTC). This value comes from OCSTracer.ini.

View Option

Option and Switch Description

/View

If the file specified by the /OutputFile option is successfully created, open the file for editing.

For this option to be used, the /OutputFile option must be present.

Examples

The following command formats the .ETL file for the S4 component, and produces a text file named S4.txt.

   OCSTracer Format /LogFilePath:S4.etl /OutPutFile:S4.txt

The following command formats the .ETL file for the Collaboration component, and produces a text file named Collaboration.txt.

   OCSTracer Format /LogFilePath:Collaboration.etl /OutPutFile:Collaboration.txt

List Options and Switches

The List command displays Office Communcations Server 2007 trace components. Option switches used with the List command control the components that are shown and the level of detail for each.

Detail Option

Option and Switches Description

/Detail:All

Show all information about a component.

/Detail:Summary

(Default) Show only the name, provider GUID, and default level and flags for a component.

Filter Option

Option and Switches Description

/Filter:Active

(Default) Restrict the list to only those components with active trace sessions.

/Filter:All

Show all Office Communications Server 2007 components.

/Filter:Available

Restrict the list to only those components that are installed on the computer.

/Filter:<componentName>

Restrict to a specific component.

Example

The following example lists all components that are installed on the computer, and provides all details about those components.

OcsTracer List /Filter:Available /Detail:All

Start Options and Switches

The Start command starts tracing for one or more Office Communications Server 2007 trace components. Option switches used with the Start command can be specified to override defaults from OCSTracer.ini or Default.tmx.

BufferSize Option

Option and Switch Description

/BufferSize:<n>

The size of each buffer, in KB. Buffers are allocated from non-paged pool, so care should be taken not to make buffers too large.

The default value is 64 (KB) and comes from OCSTracer.ini.

Component Option

Option and Switch Description

/Component:<name,level,flags,...>

The component name, trace level for the component, and flags for the component. Use OCSTracer List /Filter:Available to display the names of available components.

If specified, level is a constant that is defined by the component or a decimal number. If not specified, the default level for the component is used. For more information, see Component Levels and Flags.

If specified, flags is one or more comma-separated flag constants that are defined by the component, or a hexadecimal number that represents a combination of flag values. If not specified, the default flags for the component are used. For more information, see Component Levels and Flags.

Use OCSTracer List /Filter:<name> /Detail:All to get a list of levels and flags that are valid for a component, as well as the default level and flags for the component.

LogFileFolder Option

Option and Switch Description

/LogFileFolder:<path>

The directory in which to write the .ETL file(s) that are created during the tracing session. The path will be created if it does not exist.

By default .ETL files are written to the %WINDIR%\Tracing directory. This setting comes from the [Defaults] section of OCSTracer.ini.

LogFileMode Option

Option and Switches Description

/LogFileMode:Circular, <n>

(Default) Write trace events to a file until it reaches its maximum size, and then start writing trace events at the beginning of the file. The maximum file size is n MB. The default mode is Circular and the default file size is 20 MB. These values come from OCSTracer.ini.

/LogFileMode:NewFile, <n>

Write trace events to a file until it reaches its maximum size, and then create a new log file in which to continue writing trace events. The new log file contains a %d placeholder (see the note that follows this table) that is incremented by one each time a new log file is created. The maximum file size is n MB.

/LogFileMode:Sequential, <n>

Write trace events to a file until it reaches its maximum size, and then stop logging. The maximum file size is n MB.

Note

Log file names are always of the form <componentName>.ETL or <componentName>_%d.ETL for the NewFile option where %d starts at 1 and is incremented by 1 for each new log file created. For more information about controling the log file name, see the LogFileName option.

Important

The drive that contains the log file folder must have at least 200 MB of free space not including the space needed for the log file itself.

LogFileName Option

Option and Switch Description

/LogFileName:<nameTemplate>

The template to use for log file names. The default name for log files is <componentName>.ETL or <componentName>_%d.ETL, with the latter format used for the /LogFileMode:NewFile,n option. Use this option to override the default name format. If <nameTemplate> includes an asterisk, it will be replaced at run time by <componentName>. If <nameTemplate> does not include an asterisk, it will be treated as a prefix string with which to prefix each log file name.

The default is * and comes from the [Defaults] section of OCSTracer.ini.

LogFilePath Option

Option and Switch Description

/LogFilePath:<path>

The path to the output .ETL log file. It must include %d in the path if /LogFileMode:NewFile is specified.

This option overrides the LogFileFolder and LogFileName options.

MaxBuffers Option

Option and Switch Description

/MaxBuffers:<n>

The maximum number of buffers ever to allocate for the trace session. The default value is 40 and comes from OCSTracer.ini.

MinBuffers Option

Option and Switch Description

/MinBuffers:<n>

The minimum number of buffers ever to allocate for the trace session. The default value is 20 and comes from OCSTracer.ini.

Examples

The following example starts a tracing session on the S4 and Collaboration components, using the default levels and flags for these components.

OCSTracer Start /Component:S4 /Component:Collaboration

The following example starts a tracing session on the S4 component, and sets the component level to TL_WARN. Only fatal errors, errors, and warnings will be logged.

OCSTracer start /Component:S4,TL_WARN

Stop Options and Switches

The Stop command stops any active Office Communications Server 2007 trace sessions specified by the options. If no options are specified, this command flushes all active OCS trace sessions.

Component Option

Option and Switch Description

/Component:<name>

The name of an Office Communications Server 2007 trace component with an active trace session. Use OCSTracer List /Filter:Active to list the names of components with active trace sessions.

If multiple components are specified, they should be separated by commas, with no spaces between the components.

By default, if no Component options are specified, all Office Communications Server 2007 components are assumed to be active.

DeleteEtl Option

Option and Switches Description

/DeleteEtl:Always

Always delete .ETL files if they have been successfully formatted and sent to the the file specified in the OutputFile option.:

/DeleteEtl:IfEmpty

Delete .ETL files if they contain no events. Not implemented.

/DeleteEtl:Never

(Default) Never delete .ETL files.

OutputFile Option

Option and Switch Description

/OutputFile:<txtFilePath>

The name of the file to create that will contain the text representation of the .ETL files specified by the LogFilePath option(s), sorted in time order.

This option is optional with the Stop and Trace commands, and is required by the Format command.

TmfSearchPath Option

Option and Switch Description

/TmfSearchPath:<searchPath>

A semicolon-separated list of paths in which to search for .TMF files if Default.tmx file does not contain the necessary formatting information for a trace event.

UTC Option

Option and Switches Description

/UTC:No

Display times in the formatted text file in local time.

/UTC:Yes

(Default) Display times in the formatted text file in Coordinated Universal Time (UTC). This value comes from OCSTracer.ini.

View Option

Option and Switch Description

/View

If the file specified by the OutputFile option is successfully created, open the file for editing.

For this option to be used, the OutputFile option must be present.

Example

The following example stops tracing on the Collaboration component.

OcsTracer Stop /Component:Collaboration

Trace Options and Switches

The Trace command starts tracing for one or more Office Communications Server 2007 trace components with real time formatting of trace events to the console window until the user presses CTRL + C. The trace sessions are then flushed and stopped.

BufferSize Option

Option and Switch Description

/BufferSize:<n>

The size of each buffer, in KB. Buffers are allocated from non-paged pool, so care should be taken not to make buffers too large.

The default value is 64 (KB) and comes from OCSTracer.ini.

Component Option

Option and Switch Description

/Component:<name,level,flags...>

The component name, trace level for the component, and flags for the component. Use OCSTracer List to display available component names.

If specified, level is a constant that is defined by the component or a decimal number. If not specified, the default level for the component is used. For more information, see Component Levels and Flags.

If specified, flags is one or more comma-separated flag constants that are defined by the component, or a hexadecimal number that represents a combination of flag values. If not specified, the default flags for the component are used. For more information, see Component Levels and Flags.

Use OCSTracer List /Filter:<name> /Detail:All to get a list of levels and flags that are valid for a component, as well as the default level and flags for the component.

DeleteEtl Option

Option and Switches Description

/DeleteEtl:Always

Always delete .ETL files if they have been successfully formatted and sent to the the file specified in the OutputFile option.:

/DeleteEtl:IfEmpty

Delete .ETL files if they contain no events. Not implemented.

/DeleteEtl:Never

(Default) Never delete .ETL files.

DisplayOnly Option

Option and Switch Description

/DisplayOnly

Send output only to the console and do not create an .ETL file. This option cannot be specified with the OutputFile option.

FlushTimer Option

Option and Switch Description

/FlushTimer:<n>

Flush the trace buffers every n seconds. The tracing mechanism always flushes full buffers, so using this option can result is wasted disk space when the DisplayOnly option is not used. In this case, .ETL files will grow by multiples of BufferSize KB each time the buffers are flushed. If the rate at which events occur is low, this can result in much wasted disk space. For this reason, if you set FlushTimer to a small value, you should also choose DisplayOnly.

The default value for this option is 10 seconds and comes from OCSTracer.ini. You should not set this option to a smaller value.

LogFileFolder Option

Option and Switch Description

/LogFileFolder:<path>

The directory in which to write the .ETL file(s) that are created during the tracing session. The path will be created if it does not exist.

By default .ETL files are written to %WINDIR%\Tracing. This setting comes from the [Defaults] section of OCSTracer.ini.

LogFileMode Option

Option and Switches Description

/LogFileMode:Circular, <n>

(Default) Write trace events to a file until it reaches its maximum size, and then start writing trace events at the beginning of the file. The maximum file size is n MB. The default mode is Circular and the default file size is 20 MB. These values come from OCSTracer.ini.

/LogFileMode:NewFile, <n>

Write trace events to a file until it reaches its maximum size, and then create a new log file in which to continue writing trace events. The new log file contains a %d placeholder that is incremented by one each time a new log file is created. The maximum file size is n MB.

/LogFileMode:Sequential, <n>

Write trace events to a file until it reaches its maximum size, and then stop logging. The maximum file size is n MB.

Note

Log file names are always of the form <componentName>.ETL or <componentName>_%d.ETL for the NewFile option where %d starts at 1 and is incremented by 1 for each new log file created. For more information about controling the log file name, see the LogFileName option.

Important

????The drive that contains the log file folder must have at least 200 MB of free space not including the space needed for the log file itself.

LogFileName Option

Option and Switch Description

/LogFileName:<nameTemplate>

The template to use for log file names. The default name for log files is <componentName>.ETL or <componentName>_%d.ETL, with the latter format used for the /LogFileMode:NewFile,n option. Use this option to override the default name format. If <nameTemplate> includes an asterisk, it will be replaced at run time by <componentName>. If <nameTemplate> does not include an asterisk, it will be treated as a prefix string with which to prefix each log file name.

The default is * and comes from the [Defaults] section of OCSTracer.ini.

LogFilePath Option

Option and Switch Description

/LogFilePath:<path>

The path to the output .ETL log file. It must include %d in the path if LogFileMode:NewFile is specified.

This option overrides the LogFileFolder and LogFileName options.

MaxBuffers Option

Option and Switch Description

/MaxBuffers:<n>

The maximum number of buffers ever to allocate for the trace session. The default value is 40 and comes from OCSTracer.ini.

MinBuffers Option

Option and Switch Description

/MinBuffers:<n>

The minimum number of buffers ever to allocate for the trace session. The default value is 20 and comes from OCSTracer.ini.

OutputFile Option

Option and Switch Description

/OutputFile:<txtFilePath>

The name of the file to create that will contain the text representation of the .ETL files specified by the LogFilePath option(s), sorted in time order.

This option is optional with the Stop and Trace commands, and is required by the Format command.

TmfSearchPath Option

Option and Switch Description

/TmfSearchPath:<searchPath>

A semicolon-separated list of paths in which to search for .TMF files if Default.tmx file does not contain the necessary formatting information for a trace event.

UTC Option

Option and Switches Description

/UTC:No

Display times in the formatted text file in local time.

/UTC:Yes

(Default) Display times in the formatted text file in Coordinated Universal Time (UTC). This value comes from OCSTracer.ini.

View Option

Option and Switch Description

/View

If the file specified by the OutputFile option is successfully created, open the file for editing.

For this option to be used, the OutputFile option must be present.

Example

The following command starts a tracing session on the Collaboration component, creating a new file for the trace data whenever the file reaches 30 KB in size. The time used for event data is local time.

OcsTracer Trace /Component:Collaboration /LogFileMode:NewFile,30 /UTC:No

Update Options and Switches

The Update command updates levels and flags for active Office Communication Server 2007 trace sessions. If the update is successful, changes are effective immediately.

Component Option

Option and Switch Description

/Component:<name,level,flags,...>

The component name, trace level for the component, and flags for the component. Use OCSTracer List /Filter:Available to display the names of available components.

If specified, level is a constant that is defined by the component or a decimal number. If not specified, the default level for the component is used. For more information, see Component Levels and Flags.

If specified, flags is one or more comma-separated flag constants that are defined by the component, or a hexadecimal number that represents a combination of flag values. If not specified, the default flags for the component are used. For more information, see Component Levels and Flags.

Use OCSTracer List /Filter:<name> /Detail:All to get a list of levels and flags that are valid for a component, as well as the default level and flags for the component.

Example

The following command updates the level and flags for the S4 component to TL_INFO (fatal error, error, warning, and informational events will be logged) and TF_PROTOCOL and TF_CONNECTION ( ).

OcsTracer Update /Component:S4,TL_INFO,TF_PROTOCOL,TF_CONNECTION