| |
Home |
![[Table of Contents]](/dwicons/b_toc.gif)
|
Server Administration Guide for DirectConnect |
![[-]](/dwicons/i_colpse.gif)
| Chapter 6 Log and trace files |
Chapter 6
This chapter explains DirectConnect log and trace files. Both file types provide troubleshooting information, but each is intended for a different audience. The distinctions are as follows:
The log file is a collection of records intended primarily for the System Administrator.
The trace file is a collection of records intended primarily for Sybase Technical Support personnel.
This chapter includes the following topics:
The DirectConnect Server provides several facilities for logging and reporting information. It uses these facilities during startup, setup, and connection routing. The log file, srv.log, begins recording information each time you start the server and continues recording messages the entire time the server runs.
When srv.log reaches 10MB, the log file is renamed srv.log_old and any other srv.log_old file is overwritten. This allows OpenServer tracing to be enabled without using any more than 20mb of disk space.
While the actual data in any log file depends upon the product and events, representative log file data can include:
Performance data and timestamps
Client connection activity
Client messages
Statistics
SQL language, as received and after transformation
Host communications
Host server file information
The maximum size of any DirectConnect log record is 32,767 characters.
You can enable or disable logging on the following levels:
DirectConnect Server
Service library
Service
Tracing is a tool used by Sybase Technical Support to solve customer problems. In most situations, you enable tracing only in response to a request from Sybase Technical Support.
The actual data in any trace file depends upon the product. Representative trace file data can include:
Logged messages
Function entry and exit events
Failure points
Data passed between functional layers
Data transformations
While you can control the degree of tracing through configuration properties, any level of tracing degrades system performance. For this reason, use tracing only in particular, controlled situations.
The "Tracing" setting in the [ODBC] section of the odbc.ini file should be set to 0. Setting this value to 1 causes a negative impact on performance.
An exception to this rule involves DirectConnect Server startup. If startup fails, you may want to use the low-level failure details written to the trace file and attempt to solve the problem without Sybase Technical Support assistance.
The DirectConnect Server differentiates between log records and trace records. Each type of data is contained in a separate file. The files are maintained in U.S. English, using the native character set of the machine on which the server is running. However, client messages that are written to the log file appear in the client language.
You can configure logging and tracing properties by editing server or service library configuration files. When you make such changes, you must stop the server, then restart it for the changes to take effect. For information about editing configuration properties, see Chapter 4, "Configuring the server" .
You also can use DirectConnect Manager to make certain configuration changes dynamically:
Select the DirectConnect server.
Select the Configure button, or select Properties from the Configure menu.
The Configuration Properties property sheet appears, showing tabbed pages that contain groups of related DirectConnect properties.
Select the Server properties tab.
Highlight the logging or tracing property, enter or select the new value in the Change box, and select the Change button.
Select OK to send the new values to DirectConnect. The output window displays messages that indicate the results of the configuration changes.
You can use a text editor to read log or trace records from the appropriate DirectConnect Server subdirectory. Optionally, you can use the DirectConnect Manager to retrieve and read the record, described in the following section.
DirectConnect Manager allows you to access the server log file, retrieve its messages, and view them in a text editor. You can retrieve the entire server log file, or set criteria to retrieve only a subset on the log file.
To retrieve the server log file:
Select a server.
From the File menu, select Retrieve Server Log.
The Retrieve Server Log File dialog box appears, showing the following tabbed pages:
Object Names
Record Types
Spid (Server Process ID)
User ID
Date/Time
Select the tabbed page with the criteria you want, then select the Date/Time page, where you specify a range of time or dates for which you want to retrieve server log messages.
Select OK.
DirectConnect Manager retrieves a snapshot of the server log file, saves it to your hard drive, and opens the file in the default text editor. The snapshot contains a subset of the server log file that meets the criteria you selected in the Retrieve Server Log File pages.
The log file resides in the log subdirectory. The default log file name is ServerName.log, where ServerName is the name you assigned to the DirectConnect Server during installation. A single log file contains log records from all services.
The trace file also resides in the log subdirectory. The default trace file name is ServerName.trc, where ServerName is the name you assigned to the DirectConnect Server during installation.
The log and trace files are ASCII text files. Each contains startup data and configuration information in the header section at the beginning of the file.
The log file has a fixed size, which you can configure. If the LogWrap configuration property value is set to yes, the log file wraps when it reaches its configured maximum file size. For more information, see Chapter 4, "Configuring the server" .
The trace file does not have a size limit. If tracing is enabled, the file grows to consume all available disk space. Because limiting the file size can cause a potential loss of data that Sybase Technical Support may need for problem-solving, you cannot specify a maximum trace file size.
Log and trace records are recorded in chronological order. If multiple workstations use DirectConnect Servers, the log or trace records for a particular user do not appear consecutively.
The logical end of the log file is indicated by an <END> marker.
Each time the DirectConnect Server starts, it creates new log and trace files. The existing files are renamed as backup files, using the following format:
mmddyyss.log
where
mm is a two-digit number, from 1 to 12, that indicates the month.
dd is a two-digit number, from 1 to 31, that indicates the day.
yy is a two-digit number, from 0 to 99, that indicates the year.
ss is a two-digit, random number.
Be sure to delete or archive the backup files periodically to conserve disk space.
Log and trace records consist of a variable number of columns of data, separated by tab characters.
The following table displays the columns of data in a typical log or trace record.
Record Type | DateTime | Object Name | SPID | User ID | Application Name | Specific Information |
The following table describes the function of each of the columns.
Column | Description |
Record Type | The configuration property name. |
DateTime | The date and time the record was published. |
Object Name | The name of the service, service library, or server that generated the record. |
SPID | The Open Server process ID (if applicable). |
User ID | The user ID of the client connection that generated the record (if applicable). |
Application Name | The name of the client application through which the client connected (if applicable). |
Specific Information | The message text, which may contain embedded tabs to further separate the information in this column. |
If a service library logs a message during its start or stop functions, client information is not available. In such cases, the Object Name column contains the service library name, and the SPID, User ID, and Application Name columns read "NULL."
Log messages that do not originate from the DirectConnect Server or a service library are generated by the service library in the context of a client connection.
The DirectConnect logging facility must have access to the server configuration file server.cfg before it can initialize. If the server configuration is invalid, or if an early startup error occurs, messages are sent to the following substitute locations:
In all cases, including Windows NT systems, the server sends messages to stderr (the console by default).
On Windows NT systems only, messages are also written to the Windows NT event log.
Because these "pre-log" error messages do not appear in the log file, the most common messages, with explanations, are listed in the following sections.
If a startup error occurs when the DirectConnect Server is started from the command line, the following messages are sent to stderr:
System info is invalid
This message indicates that either the system environment variables are not working properly, or the system is low on memory or other resources.
Memory allocation failure: property
This message indicates that the system is out of memory.
Could not load the configuration:{filespec}The noted configuration file filespec is missing, incorrectly named, in the wrong location, or corrupt. The message text displays the full path and file name of the expected server.cfg file.
Invalid configuration property value on line: {line_number}
The configuration is invalid: {filespec}One or more configuration properties contains an invalid value. The message text displays the full path and file name of the erroneous server.cfg file.
If a startup error occurs when the DirectConnect Server is started as a Windows NT service, the following messages are sent to the Windows NT event log:
Messages 2 through 9 indicate fatal errors that terminate the startup process. Messages 10 and 11 are informational only.
2 The DirectConnect Server service could not be registered with the Windows NT service manager.
The previous message indicates an operating system error or a problem with the Windows NT Registry.
3 DirectConnect Server failure while reporting status to Windows NT service manager.
This message indicates an operating system error or a problem with the Windows NT Registry.
4 DirectConnect Server failure creating event for process thread.
This message indicates an operating system error or a system resource problem. Check whether excessive processes are presently running.
5 DirectConnect Server failure launching process thread.
This message indicates an operating system error or a system resource problem. Check whether excessive processes are presently running.
6 DirectConnect Server failure constructing system information.
Either the system environment variables are not working properly, or the system is low on memory or other resources. Check the system path syntax and the SYBASE and DSLISTEN environment variables.
7 DirectConnect Server could not load the server configuration: <filespec> The file may be missing.
One or more configuration properties contains an invalid value. If the server was started from a command line, the offending line number is indicated.
If the server was started on a Windows NT system as a Windows NT service, run the product from the command line and add the -t switch to perform a startup test. Doing this displays the full error information.
9 DirectConnect Server failure constructing the log manager.
The log manager process could not be started. Make sure that the executable exists in the \DC-12_0\bin directory.
10 DirectConnect Server "{server_name}" started.This informational message logs when the server starts.
11 DirectConnect Server "{server_name}" stopped.This informational message logs when the server stops.
Both messages 10 and 11 are written every time you start or stop the server. These records are not automatically erased. If you start and stop the server frequently, y ou may want to purge your Windows NT event log periodically.
The example in this section shows log records from a server startup attempt. The example uses the following conventions:
The first six columns of each record are omitted since these columns are virtually identical from record to record.
All of the records are of type LogHeader, except for the last, which is of type LogEndHeader.
The line numbers are for the explanations that follow the example. The numbers do not appear in an actual log file.
The sample log file is as follows:
1 -------------------------------- 2 DirectConnect 12.0 B 3 Copyright(c)2000, Sybase, Inc. 4 INTEL x386 Windows NT 4.1 (807) 5 (CRS 85.0) OPT 17-Mar-1997912:00:00 6-------------------------------- 7 *** Initial configuration for: [SRVNAME] *** 8 --- MaxConnections = 2 9 --- RemoteSites = 3 10--- DefQueueSize = 1024 11--- CtlibPacketSize = 512 12--- OpenServerTraceFlags = 0 13--- ServiceRedirectionFile = snrf.tbl 14--- Description = The DirectConnect server. 15--- LogFileName = 16--- LogFileSize = 500000 17--- LogWrap = yes 18--- LogFlush = no 19--- LogToScreen = no 20--- LogClientLogin = yes 21--- LogClientMessages = 0 22--- TraceFileName = 23--- TraceLogMessages = yes 24--- TraceEntryExit = yes 25--- TraceAsync = yes 26--- TraceOther = yes 27--- TraceToScreen = no 28 Service Name Redirection enabled: C:\SQL10\ DC-12_0\SRVNAME\cfg\snrf.tbl 29*** The following localized message files are \ supported: 30--- C:\SQL10\DC-12_0\SRVNAME\locales\ us_english\cp850\server.loc 31 Loading service library file: C:\SQL10\ DC-12_0\SRVNAME\svclib\shutdown.dll 32***Initial configuration for: [Shutdown] *** 33***Initial configuration for: [shutdown] *** 34--- EnableAtStartup = yes 35 Service loaded: [shutdown] 36*** The following localized message files are \ supported: 37--- C:\SQL10\DC-12_0\SRVNAME\locales\ us_english\cp850\shutdown.loc 38 Successfully initialized service library: \ Shutdown 39 Loading service library file: C:\SQL10\ DC-12_0\SRVNAME\svclib\smtest1.dll 40*** Initial configuration for: [smtest1] *** 41---UserExitFileName = userexit 42*** Initial configuration for: [ServiceA] *** 43--- MaxClients = 10 44--- EnableAtStartup = yes 45--- StopCondition = error 46--- MaxRowCount = 1000 47--- LogReceivedSQL = yes 48 Service loaded: [ServiceA] 49 Service loaded: [ServiceB] 50*** The following localized message files are \ supported: 51--- C:\SQL10\DC-12_0\SRVNAME\ locales\us_english\cp850\smtest1.loc 52 Successfully initialized service library: \ smtest1 53 !READY! Waiting for connections.
Following are explanations of the log record entries, by line number:
5: A mnemonic indicates the build or version of the library that was linked with the executable.
7: The server name appears in the brackets.
8-27: The startup values for the server configuration properties are listed.
19: The system sends log records to the log file, but not to the screen.
28: An indication whether service name redirection is to be used, and if so, the path to the file that was loaded.
29-30: The localized message files found for the server and the supported locales are shown.
31, 39: Each service library module installed in the \DC-12_0\ServerName\svclib subdirectory is loaded in turn.
32: The service library properties are listed. In this example, the [Shutdown] service library does not have configurable properties.
33-34: The initial configurations of the enabled services associated with the service library are listed. In this example, the [shutdown] service defines one configuration property: EnableAtStartup.
35: An indication that initialization for the specified service is complete.
36-37, 50-51: The localized message files found for the associated service library and the supported locales are listed.
38: An indication that initialization for the specified service library is complete.
49: In this example, [ServiceB] was loaded but not enabled, nor is it able to receive connections. This is noted by the lack of an initial configuration listing (initial service configuration is always output when the service becomes enabled). Because this service was not enabled at startup, you can enable it only with DirectConnect Configuration Tool.
53: An indication that server initialization is complete. Clients can now connect to any enabled service.
In this example, the information shown after the system-supplied columns is free-form.
The trace records are separated by tabs so you can easily import them into most query tools.
TraceEntryExit 06/30/1995 16:35:57.641 SRVNAME NULL NULL NULL > evm_StartHandler
TraceEntryExit 06/30/1995 16:35:57.651 SRVNAME NULL NULL NULL > smServer::LoadSvclib: [C:\sql10\ DC-12_0\SRVNAME\svclib\sample1.dll] linked with DirectConnect v10.5.0 lib:smr
TraceEntryExit 06/30/1995 16:35:57.771 SRVNAME NULL NULL NULL > smSvclib::InitCriticalBase
TraceEntryExit 06/30/1995 16:35:57.801 SRVNAME NULL NULL NULL > smServer::AddSvclib: [Sample1]
TraceEntryExit 06/30/1995 16:35:57.801 SRVNAME NULL NULL NULL < smServer::AddSvclib
TraceEntryExit 06/30/1995 16:35:57.821 SRVNAME NULL NULL NULL < smSvclib::InitCriticalBase
TraceEntryExit 06/30/1995 16:35:57.821 SRVNAME NULL NULL NULL < smServer::LoadSvclib: [Sample1]
TraceEntryExit 06/30/1995 16:35:57.831 SRVNAME NULL NULL NULL > smServer::LoadSvclib: [C:\sql10\DC-12_0\SRVNAME\svclib\sample2.dll] linked with DirectConnect v10.5.0 lib:smr
TraceEntryExit 06/30/1995 16:35:57.931 SRVNAME NULL NULL NULL > smSvclib::InitCriticalBase
TraceEntryExit 06/30/1995 16:35:57.961 SRVNAME NULL NULL NULL > smServer::AddSvclib: [Sample2]
TraceEntryExit 06/30/1995 16:35:57.961 SRVNAME NULL NULL NULL < smServer::AddSvclib
TraceEntryExit 06/30/1995 16:35:57.991 SRVNAME NULL NULL NULL < smSvclib::InitCriticalBase
TraceEntryExit 06/30/1995 16:35:57.991 SRVNAME NULL NULL NULL < smServer::LoadSvclib: [Sample2]
TraceEntryExit 06/30/1995 16:35:57.991 SRVNAME NULL NULL NULL < evm_StartHandler: !READY!
|
|