Enabling and downloading logs from BMC Helix Innovation Studio

BMC Helix Platform provides logging capabilities that you can use to track the activities and debug issues within the application. With BMC Helix Platform you can gather information to troubleshoot functional issues or errors that occur in a bundle and log them in a log file. The logs for each bundle are stored in a separate log file unique to that bundle. For example, logs for bundle A are stored in log file A, whereas logs for bundle B are stored in log file B.

BMC Helix Platform also allows multiple bundles to share the same log file name. For example, bundle A invokes a service from bundle B, the logs for the completed execution will be stored in multiple files. To avoid logs from being saved in multiple log files, BMC Helix Platform allows bundles to share the same log file name. The logs generated by these bundles are stored in same log file by specifying same log file name for each smart bundle.

As a developer or an administrator, you can enable bundle and server logs and download the log files to troubleshoot issues.

To enable bundle logs

1. Log in to BMC Helix Innovation Studio, navigate to the Administration tab, and select the required bundle.
2. Click Logger Configuration as shown in the following image:
   

3. In the Logger Configuration Settings panel, enter the following details:

   Option	Description
   File Name	Specify the name of the log file. By default, name of your smart bundle is the name of the log file.
   Level	Specify the level of logging for smart bundle. The options are: TRACE DEBUG INFO WARN ERROR The default level is ERROR.

4. Click Save.
   For information about downloading bundle logs, see To download bundle and server logs.
   
   

To enable server logs

1. Log in to BMC Helix Innovation Studio and navigate to the Administration tab.
2. Select Logger Configuration > Server Logs.
   The following image shows the Server Logs page.
   

3. On the Server Logs page, in Capture logs for the next, enter the time interval for which you want to capture the logs.

   Important

   Server logs are automatically turned off after the set time interval has elapsed. However, you can still download the bundle logs that you have enabled.

4. In Log types to be captured, select the type of logs that you want to capture and download.
   You can enable the following log types: 

   • Rules

   • Escalation (Timer Rules)

   • Process
     

5. (Optional) If you want to capture SQL and API logs, click Show More and then select these logs. 

6. To save the log settings, click Save.
   The server logs are enabled and captured for the set time interval.

To download bundle and server logs

1. Log in to BMC Helix Innovation Studio and navigate to the Administration tab.
2. Select Logger Configuration > Server Logs.
3. On the Server Logs page, click Download Logs.
   A tar.gz file is downloaded that contains the server.log file. 

As an administrator, when you download logs, you might see multiple tar files inside the main tar.gz file like <server-instance>-0.tar.gz, <server-instance>-1.tar.gz. You can see all the logs that pertain to your application and might have spanned across different servers. 

For more information about the format of log files, see Format of log messages.

To update the log file size and log history settings

As an administrator, you can change the default value for the maximum log file size and log history settings. However, we do not recommend that you manually update these settings. When you set a large file size, it could impact the download functionality.

1. Log in to BMC Helix Innovation Studio and navigate to the Administration tab.
2. Select Configure My Server > Centralized Configuration Settings > Centralized Tenant Configuration.
3. On the Centralized Tenant Configuration page, from Component Type, select Shared.

4. To update the maximum log file size and log history, select and edit the following settings:

   Setting name	Setting description	Default value
   Max-Log-File-Size	Takes the value for the maximum size of each log file.	134217728 (Bytes)
   Max-Log-History	Takes the value for the number of log files created for the set time interval. A new log file is created when the previous file has reached its maximum file size.	8 (files)

Searching log files to track a single operation

An operation consists of several actions. For each operation, the logs are scattered across several files such as Process Log, API Log, SQL Log and so on. Any log file that is enabled contains the Operation Id parameter unique for all logs of an operation. To troubleshoot an application, you can search the Operation ID parameter in several log files and group the logs related to a single operation. 

You can set the Operation Id for an operation. If you have not set the Operation Id, the server generates the Operation Id.

How Operation ID works

• The server tracks a single operation with the same Operation Id in different log files.
• The server retains the Operation Id when the After Event rule executes.
• The server generates a new Operation Id for a process that resumes after a wait state. 
• The server generates a new Operation Id when a Timer Event rule is executed.
• When a custom rule or process is executed in a Thread Local context and spawns a new thread, you can copy the Operation Id from the calling thread to the new thread. If the new thread is left blank, the server generates a new Operation Id. The ThreadLocalContext provides a method to set and get the Operation Id.

To set the Operation ID

