Downloads |
 Feedback
|
Table Of Contents
Supported Standards, MIBs, and RFCs
Configuring the Event Trace Size
Configuring the Event Trace Message File
Verifying Event Trace Operation
Configuring Event Tracing for One Component Example
Configuring Event Tracing for Multiple Components Example
Configuring the Event Trace Size Example
Configuring the Event Trace Message File Example
monitor event-trace dump-traces
Event Tracer
Feature History
12.0(18)S
This feature was introduced.
12.2(8)T
This feature was integrated into Cisco IOS Release 12.2(8)T.
This document describes the Event Tracer feature. It includes the following sections:
•
Supported Standards, MIBs, and RFCs
Feature Overview
The Event Tracer feature provides a binary trace facility for troubleshooting Cisco IOS software. This feature gives Cisco service representatives additional insight into the operation of the Cisco IOS software and can be useful in helping to diagnose problems in the unlikely event of an operating system malfunction or, in the case of redundant systems, route processor switchover.
Note
Event tracing works by reading informational messages from specific Cisco IOS software subsystem components that have been preprogrammed to work with event tracing, and by logging messages from those components into system memory. Trace messages stored in memory can be displayed on the screen or saved to a file for later analysis.
By default, trace messages saved to a file are saved in binary format without applying additional processing or formatting. Saving messages in binary format allows event tracing to collect informational messages faster and for a longer time prior to a system malfunction or processor switchover. Optionally, event trace messages can be saved in ASCII format for additional file processing.
The Event Tracer feature can support multiple traces simultaneously. To do this, the feature assigns a unique ID number to each instance of a trace. This way, all messages associated with a single instance of a trace get the same ID number. Event tracing also applies a timestamp to each trace message, which aids in identifying the message sequence.
The number of trace messages stored in memory for each instance of a trace is configurable up to 65536 entries. As the number of trace messages stored in memory approaches the configured limit, the oldest entries are overwritten with new messages, which continues until the event trace is terminated.
Event tracing can be configured in "one-shot" mode. This is where the current contents of memory for a specified component are discarded and a new trace begins. New trace messages are collected until the message limit is reached, at which point the trace is automatically terminated.
Benefits
Event tracing has a number of benefits to aid in system diagnosis:
Binary Data Format
Event information is saved in binary format without applying any formatting or processing of the information. This results in capturing event information more quickly and for a longer period of time in the moments leading up to a system malfunction or processor switchover. The ability to gather information quickly is also helpful in tracing events that generate a lot of data quickly.
File Storage
Information gathered by the event tracing can be written to a file where it can be saved for further analysis.
Optional ASCII Data Format
Event tracing provides an optional command to save the information in ASCII format.
Multiple Trace Capability
Event tracing can be configured to trace one or more components of the Cisco IOS software simultaneously, depending on the software version running on the networking device.
Restrictions
Event tracing provides a mechanism to help TAC representatives assist Cisco customers in diagnosing certain Cisco IOS software functions. Configuration of this feature on a networking device is recommended only under the direction of a TAC representative. This feature does not produce customer readable data; therefore, it requires the assistance of a TAC representative for proper configuration and analysis.
Supported Platforms
•
Platform Support Through Feature Navigator
Cisco IOS software is packaged in feature sets that support specific platforms. To get updated information regarding platform support for this feature, access Feature Navigator. Feature Navigator dynamically updates the list of supported platforms as new platform support is added for the feature.
Feature Navigator is a web-based tool that enables you to quickly determine which Cisco IOS software images support a specific set of features and which features are supported in a specific Cisco IOS image.
To access Feature Navigator, you must have an account on Cisco.com. If you have forgotten or lost your account information, send a blank e-mail to cco-locksmith@cisco.com. An automatic check will verify that your e-mail address is registered with Cisco.com. If successful, account details with a new random password will be e-mailed to you. If you want to establish an account on Cisco.com, go to http://www.cisco.com/register and follow the directions to establish an account.
Feature Navigator is updated when major Cisco IOS software releases and technology releases occur. As of May 2001, Feature Navigator supports M, T, E, S, and ST releases. You can access Feature Navigator at the following URL:
http://www.cisco.com/go/fn
Supported Standards, MIBs, and RFCs
Standards
None
MIBs
None
To obtain lists of supported MIBs by platform and Cisco IOS release, and to download MIB modules, go to the Cisco MIB website on Cisco.com at the following URL:
http://www.cisco.com/public/sw-center/netmgmt/cmtk/mibs.shtml
RFCs
None
Prerequisites
The list of software components that support event tracing can vary from one Cisco IOS software image to another. And in many cases, depending on the software component, the event tracing functionality is enabled or disabled by default. Knowing what software components support event tracing and knowing the existing state of the component configuration is important in deciding whether to configure event tracing.
To determine whether event tracing has been enabled or disabled by default for a specific component, follow these steps:
Step 1
Router(config)# monitor event-trace ?Step 2
Router# show monitor event-trace component allStep 3
Router# show monitor event-trace component parametersThis information can help you in determining your configuration options.
Configuration Tasks
See the following sections for configuration tasks for the Event Tracer feature. Each task in the list is identified as either required or optional.
•
•
•
•
Follow the instructions in the "Prerequisites" section prior to configuring this feature. If the default configuration information meets your site requirements, no further configuration may be necessary, and you may proceed to the section "Verifying Event Trace Operation."
Configuring Event Tracing
In most cases where Cisco IOS software components support event tracing, the feature is configured by default. For some software components, event tracing is enabled, while for other components event tracing might be disabled. In some cases, a TAC representative may want to change the default settings.
To enable or disable event tracing, use the following commands in global configuration mode:
Configuring the Event Trace Size
In most cases where Cisco IOS software components support event tracing, the feature is configured by default. In some cases, such as directed by a TAC representative, you might need to change the size parameter to allow for writing more or fewer trace messages to memory.
To configure the message size parameter, use the following command in global configuration mode:
Configuring the Event Trace Message File
To configure the file location where you want to save trace messages, use the following command in global configuration mode:
Verifying Event Trace Operation
Note
Step 1
Router# show running-configStep 2
In the following example, event tracing has been enabled for the IPC component. Notice that each trace message is numbered sequentially (for example, 3667) and is followed by a the timestamp (derived from the device uptime). Following the timestamp is the component specific message data.
Router# show monitor event-trace ipc3667: 6840.016:Message type:3 Data=01234567893668: 6840.016:Message type:4 Data=01234567893669: 6841.016:Message type:5 Data=01234567893670: 6841.016:Message type:6 Data=0123456To view trace information for all components enabled for event tracing, enter the show monitor event-trace all-traces command. In this example, separate output is provided for each event and message numbers are interleaved between the events.
Router# show monitor event-trace all-tracesTest1 event trace:3667: 6840.016:Message type:3 Data=01234567893669: 6841.016:Message type:4 Data=01234567893671: 6842.016:Message type:5 Data=01234567893673: 6843.016:Message type:6 Data=0123456789Test2 event trace:3668: 6840.016:Message type:3 Data=01234567893670: 6841.016:Message type:4 Data=01234567893672: 6842.016:Message type:5 Data=01234567893674: 6843.016:Message type:6 Data=0123456789Step 3
Router# monitor event-trace ipc dump
Troubleshooting Tips
Event Tracing Does Not Appear to Be Configured in the Running Configuration
Depending on the software component, event tracing is enabled or disabled by default. In either case, the default condition will not be reflected in output of the show running-config command; however, changing any of the settings for a command that has been enabled or disabled by default will cause those changes to show up in the output of the show running-config command. Changing the condition of the component back to its default state (enabled or disabled), will cause the entry not to appear in the configuration file.
Show Command Output Is Reporting "One or More Entries Lost "
The trace function is not locked while information is being displayed to the console, which means that new trace messages can accumulate in memory. If entries accumulate faster than they can be displayed, some messages can be lost; however, messages will continue to display on the console. If the number of lost messages is excessive, the show command will stop displaying messages.
Show Command Output Terminates Unexpectedly
The trace function is not locked while information is being displayed to the console, which means that new trace messages can accumulate in memory. If entries accumulate faster than they can be displayed, some messages can be lost. If the number of lost messages is excessive, the show command will stop displaying messages.
Show Command Output Is Reporting That "Tracing Currently Disabled, from EXEC Command"
The Cisco IOS software allows for the subsystem components to define whether support for event tracing is enabled or disabled at boot time. Event tracing allows users to enable or disable event tracing in two ways: using the monitor event-trace (EXEC) command in privileged EXEC mode or using the monitor event-trace (global) command in global configuration mode. To enable event tracing again in this case, you would enter the enable form of either of these commands.
Show Command Output Is Reporting That "Tracing Currently Disabled, from Config Mode"
The Cisco IOS software allows for the subsystem components to define whether support for event tracing is enabled or disabled at boot time. Event tracing allows users to disable event tracing in two ways: using the monitor event-trace disable (EXEC) command in privileged EXEC mode or using the monitor event-trace disable (global) command in global configuration mode. To enable event tracing again in this case, you would enter the enable form of either of these commands.
Event Trace Messages Are Not Being Saved in ASCII Format
By default, the monitor event-trace component dump and monitor event-trace dump-traces commands save trace messages in binary format. If you want to save trace messages in ASCII format, use either the monitor event-trace component dump pretty command to write the trace messages for a single event, or the monitor event-trace dump-traces pretty command to write trace messages for all event traces currently enabled on the networking device.
Configuration Examples
This section provides the following configuration examples:
•
•
•
•
Configuring Event Tracing for One Component Example
In the following example, the networking device has been configured to trace IPC component events:
monitor event-trace ipc enableConfiguring Event Tracing for Multiple Components Example
In the following example, the networking device has been configured to trace IPC and MBUS component events:
monitor event-trace ipc enablemonitor event-trace mbus enableConfiguring the Event Trace Size Example
In the following example, the size of the IPC trace is set to 4096 entries while the size of the MBUS trace is set to 8192 entries:
monitor event-trace ipc size 4096monitor event-trace mbus size 8192Configuring the Event Trace Message File Example
The following example identifies the files in which to write trace messages. In this example, event tracing has been enabled for both the IPC and MBUS components, the IPC trace messages are written to the ipcdump file in flash memory, while the MBUS trace message files are written to the mbusdump file on the TFTP server.
monitor event-trace ipc dump-file slot0:ipcdumpmonitor event-trace mbus dump-file TFTP:mbusdumpCommand Reference
This section documents new commands. All other commands used with this feature are documented in the Cisco IOS Release 12.0 command reference publications.
New Commands
•
monitor event-trace (EXEC)
To control the event trace function for a specified Cisco IOS software subsystem component, use the monitor event-trace (EXEC) command in privileged EXEC mode.
monitor event-trace component {clear | disable | dump [pretty] | enable | one-shot}
Syntax Description
Command Modes
Privileged EXEC
Command History
12.0(18)S
This command was introduced.
12.2(8)T
This command was integrated into Cisco IOS Release 12.2(8)T.
Usage Guidelines
Use the monitor event-trace (EXEC) command to control what, when, and how event trace data is collected. Use this command after you have configured the event trace functionality on the networking device using the monitor event-trace (global) command.
Note
The Cisco IOS software allows for the subsystem components to define whether support for event tracing is enabled or disabled at boot time. You can enable or disable event tracing in two ways: using the monitor event-trace (EXEC) command in privileged EXEC mode or using the monitor event-trace (global) command in global configuration mode. To enable event tracing again, you would enter the enable form of either of these commands.
To determine whether a subsystem has enabled or disabled event tracing, use the monitor event-trace ? command to get a list of software components that support event tracing. To determine whether event tracing is enabled by default for the subsystem, use the show monitor event-trace command to view trace messages.
Use the show monitor event-trace command to display trace messages.
Use the monitor event-trace component dump command to save trace message information for a single event. By default, trace information is saved in binary format. If you want to save trace messages in ASCII format, possibly for additional application processing, use the monitor event-trace component dump pretty command.
To write the trace messages for all events currently enabled on a networking device to a file, enter the monitor event-trace dump-traces command.
To configure the file where you want to save trace information, use the monitor event-trace (global) command.
Examples
The following example shows the privileged EXEC commands to stop event tracing, clear the current contents of memory, and re-enable the trace function for the IPC component. This example assumes that the tracing function is configured and enabled on the networking device.
Router# monitor event-trace ipc disableRouter# monitor event-trace ipc clearRouter# monitor event-trace ipc enableThe following example shows how the monitor event-trace one-shot command accomplishes the same function as the previous example except in one command. In this example, once the size of the trace message file has been exceeded, the trace is terminated.
Router# monitor event-trace ipc one-shotThe following example shows the command for writing trace messages for an event in binary format. In this example, the trace messages for the IPC component are written to a file.
Router# monitor event-trace ipc dumpThe following example shows the command for writing trace messages for an event in ASCII format. In this example, the trace messages for the MBUS component are written to a file.
Router# monitor event-trace mbus dump prettyRelated Commands
monitor event-trace (global)
To configure event tracing for a specified Cisco IOS software subsystem component, use the monitor event-trace (global) command in global configuration mode. To change the default setting to enable or disable event tracing, refer to the "Usage Guidelines" section for this command.
monitor event-trace component {disable | dump-file filename | enable | size number}
Syntax Description
Defaults
Enabled or disabled depending on the software component.
Command Modes
Global configuration
Command History
12.0(18)S
This command was introduced.
12.2(8)T
This command was integrated into Cisco IOS Release 12.2(8)T.
Usage Guidelines
Use the monitor event-trace (global) command to enable or disable event tracing and to configure event trace parameters for Cisco IOS software subsystem components.
Note
The Cisco IOS software allows the subsystem components to define whether support for event tracing is enabled or disabled by default. The command interface for event tracing allows users to change the default two ways: using the monitor event-trace (EXEC) command in privileged EXEC mode or using the monitor event-trace (global) command in global configuration mode.
Additionally, default settings do not show up in the configuration file. If the subsystem software enables event tracing by default, the monitor event-trace component enable command will not show up in the configuration file of the networking device; however, disabling event tracing that has been enabled by default by the subsystem will create a line in the configuration file.
Note
To determine whether a subsystem has enabled or disabled event tracing, use the monitor event-trace ? command to get a list of software components that support event tracing.
To determine whether event tracing is enabled by default for the subsystem, use the show monitor event-trace command to view trace messages.
Examples
The following example shows how to enable event tracing for the IPC subsystem component in Cisco IOS software and configure the size to 4096 messages. The trace messages file is set to ipc-dump in slot0 (flash memory).
monitor event-trace ipc enablemonitor event-trace ipc dump-file slot0:ipc-dumpmonitor event-trace ipc size 4096Related Commands
monitor event-trace dump-traces
To save trace messages for all event traces currently enabled on the networking device, use the monitor event-trace dump-traces command in privileged EXEC mode.
monitor event-trace dump-traces [pretty]
Syntax Description
Command Modes
Privileged EXEC
Command History
12.0(18)S
This command was introduced.
12.2(8)T
This command was integrated into Cisco IOS Release 12.2(8)T.
Usage Guidelines
Use the monitor event-trace dump-traces command to save trace message information for all event traces currently enabled on a networking device. By default, trace information is saved in binary format. If you want to save trace messages in ASCII format, possibly for additional application processing, use the monitor event-trace dump-traces pretty command.
To write the trace messages for an individual trace event to a file, enter the monitor event-trace (EXEC) command.
To configure the file where you want to save messages, use the monitor event-trace (global) command.
Examples
The following example shows how to save the trace messages in binary format for all event traces enabled on the networking device.
monitor event-trace dump-tracesThe following example shows how to save the trace messages in ASCII format for all event traces enabled on the networking device.
monitor event-trace dump-traces prettyRelated Commands
show monitor event-trace
To display event trace messages for Cisco IOS software subsystem components, use the show monitor event-trace command in privileged EXEC mode.
show monitor event-trace [all-traces] [component {all | back time | clock time | from-boot seconds | latest | parameters}]
Syntax Description
Command Modes
Privileged EXEC
Command History
12.0(18)S
This command was introduced.
12.2(8)T
This feature was integrated into Cisco IOS Release 12.2(8)T.
Usage Guidelines
Use the show monitor event-trace command to display trace message information.
The trace function is not locked while information is being displayed to the console, which means that new trace messages can accumulate in memory. If entries accumulate faster than they can be displayed, some messages can be lost. If this happens, the show monitor event-trace command will generate a message indicating that some messages might be lost; however, messages will continue to display on the console. If the number of lost messages is excessive, the show monitor event-trace command will stop displaying messages.
Examples
The following sample output illustrates the show monitor event-trace component command output for the IPC component. Notice that each trace message is numbered and is followed by a the timestamp (derived from the device uptime). Following the timestamp is the component-specific message data.
Router# show monitor event-trace ipc3667: 6840.016:Message type:3 Data=01234567893668: 6840.016:Message type:4 Data=01234567893669: 6841.016:Message type:5 Data=01234567893670: 6841.016:Message type:6 Data=0123456To view trace information for all components configured for event tracing on the networking device, enter the show monitor event-trace all-traces command. In this example, separate output is provided for each event and message numbers are interleaved between the events.
Router# show monitor event-trace all-tracesTest1 event trace:3667: 6840.016:Message type:3 Data=01234567893669: 6841.016:Message type:4 Data=01234567893671: 6842.016:Message type:5 Data=01234567893673: 6843.016:Message type:6 Data=0123456789Test2 event trace:3668: 6840.016:Message type:3 Data=01234567893670: 6841.016:Message type:4 Data=01234567893672: 6842.016:Message type:5 Data=01234567893674: 6843.016:Message type:6 Data=0123456789Related Commands
