streamtool viewlog

viewlog [-d,--domain-id <did>] {[--log] | [[-i,--instance-id <instance>] [[--tracefiles] | [--console]] [--resource <resourceId>] {[--service <service>] [--pe <pe>]}]} [-p,--print] [--tail <number>] [--which <number>] [-U,--User <user>] [-h,--help] [--trace <level>] [-v,--verbose <level>] [--zkconnect {<host>:<port>},... | --embeddedzk]

The streamtool viewlog command retrieves a log or trace file and opens an editor ($VISUAL, $EDITOR, or vi) to view the contents.

Authority

To view log or trace data for a domain, you must have read authority on the system-log domain object. By default, the DomainAdministrator role has this authority.

To view log or trace data for an instance, you must have read authority on the system-log instance object and search authority for the instance object. By default, the DomainAdministrator and InstanceAdministrator roles have this authority.

To view log or trace data for jobs, you must have read authority on the application-log instance object. You must also have search authority for the instance object and read authority for the appropriate jobgroup_name object. By default, the DomainAdministrator and InstanceAdministrator roles have this authority. If the user who submits the job has the InstanceUser role, they also have this authority. For more information, see streamtool getacl and streamtool getdomainacl.

Description

By default, the streamtool viewlog command opens the requested log or trace file in the editor that you specify in the VISUAL or EDITOR environment variable. To print to a stdout file, specify the --print option.

By default, the streamtool viewlog command displays a trace file. To view a trace file, you must specify a domain or instance service or a processing element. Services and processing elements have two types of trace files:

• a rolling component trace
• a rolling console trace that captures the stdout and stderr messages.

The instance's configuration controls the characteristics of the rolling log or trace mechanism: the maximum number of fragments and the maximum capacity of a fragment.

Trace files are composed of rolling fragments. By default, the streamtool viewlog command returns the most recent rolling trace fragment for the runtime service or PE. To view an older rolling fragment, specify the --which option.

When the number of trace files reaches the configured maximum, the system:

1. Removes the oldest (highest numbered) trace fragment.
2. Increases the number of each trace fragment by one. For example, fragment 1 becomes 2.
3. Changes the current fragment to fragment 1.
4. Creates a new empty current fragment.

When you retrieve a trace for a management service, the trace is retrieved from the current host the service is configured on unless another host is specified.

If the instance is configured to use a LogType of

, use the Linux log viewer to view the log.

To view the stdout and stderr console trace messages, specify the --console option.

To collect log and trace data, use the streamtool getlog command. This command saves the data in a compressed tar file.

--console

Specifies to show the stdout and stderr output for the processing element or service.

-d,--domain-id <did>

Specifies the domain identifier.

If you do not specify this option, Streams uses the domain name that is set in the STREAMS_DOMAIN_ID environment variable. By default, that domain name is StreamsDomain. If you are using the interactive streamtool interface, it uses the name of the active domain for the current streamtool session or else it prompts you for the domain name.

The active domain for the current streamtool session is set every time that you successfully run a streamtool command with a -d or --domain-id option. Alternatively, you can run the streamtool domain command in the interactive interface.

--embeddedzk

Specifies to use the embedded copy of ZooKeeper. This option is not supported within the interactive streamtool interface.

If you are not using the interactive streamtool interface and you do not specify either this option or the --zkconnect option, Streams uses the ZooKeeper connection that is associated with the active domain or the domain that is specified in the --domain-id option. Streams determines which connection maps to the domain by using cached information about the domains. In this scenario, if the domain identifier is not unique in the Streams configuration cache, the command fails.

-h,--help

Specifies to show the command syntax.

-i,--instance-id <instance>

Specifies the instance identifier.

If you do not specify this option, Streams uses the instance identifier that is set in the STREAMS_INSTANCE_ID environment variable. By default, that instance identifier is StreamsInstance. If you are using the interactive streamtool interface, it tries to use an instance ID that you specified in a previous command. If no such value is found, the command uses the STREAMS_INSTANCE_ID environment variable. Alternatively, you can run the streamtool instance command in the interactive interface.

--log

Specifies to collect only the domain log file. The domain log file contains the log data for the applications that are running in the domain. It also contains log data for the domain and instance services.

-p,--print

Specifies to not open an editor; the command prints the information to stdout instead.

--pe <pe>

Specifies the processing element identifier.

--resource <resourceId>

Specifies a resource identifier, which can be the host name or IP address. The command gets the trace file from this resource.

--service <service>

Specifies the name of the domain, instance, or application service. Enter one of the following values for service-name:

• aas: The authentication and authorization service.
• app: The application deployment service.
• auditlog: The logging service.
• controller: The domain controller service.
• jmx: The management API service.
• pec: The processing element container.
• sam: The application manager service.
• srm: The application metrics service.
• sws: The web management service.
• view: The view service.

--tail <number>

Retrieves the last number lines of the log or trace file, where number must be greater than zero.

--trace <level>

Specifies the trace setting. The following valid levels are listed in order of increasing verbosity, which is to say that the first level in the list generates the least amount of information:

• off
• error
• warn
• info
• debug
• trace

The default value is off.

--tracefiles

Specifies to view the trace files for the processing element or service. By default, the command uses this option.

-U,--User <user>

Specifies an Streams user ID that has authority to run the command.

-v,--verbose <level>

Specifies to provide more detailed command output. The verbosity level can be 0-3, where 0 disables detailed reporting and each increment provides more detailed output.

--which <number>

Specifies to retrieve the specified rolling trace fragment.

• By default, Streams displays the most recent rolling log or trace fragment for the processing element or runtime service (current).
• To view an older fragment, specify the fragment-number. Streams numbers the rolling fragments in most-recent-first order, for example, number 1 is a more recent fragment than number 2.

--zkconnect <{<host>:<port>},...>

The name of one or more host and port pairs that specify the configured ZooKeeper servers. This option is not supported within the interactive streamtool interface.

If you are not using the interactive streamtool interface and you do not specify this option, Streams tries to use:

1. The --embeddedzk option
2. The value from the STREAMS_ZKCONNECT environment variable
3. A ZooKeeper connection string that is derived from cached information about the current domain.

Example 1: Viewing the log data for a host

To view the log for the domain, enter the following command:

[streamtool <bsmith@StreamsDomain.StreamsInstance>] viewlog --log

Example 2: Viewing the most recent trace data for an application, domain, or instance service:

To view the most recent rolling trace file for the web managment service, enter the following command:

[streamtool <bsmith@StreamsDomain.StreamsInstance>] viewlog --service sws

Example 3: Viewing the most recent trace data for a processing element

To view the most recent rolling trace file for a processing element, enter the following command:

[streamtool <bsmith@StreamsDomain.StreamsInstance>] viewlog --pe pe-id

Example 4: Viewing the most recent trace data for an operator

To view the most recent rolling trace file for an operator in the specified processing element, enter the following command:

streamtool viewlog -d StreamsDomain -i StreamsInstance --embeddedzk --pe pe-id --print | grep operator-id

To specify the number of output lines, include

on the command.

For example, the following output was generated from a streamtool viewlog that specified a pe-id of 5 and a operator-id of Source1:

08 Jun 2012 17:17:12.032 [13854] DEBUG #splapptrc,J[1],P[5],Source1,spl_operator 
M[Source1.cpp:process:190] - FileSource startup...