In the REST API HTTP header, add the parameter operation-id and set the value to an alphanumeric string of 1 to 30 characters. You can use any standard Java algorithms to generate the Operation Id. If you want to use the same Operation Id for multiple API calls, you must set the Operation Id in the HTTP header for each call. 

Format of log messages

The following example shows the general format of the log messages:

<BUNDLE> <TID: xxx> <TENANT ID:xxx> <USER: xxx > /*date */ <<log level>> <<actual message>> 

For example:

<BUNDLE><TID: 0000000033> <TENANT ID: TNGAABDUC2YGIAO78IS4O6M82T3SUZ> <USER:admin>  /* Wed Mar 15 2017 16:59:36.459 */ DEBUG trackExpenses : Debug Level Is Enabled 
<BUNDLE><TID: 0000000033> <TENANT ID: TNGAABDUC2YGIAO78IS4O6M82T3SUZ> <USER:admin>  /* Wed Mar 15 2017 16:59:36.462 */ TRACE trackExpenses: For Expense exception amount is 5000

Example of Operation Id in an API log

<API > <OpId: IDGG5K5KB1HMPAOD1EK2OD1EK28A9Z> <TID: 0000000001> <RPC ID: 0000000000> <Queue: Admin     > <Client-RPC: 390600   > <USER: Remedy Application Service                   > <Tenant-ID: 0                                            > <Overlay-Group: 0         > /* Fri Sep 15 2017 11:22:55.2270 */ +GLEWF   ARGetListEntryWithFields -- schema BundleDeploy:BundleRegistry from Unidentified Client (protocol 19) at IP address null using INTERNAL // :q:0.0s null
<API > <OpId: IDGG5K5KB1HMPAOD1EK2OD1EK28A9Z> <TID: 0000000001> <RPC ID: 0000000000> <Queue: Admin     > <Client-RPC: 390600   > <USER: Remedy Application Service                   > <Tenant-ID: 0                                            > <Overlay-Group: 0         > /* Fri Sep 15 2017 11:22:55.2390 */ -GLEWF            OK
<API > <OpId: IDGG5K5KB1HMPAOD1EK2OD1EK28A9Z> <TID: 0000000392> <RPC ID: 0000000000> <Queue: Admin     > <Client-RPC: 390600   > <USER: Remedy Application Service                   > <Tenant-ID: 0                                            > <Overlay-Group: 0         > /* Fri Sep 15 2017 11:22:55.2940 */ +GLEWF   ARGetListEntryWithFields -- schema BundleDeploy:BundleRegistry from Unidentified Client (protocol 19) at IP address null using INTERNAL // :q:0.0s null
<API > <OpId: IDGG5K5KB1HMPAOD1EK2OD1EK28A9Z> <TID: 0000000392> <RPC ID: 0000000000> <Queue: Admin     > <Client-RPC: 390600   > <USER: Remedy Application Service                   > <Tenant-ID: 0                                            > <Overlay-Group: 0         > /* Fri Sep 15 2017 11:22:55.2940 */ -GLEWF            OK
<API > <OpId: IDGG5K5KB1HMPAOD1EK2OD1EK28A9Z> <TID: 0000000001> <RPC ID: 0000000000> <Queue: Admin     > <Client-RPC: 390600   > <USER: Remedy Application Service                   > <Tenant-ID: 0                                            > <Overlay-Group: 0         > /* Fri Sep 15 2017 11:22:56.8780 */ +GLEWF   ARGetListEntryWithFields -- schema BundleDeploy:BundleRegistry from Unidentified Client (protocol 19) at IP address null using INTERNAL // :q:0.0s null

Using Logger service

BMC Helix Platform provides a Logger service (com.bmc.arsys.rx.services.common.Logger) for developers to add logs in their server-side code. For example, a developer can add logs in service classes or REST resources.

The following example shows how to get the Logger and use the Logger to log messages:

import com.bmc.arsys.rx.application.common.ServiceLocator;
import com.bmc.arsys.rx.services.common.Logger;

public class TaskService implements Service {
    public TaskResult createTask(Task task) {
        Logger logger = ServiceLocator.getLogger();
        if (logger.isDebugEnabled()) {
            logger.debug(String.format("the task name is %s, assigned to %s", task.getName(), task.getAssignee());
        }

        RecordInstance recordInstance = convertToRecordInstance(task);
        try{
            ServiceLocator.getRecordService().createRecordInstance(recordInstance);
            logger.info(String.format("task %s is created", task.getId()));
        } catch (RxException ex) {
            logger.error(ex);
            throw ex;
        }
    }
}

Related topic

Enabling browser logging in a Digital Service application