Oracle Net8 Administrator's Guide Release 8.0 A58230-01 |
|
Net8 provides methods for understanding and resolving network problems through the use of log and trace files. These files keep track of the interaction between network components as errors occur. Evaluating this information will help you to diagnose and troubleshoot even the most complex network problems.
This chapter describes common network errors and outlines procedures for resolving them. It also describes methods for logging and tracing error information to diagnose and troubleshoot more complex network problems. This chapter contains the following sections:
Due to the complexity of network communications, network errors may originate from a variety of sources, for a variety of reasons. If an error occurs, applications such as SQL*Plus and SQL*Forms, which depend on network services from Net8, will normally generate an error message.
A list of the most common network error messages follows:
Oracle Network Products provide detailed information about the source and context of problems as they arise. This information is generated and stored in log and trace files. The process of logging and tracing error information will help you to diagnose and resolve network problems.
Logging refers to the process by which network components note and append error-specific information to a log file. Each Net8 component produces its own log file to describe the state of the software at various communication layers as an error occurs. To ensure that all errors are recorded, logging cannot be disabled on clients or Names Servers. Furthermore, only an administrator may replace or erase log files. The log file for the listener also includes Audit Trail information about every client connection request, as well as most listener control commands.
Log files provide information contained in an error stack. An error stack refers to the information that is produced by each layer in an Oracle communications stack as the result of a network error.
Figure 10-1 depicts the relationship among Oracle network products as they might appear in an error stack:
The layers in Figure 8-1 are as follows:
Your network may or may not include all of these components.
As an example, suppose that a user of a client application tries to establish a connection with a database server using Net8 and TCP/IP, and the user enters:
sqlplus scott/tiger@hrserver.world
The SQL*Plus banner is displayed on the screen, and the following error is displayed:
ORA-12203: TNS:Unable to connect to destination
This message indicates that the connection to the server failed because the database could not be contacted. Although the application displays only a one-line error message, an error stack that is much more informative is recorded in the log file by the network layer. On the client-side, a log file called SQLNET.LOG, contains an error stack corresponding to the ORA-12203 error as follows:
***********************************************************
Fatal OSN connect error 12203, connecting to: (DESCRIPTION=(CONNECT_DATA=(SID=trace)(CID=(PROGRAM=) (HOST=lala)(USER=sviavant)))(ADDRESS_LIST=(ADDRESS= (PROTOCOL=ipc)(KEY=trace))(ADDRESS=(PROTOCOL=tcp) (HOST=lala)(PORT=1521)))) VERSION INFORMATION: TNS for SunOS: Oracle Bequeath NT Protocol Adapter for SunOS: Unix Domain Socket IPC NT Protocol Adaptor for SunOS: TCP/IP NT Protocol Adapter for SunOS: Tracing to file: /home/sviavant/trace_admin.trc Tns error struct: nr err code: 12203 TNS-12203: TNS:unable to connect to destination ns main err code: 12541 TNS-12541: TNS:no listener ns secondary err code: 12560 nt main err code: 511 TNS-00511: No listener nt secondary err code: 61 nt OS err code: 0
Each Net8 component produces its own log file. Table 10-2 provides the default filenames and a description of the information they contain:
Parameters that control logging, including the type and amount of information logged, as well as the location where the files are stored, are set in the configuration file of each network component as follows:
Although there are operating system specific default names and locations for the log files, you can specify alternative names and locations if you wish. Each component may have log parameters that determine the following:
To change log file names, edit the following parameter in the appropriate component configuration file:
LOG_FILE_component = string
For example, the following parameter in your listener configuration file would send listener log output to a file called TEST.LOG on the server machine.
LOG_FILE_LISTENER = TEST
Note::On most operating systems, the .log suffix is automatically appended to the log filename. For a full description of configuration parameters, refer to Appendix B, "Configuration Parameters". Some platforms have restrictions on the properties of a filename. See your Oracle operating system-specific documentation for platform-specific restrictions.
To change the location of where the log file for each component is stored, edit the following parameter in the appropriate component configuration file:
LOG_DIRECTORY_component = valid directory
Examples are specific to different operating systems. An example on UNIX might be:
LOG_DIRECTORY_LISTENER = /tmp/log
Some platforms have restrictions on the properties of a directory. For more information about platform-specific restrictions, refer to your Oracle operating system-specific documentation.
To use a log file to diagnose a network error:
The listener log file contains Audit Trail information that allows you to gather and analyze network usage statistics, as well as information indicating the following:
Note that you cannot turn this feature off.
The Audit Trail formats text into the following fields: Timestamp, Connect Data, [Protocol Info], event, [sid], return Code. Properties of the Audit Trail are as follows:
Typical output to the log file upon a reload request is as follows:
10-MAY-96 14:16:21 *(CONNECT_DATA=(CID=(PROGRAM=)(HOST=roach)(USER=reltest) (COMMAND=reload)(ARGUMENTS=64)(SERVICE=LISTENER) (VERSION=36704256))*reload*0
Typical output to the log file upon a connection request is as follows:
10-MAY-96 14:16:21*(CONNECT_DATA=(SID=reltest)(CID= (PROGRAM=C:\ORAWIN\BIN\PLUS31.EXE) (HOST=WINDOWSPC)(USER=CCLOW))*(ADDRESS=(PROTOCOL=tcp) (HOST=144.25.23.246)(PORT=3366)) *establish*reltest*0
Notice that the user ID is recorded as well as the platform, protocol, and software used to make the connection.
You can use Audit Trail information to view trends and user activity by first storing it in a table and then collating it into a report format. To import the data into a table, use an import utility such as SQL*Loader.
The trace facility produces a detailed sequence of statements that describe network events as they are executed. "Tracing" an operation allows you to obtain more information on the internal operations of the components of Net8 than is provided in a log file. This information is output to files that can be evaluated to identify the events that led to an error.
CAUTION: The trace facility uses a large amount of disk space and may have a significant impact upon system performance. Therefore, you should enable tracing only when necessary |
Components that can be traced using the trace facility are:
To enable tracing as well as to set specific trace parameters, you may use either:
To set tracing parameters using component configuration files:
TRACE_LEVEL_component name=(OFF/USER/ADMIN/SUPPORT) TRACE_DIRECTORY_component name=directory name
To set trace parameters using component control utilities:
Oracle Trace is a new tool that can be used with Oracle Enterprise Manager or stand alone enabling you to format and correlate data from two different trace files. Use Oracle Trace in situations where you will need to compare and/or correlate the trace information produced individually by Net8 and the server, or by Net8 as it interacts between the client and server. For more information on enabling Oracle Trace, refer to the Net8 Release Notes.
Evaluating trace files either manually, or by using the Trace Assistant tool will help you to diagnose and troubleshoot network problems by giving you a better understanding of the following:
Net8 performs its functions by sending and receiving data packets.By specifying a trace level of SUPPORT, you can view the actual contents of the Net8 packet in your trace file. The order of the packet types sent and received will help you to determine how your connection was established.
Each line in the trace file begins with a procedure followed by a message. Following each procedure is a line of hexadecimal data representing actual data. The actual data that flows inside the packet is sometimes viewable to the right of the hexadecimal data.
Table 10-4 provides a list of the Net8 packet keywords and describes the types of packets they represent:
Keyword | Packet Type |
---|---|
NSPTCN |
Connect |
NSPTAC |
Accept |
NSPTRF |
Refuse |
NSPTRS |
Resend |
NSPDA |
Data |
NSPCNL |
Control |
NSPTMK |
Marker |
Note:: This data is not viewable if you are using encryption through an Oracle network product or through EBCDIC data. |
For example, the following line describes a procedure called "nscon" sending a NSPTCN packet over the network:
nscon: sending NSPTCN packet
Each packet has a keyword that denotes the packet type. All packet types begin with the prefix "NSP". It is helpful to remember this when reviewing trace files for specific packet information
Example 10-4 provides typical packet information:
nscon: entry nscon: doing connect handshake... nscon: sending NSPTCN packet nspsend: entry nspsend: plen=187, type=1 nspsend: 187 bytes to transport nspsend:packet dump nspsend:00 BB 00 00 01 00 00 00 |........| nspsend:01 33 01 2C 0C 01 08 00 |.3.,....| nspsend:7F FF 7F 08 00 00 00 01 |........| nspsend:00 99 00 22 00 00 08 00 |..."....| nspsend:01 01 28 44 45 53 43 52 |..(DESCR| nspsend:49 50 54 49 4F 4E 3D 28 |IPTION=(| nspsend:43 4F 4E 4E 45 43 54 5F |CONNECT_| nspsend:44 41 54 41 3D 28 53 49 |DATA=(SI| nspsend:44 3D 61 70 33 34 37 64 |D=ap347d| nspsend:62 31 29 28 43 49 44 3D |b1)(CID=| nspsend:28 50 52 4F 47 52 41 4D |(PROGRAM| nspsend:3D 29 28 48 4F 53 54 3D |=)(HOST=| nspsend:61 70 32 30 37 73 75 6E |ap207sun| nspsend:29 28 55 53 45 52 3D 6D |)(USER=m| nspsend:77 61 72 72 65 6E 29 29 |warren))| nspsend:29 28 41 44 44 52 45 53 |)(ADDRES| nspsend:53 5F 4C 49 53 54 3D 28 |S_LIST=(| nspsend:41 44 44 52 45 53 53 3D |ADDRESS=| nspsend:28 50 52 4F 54 4F 43 4F |(PROTOCO| nspsend:4C 3D 74 63 70 29 28 48 |L=tcp)(H| nspsend:4F 53 54 3D 61 70 33 34 |OST=ap34| nspsend:37 73 75 6E 29 28 50 4F |7sun)(PO| nspsend:52 54 3D 31 35 32 31 29 |RT=1521)| nspsend:29 29 29 00 00 00 00 00 |))).....| nspsend: normal exit nscon: exit (0)
Every time a problem occurs with the connection in Net8, the error code is logged in the trace file with the prefix of <ERROR> or <FATAL>. Example 10-5 depicts typical trace file error output.
nspsend: entry nspsend: plen=244, type=6 ntpwr: entry ntpwr: exit -<ERROR>- nspsend: transport write error nspsend: error exit nserror: entry -<ERROR>- nserror: nsres: id=0, op=65, ns=12541, ns2=12560; nt[0]=511, nt[1]=61,nt[2]=0 -<ERROR>- nsopen: unable to open transport nricdt: Call failed... nricdt: exit -<ERROR>- osnqper: error from nricall -<ERROR>- osnqper: nr err code: 12203 -<ERROR>- osnqper: ns main err code: 12541 -<ERROR>- osnqper: ns (2) err code: 12560 -<ERROR>- osnqper: nt main err code: 511 -<ERROR>- osnqper: nt (2) err code: 61 -<ERROR>- osnqper: nt OS err code: 0 osnqme: entry osnqme: reporting nr (1) error: (12203) as rdbms err (12203) osnqme: exit -<ERROR>- onstns: Couldn't connect, returning 12203 nricall: Exiting NRICALL with following termination result -1 nricall: exit osnqme: entry osnqme: reporting nr (1) error: (12203) as rdbms err (12203) osnqme: exit -<ERROR>- onstns: Couldn't connect, returning 12203 -<ERROR>- osnqper: error from nricall
The most efficient way to evaluate error codes is to find the most recent NS error code logged. This is because the session layer controls the connection. The most important error messages are the ones at the bottom of the file. They are the most recent errors and the source of the problem with your connection.
For information about the specific return codes, use the Oracle UNIX error tool "oerr". Use the "oerr" tool to discover more information about Net8 return codes, by entering the following at any command line prompt:
oerr tns error_number
Net8 provides a tool called the Trace Assistant to help you understand the information provided in your trace files by converting existing lines of trace file text into a more readable paragraph. Note that the Trace Assistant runs against only a level 16 (SUPPORT) SQL*Net or Net8 trace file.
To run the Trace Assistant, type the following at any command line prompt:
trcasst [options] filename
Table 10-5 describes the options that are available.
Example 10-6 depicts how Trace Assistant converts trace file information into a more readable format.
However, other errors may also exist within the trace file that were not logged from the nserror function.
Trace Assistant also allows you to view data packets from both the Net8 and Two Task Common communication layers. Trace Assistant offers you two options to view these packets:
The following examples depict how Trace Assistant presents various packets as they are sent to and from the Net8 layer in a variety of transactions:
Note that the packets being sent or received have a prefix of "---> Send nnn bytes" or "<--- Received nnn bytes" showing that this node is sending or receiving a packet of a certain type and with nnn number of bytes. This prefix enables you to determine if the node is the client or the server. The connection request is always sent by the client, but received by the server (or listener).
Two-Task Common handles requests such as open cursor, select rows, and update rows that are directed to the database. All requests are answered by the server. If you request to logon, a response is returned from the database that the request was completed. Example 10-11 and Example 10-12 show the type of information you can expect.
Summary information for Two-Task Common is different from other displays in that it shows two packets on each line, rather than one. This is done to mirror the request/response pairings process by which Two-Task Common operates.
The type of statistics gathered is on the order of how many calls (TTC), packets and bytes were sent and received between the network partners. The following example depicts typical trace file statistics:
The following example shows a full trace file decoded. This example was created using the Oracle client tool SVRMGRL with the request:
connect scott/tiger@june
The message ORA-12154: TNS:could not resolve service name was displayed on the screen.
This trace file provides a summary of what occurs with Net8 when you encounter the error "Could not resolve service name". In this example, a client is unsuccessful in making a connection to service name "june". This is because a "names.default_domain = world" parameter exists in the profile. This parameter adds the ".world" extension to all service names requested, including the service name "june". Unfortunately, this service name is defined in neither the client's local naming configuration file, nor a Names Server. To troubleshoot this problem, the user should:
If you are still unable to resolve your problems or if you are requested to contact Oracle Customer Support to report the error, please have the following information at hand:
Example: "My client application runs on a Sun workstation running SUN OS4.1.3 and the server application runs on a VAX machine running VMS version 5.4. The protocol is TCP/IP."
1 = Program not usable. Critical impact on operations.
2 = Program usable. Operations severely restricted.
3 = Program usable with limited functions. Not critical to overall operations.
4 = Problem circumvented by customer. Minimal effect, if any, on operations.