Using and Managing Trace Files

<< Click to Display Table of Contents >>

Navigation:  Administering SQLstream Blaze > Configuring s-Server >

Using and Managing Trace Files

Previous pageReturn to chapter overviewNext page

SQLstream uses the standard Java logging interface (defined in the package java.util.logging) to trace execution for debugging purposes. Trace files can let you troubleshoot stream functioning during development. Errors logged to the trace log are also available in the global error stream. See the topic Global Error Stream in the Streaming SQL Reference Guide for more details.

Configuration files

To control the depth of the logging and the formatting of the output, Java logging uses external configuration files in the standard Java properties format. You determine the location of these files during installation. By default, SQLstream uses the following logging configuration files:

Component

Configuration File

Default Trace Log File(s)

SQLstream s-Server

/var/log/sqlstream/Trace.properties

/var/log/sqlstream//Trace.log

/var/log/sqlstream/ApplicationTrace.log

SQLstream s-Studio and other client tools

/var/log/sqlstream/ClientTrace.properties

/var/log/sqlstream/ClientTrace.log

The SQLstream s-Server configuration controls tracing to two different log files: Trace.log and ApplicationTrace.log.

Trace.log This is the "master" trace, which includes all trace information for the entire server.

ApplicationTrace.log This contains only trace information relevant to installed application components (such as plugins, user-defined transforms, and SQL statements).

ClientTrace.log This records trace messages generated by client interaction with Streaming Data Protocol or JDBC; that is, all client interactions with s-Server.

You can modify the properties files to change the default logging. Before doing so, you should save a copy of the original, unmodified file.

Note: The installed files are made read-only by default so as to avoid accidental modification.

Changing tracing levels

Because trace files are intended for debugging, by default, very little is logged to these files. You can change the default tracing level by editing the Trace.properties or ClientTrace.properties file. To view more logging, open one of the properties files in a text editor and uncomment (remove the "#") lines such as the following (both from ClientTrace.properties):

#com.sqlstream.aspen.jdbc.level=FINE

#com.sqlstream.aspen.sdp.level=FINE

 

You can also change the tracing level for a particular package or class. For example, suppose you created a set of plugins that you want to debug at a high level of tracing. If the plugins are all part of a package called com.example.plugin, you can add the following to your Trace.properties:

com.example.plugin.level=FINEST

 

See also the topic Error Logging in the Streaming SQL Reference Guide.

Limiting trace log size

The default tracing configurations are intentionally set for development mode, with no limit is placed on the maximum size of a trace file. Once you move to production, it is important to change these settings to prevent trace files from eventually using up all available disk space.

There are two ways to limit trace files:

By placing a limit on the maximum size of any single trace file
By specifying that trace files should "roll over". (This option is enabled by default.) "Roll over" means that the first time a trace file is full, it will be saved with a "1" appended to the filename, and a new trace file will be started. Subsequent rollovers will be given a ".2" extension instead, and so on up to the maximum trace file count defined in the configuration file (set to 20 by default). Once that limit has been reached, the oldest trace file is deleted each time a new one is created.

To control the maximum file size and rollover count, change the following properties in the file /var/log/sqlstream/Trace.properties:

Trace.log

Property Name

Default

File size

java.util.logging.

FileHandler.limit

10000000 bytes

Rollover count

java.util.logging.

FileHandler.count

20

Application

Trace.log

Property Name

Default

File size

com.sqlstream.aspen.

trace.ApplicationLogConfigurator.limit

10000000 bytes

Rollover count

jcom.sqlstream.aspen.

trace.ApplicationLogConfigurator.count

20

For SQLstream s-Studio, use the following properties in /var/log/sqlstream/ClientTrace.properties:

ClientTrace.log

Property Name

Default

File size

java.util.logging.

FileHandler.limit

10000000 bytes

Rollover count

java.util.logging.

FileHandler.count

20

If you set file size limit to zero, the file will never roll over, even if a rollover count is set.

Using different configuration files

You can override which logging configuration file SQLstream uses by overriding the value for the property java.util.logging.config.file. To do so, set the property in the file $SQLSTREAM_HOME/aspen.custom.properties. To change the user interface logging configuration file, set the property in $HOME/.SQLstreamrc.

For example, to use the file /usr/local/MyTrace.properties for user interface logging configuration, add the following line to the .SQLstreamrc file in your home directory:

java.util.logging.config.file=/usr/local/MyTrace.properties

 

Adapter and SQL/MED parameters

SQLstream adapters use parameters specified as OPTIONs in the DDL (as do other SQL/MED methods to access external data) for their FOREIGN DATA WRAPPERs, SERVERs and any FOREIGN STREAMs based on them.

To find the configuration options for a particular adapter, see the documentation for that adapter. SQL/MED and related adapter matters are covered in the topic SQLstream Software Development Kit (SDK) in the s-Server Integration Guide.

Note that, like Java parameters, adapter and other SQL/MED parameters can perform variable expansion and substitution. The variable reference takes the form of a dollar sign followed by the name of the variable in curly braces. Such a property is evaluated at the time the DDL is executed (define time).

For example, the foreign server defined in the Edamame demo uses the variable aspen.home.dir to set the root directory for its log files under the SQLstream installation directory:

CREATE OR REPLACE SERVER "WebAppServer"

    FOREIGN DATA WRAPPER "LogStream"

    OPTIONS (ROOT '${aspen.home.dir}/temp')

    DESCRIPTION 'Server for webapp login stream';

 

Variables whose values are undefined are empty. For example, if aspen.home.dir were undefined, the ROOT parameter in the above example would evaluate as '/temp'.

Summarizing Error Messages

By default, s-Server reports a periodic summary of errors, in order to avoid bloating the trace log. However, this means that the global error stream contains only the summary counts and a few sampled bad rows. If you turn off sampling, you get all the bad rows traced and reported to the error stream.

To adjust sampling, you can change properties in the aspen.properties file: For more information on modifying aspen.properties, see the topic Managing Java Parameters in the Administrator Guide.

When this property is set to false, s-Server reports every late row in both the trace log and error stream. When this property is set to true, true, s-Server reports the first event and then reports every 15 seconds after the first event.

aspen.trace.sampleLateRows=false

 

You can also specify that s-Server report every row that causes a calculator error. When this property is set to false, s-Server reports every row that causes a calculator error. When this property is set to true, s-Server reports the first calculator event and then reports calculator events every 15 seconds.

aspen.trace.sampleFailedRows=true