Log and trace files generated by Teracloud® Streams

By default, Teracloud® Streams generates log and trace files for the domain and instance services and applications. Administrators, instance owners, application developers, and Teracloud® Support can use this data to correct problems with Teracloud® Streams.

Location of log and trace files

Log and trace files are on the resources where the Teracloud® Streams services and applications are running. The log and trace files for a processing element (PE) are on multiple resources if the PE is moved during its execution.

The default root directory for all log and trace files is the /tmp directory. You can configure a different root directory by updating the domainLog.path domain property. The names of the subdirectories under your configured root directory cannot be changed. For more information, see Changing the default location of log and trace files.

The /tmp directory is also the default root directory for the Teracloud® Streams class cache and other temporary files. If the class cache files are removed, the web management service might fail and not recover correctly. You can configure a different root directory by updating the domain.fileStoragePath domain property.

Removal of log and trace files

By default, Teracloud® Streams automatically removes all log and trace files when you remove a domain. Component-specific log and trace files are removed when you start or stop an instance or remove a resource.

To manually remove log and trace files, you must use the streamtool cleanlog command.

Rolling log and trace files

Most log and trace files that are generated by Teracloud® Streams are rolling files, which consist of multiple file fragments. By default, Teracloud® Streams retrieves the most current fragment.

Rolling file fragments are numbered such that the most recent fragment has the number 0 and the older fragments have the larger numbers. For example, fragment 1 is a more recent fragment than fragment 2.

When a rolling log or trace file reaches its maximum size, Teracloud® Streams performs the following actions:
  1. Removes the oldest (highest numbered) file fragment.
  2. Increases the number of each file fragment by one. For example, fragment 1 becomes fragment 2.
  3. Changes the current fragment to fragment 0.
  4. Creates a new empty current fragment.
The maximum trace file size and number of files to save are controlled by the following domain and instance properties:
  • domainTrace.maximumFileSize
  • domainTrace.maximumFileCount
  • instanceTrace.maximumFileSize
  • instanceTrace.maximumFileCount

Log and trace file types, default locations, and descriptions

To collect and view log and trace data, you can use the streamtool command line interface or the Streams Console.

The following table describes the types of log and trace files that are generated for Teracloud® Streams services and applications.

Table 1. Log and trace file types for Teracloud® Streams services and applications

This table lists the types of log and trace files, the default location on each host, and a brief description. The description shows the format of the log and trace file names.
File type Description
Default location on each host: /tmp/domain-id/logs/resource-id directory

The trace files for an instance are in the /tmp/domain-id/logs/resource-id/instances/instance-id directory.
Domain log file For each domain, there are streams.number.log files that contain log messages for the Teracloud® Streams services and applications.
Service trace files These rolling service-name.out files contain trace messages for the Teracloud® Streams services.1

The service-name.number.log files are trace files for the waiting state service, for example: jmx.0.log.
Default location on each host: /tmp/domain-id/logs/resource-id/instances/instance-id/jobs/job-id directory
Application trace files These files are rolling pe.pe-id.out files, where pe-id is the processing element ID.
These files contain the following types of trace messages:
  • Trace messages that are generated by Streams Processing Language (SPL) standard toolkit operators.
  • Trace messages that are generated by Java™ primitive operators.
  • Trace messages that are generated by C++ primitive operators and native functions (SPLAPPTRC macro).
Processing Element Container (PEC) service trace files These files are rolling pec.pe-id.out files, where pe-id is the processing element ID.
Application and PEC service console trace files These files are rolling pec.pe.pe-id.stdouterr files, where pe-id is the processing element ID.

These files contain stdout/stderr messages for Teracloud® Streams applications and the PEC service.
Default location on the resources that run the web management services: /tmp/domain-id/SWSCache directory
Application server class cache files, trace files, and log files These files are non-rolling files that are generated by the application server that is used by the web management service.
Table note:
  1. The service-name is the short name of the Teracloud® Streams service.