This documentation supports the 20.02 version of BMC Helix Platform.To view the documentation for the current version, select 20.08 from the Product version menu.

Enabling logging for a Digital Service application

BMC Helix Platform provides logging capabilities that you can use to track the activities and debug issues within the application. This topic provides information about enabling logs, setting logging levels, and viewing the contents of the log file for the applications. 

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 smart bundles are stored in same log file by specifying same log file name for each smart bundle.

To enable BMC Helix Platform logs

To generate logs, you must turn on the Debug-mode shared configuration setting.

  1. Log in to BMC Helix Innovation Studio and navigate to Administration tab.
  2. Click Configure My Server > Centralized Configuration Settings > Centralized Tenant Configuration.
  3. From the Component Type, select shared, and click Add Setting.
  4. On the Add Setting page, enter the following details:
  5. Click Save. 

Selecting the Debug-mode flags based on component

The Debug-mode represents a bit field. Each area supported by logging must be enabled by adding the correct binary value for the correct bit, which you can compute using a binary OR. The following table provides a list of values that you can use to for the corresponding log component:

Important

The binary equivalent is just shown here to help in understanding which flags control which components; you do not enter this as the Debug-mode.


Log component

Typical troubleshooting

Value

Binary equivalent

Nothing enabled

This is the default value.

0

000000000000000000000

SQL

Low level errors involving the database, such as unique index violation.

1

000000000000000000001

FLTR

Activity around Rules based on the time conditions, or record level events (on or after create, update, delete, and so on).

Often used to trigger processes.

2

000000000000000000010

USER

Login, logout, authentication, licensing, and so on.

4

000000000000000000100

API

Activity at the AR System level.

16

000000000000000001000

PROCESS

Execution of process steps, process blocking, in-process exceptions.

1048576

100000000000000000000

All but SQL

Turn on logging for all the above components, except for low level errors involving the database.

1048598

100000000000000010110

Turn on all of the above

Turn on logging for all the above components.

1048599

100000000000000010111

To enable logs

Important

If you are working on a Developer Sandbox, you can view or retrieve the log files, see To view or search the log file contents.

If you are working in a Tailoring environment, QA environment, or Production environment, you must contact BMC Support to view the log files and help troubleshoot the issues.

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

  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.

Important

  • If you use library services from an application, the library's logs are captured in the application's log file. These logs are generated based on the Logger Configuration Settings (File Name, Level) defined for the application.
    Capturing the library's logs in the application's log file allows you to maintain the log activities for the complete execution of the application in one single file.
    For example, a PTO application uses the Approval library to approve or reject the leave request of an employee. The logs for Approval library are stored in the log file for PTO application. The logs are generated based on the Logger Configuration Settings defined for PTO application.
  • The library's Logger Configuration Settings are used only if a REST API call is made to the library bundle with default-bundle-scope set to the library's bundle ID.
  • If default-bundle-scope is not set in REST API, then the logs are captured in arextension.log file.

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. 

Example

You want to troubleshoot why updating a request takes longer than expected. There are several rules and processes that run when a request is updated. After enabling the API, rule, process, and SQL debug logs, you can search for the Operation Id to identify the exact action that is causing the delay. 

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

To view or search the log file contents

Important

You can view the log file contents only if you are working on a Developer Sandbox.

  1. Log in to Remedy Mid Tier.
  2. Open the AR System Administration Console and select Tenant Server Configuration > General > Server Information to open the AR System Administration: Server Information form.
  3. Click the Log Files tab.

  4. Select any of the log types and in the Name field, type the name of the log file, as shown in the following image:

    application logging.png 

  5. Click View.
    You can view or save the log file.  
  6. Identify a server-generated Operation Id for an action:
    1. For any event or action that you want to debug, search for the start point of the API, rule, or process of the action. 
    2. Note the value of the <OpId> parameter. The Operation Id is a 30-character alphanumeric value. 
      Example: IDGG5K5KB1HMPAOD1EK2OD1EK28A9Z
    3. Search the log files for that Operation Id value.

To disable logs

  1. Log in to BMC Helix Innovation Studio, navigate to the Administration tab, and select the required deployed smart bundle
  2. Click Logger Configuration.
  3. In the Logger Configuration Settings panel, enter the name of the log file.
  4. Leave the Level field blank; do not select any option. 
  5. Click Save.

To clear the logs

Caution

BMC recommends that you do not delete the log files if you are on production environment. To delete the log files, stop the server services, clear the logs, and restart the server services.

  1. Stop the services of the BMC Helix Platform server.
  2. From the following default location of log files, select the application log file that you want to clear:
    • (Windows) – ARSystemInstallDir\<tenantdirectory>\ARserver\Db
    • (UNIX) – ARSystemInstallDir/<tenantdirectory>/ARserver/Db
  3. Delete the application's log file. Alternatively, you can clear the contents of the log file.
  4. Restart the services of the BMC Helix Platform server.

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;
        }
    }
}

Important

If you use the Logger service in any of the register() methods associated with the bundle start event, the logs for the applications are captured in the log file with a name such as arextension.log. On Windows, the location of the file is <ARServerInstallDir>\ARServer\Db.

Related topic

Enabling-browser-logging-in-a-Digital-Service-application

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*