OCSTracer Options and Switches
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 |
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 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 |
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 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 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 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 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 |
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 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 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 |
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