Troubleshooting your BAM Applications

0
83
9 min read

(For more resources related to this topic, see here.)

Understanding BAM logging and troubleshooting methodologies

In many cases, enabling BAM logging is the prerequisite for troubleshooting BAM issues. It is critical to set up the correct loggers to appropriate levels (for example, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, and FINEST), so that you can collect the information to identify the actual problem, and determine the root cause.

Apart from logging, it is also important to have the proven methodologies in place, so that you can follow these methods/procedures to conduct your troubleshooting practice.

Understanding BAM logging concepts

BAM provides a set of loggers, which are associated with BAM Java packages/ classes. Like Java, these loggers are named by following the dot convention, and are organized hierarchically.

Let’s take a look at an example. oracle.bam.adc is the root logger for the Active Data Cache. All the loggers for the sub-modules within the Active Data Cache should be named after oracle.bam.adc, and therefore become descendants of the root logger. For instance, oracle.bam.adc.security, which is the logger that tracks Active Data Cache security logs, is the child logger of oracle.bam.adc.

The logging level for the descendant/child (for example, oracle.bam.adc.security)inherits from the ancestor/parent (for example, oracle.bam.adc adc) by default, unless its logging level is explicitly specified. Thus, you should be careful when setting a root or parent logger to a low level (for example, TRACE:32 ), which may produce a large amount of log entries in the log file

The following table lists the major root-level loggers for troubleshooting key BAM components:

Logger name

Description

oracle.bam.adapter

This is the logger for troubleshooting the BAM

Adapter issues

oracle.bam.adc

This is the logger for troubleshooting the BAM

Active Data Cache operations, such as data

persistence, ADC APIs, Active Data processing

with ADC, and so on

orable.bam.common

This is the logger for debugging BAM common

components, for example, BAM Security or BAM

Messaging Framework

oracle.bam.ems

This is the logger for debugging BAM Enterprise

Message Sources (EMS)

oracle.bam.eventengine

This is the logger for debugging the Event Engine

oracle.bam.reportcache

This is the logger for debugging the Report Cache

oracle.bam.web

This is the logger for debugging the BAM web

applications, which include the Report Server

oracle.bam.webservices

This is the logger for debugging the BAM web

services interface

Enabling logging for BAM

To set up loggers for BAM, perform the following steps:

  1. Log in to Enterprise Manager 11g Fusion Middleware Control.
  2. Click on OracleBamServer(bam_server1) from the left pane, and select BAM Server | Logs | Log Configuration.

  3. Expand oracle.bam to set the BAM loggers. To ensure that the log-level changes are persistent, check the checkbox for Persist log level state across component restarts.
  4. Click on Apply.

The logs are written to the <server_name>-diagnostic.log file in the <mserver_domain_dir>/servers/<server_name>/logs directory. By default, the log file follows the size-based rotation policy, and the rotational size is 10M. You can change the default behavior by editing the log file configuration as follows:

  1. Log in to Enterprise Manager 11g Fusion Middleware Control.
  2. Click on OracleBamServer(bam_server1) from the left pane, and select BAM Server | Logs | Log Configuration.
  3. In the Log Configurations screen, click on the Log Files tab.
  4. Select odl-handler, and then click on Edit Configuration
  5. Edit the log file configuration, and click on OK.

Setting BAM loggers to appropriate values

Similar to what most Fusion Middleware components do, Oracle BAM uses the lo g levels specified in the Oracle Diagnostic Logging (ODL) standard to control the log details in the diagnostic log file.

Similar to the log levels in Java, ODL log levels and their descriptions are listed in the following table:

Log level (Java)

Log level (ODL)

Description

SEVERE+100

INCIDENT_

ERROR:1

This log level enables the BAM Server that reports critical issues or fatal errors.

SEVERE

ERROR:1

This log level enables the BAM Server components to report issues (system errors, exceptions, or malfunctions) that may prevent the system from working properly.

WARNING

WARNING:1

This log level enables the BAM Server components to report events or conditions that should be reviewed and may require actions.

INFO

NOTIFICATION:1

This is the default setting for all the BAM loggers. This log level is used to capture the lifecycle events of BAM Server components and the key messages for notification purposes. For example, if you need to verify the cache location or its running status for the BAM Report Cache, you can set the report cache logger to this log level.

CONFIG

NOTIFICATION:16

This log level enables the BAM Server components to write more detailed configuration information.

FINE

TRACE:1

This log level enables the BAM Server components to write the debug information to the log file. To  troubleshoot the BAM server components, you may start with this log level, and increase to FINER or FINEST, if needed.

FINER

TRACE:16

This log level enables the BAM Server components to write a fairly detailed debug information to the log file.

FINEST

TRACE:32

This log level enables the BAM Server components to write a highly detailed debug information.

Inherited from parent

 

Specify this value if you want a specific logger to inherit the log level from its parent logger.

The default setting for all BAM loggers is NOTIFICATION:1. For troubleshooting purposes, it is recommended to set the appropriate loggers to TRACE:1, TRACE:16, or TRACE:32.

The logging configuration is persisted in the following location on your BAM host: <domain_dir>/config/fmwconfig/ servers/<server_name>/logging.xml. Theoretically, you can edit this file to modify BAM loggers. However, it is not recommended to do so unless you have a good understanding of the configuration file. If you have multiple BAM instances in your environment, you can easily duplicate the logging configuration by copying the logging.xml file to all BAM instances, rather than making changes through EM.

Introducing the methodologies for troubleshooting BAM

Oracle BAM utilizes different technologies such as EMS, BAM Adapter, Web services, and ODI to integrate different enterprise information systems. Business data received from various data sources are then pushed all the way from the Active Data Cache, through the Report Cache and the Report Server, to Web browsers for rendering reports in real-time. Due to the complexity of the system and various technologies involved, it is critical to use the right troubleshooting methodologies to analyze and resolve issues.

The following are the basic rules of thumb for troubleshooting your BAM applications:

  • Understand the BAM key terminologies and architecture
  • Identify the problem
  • Set up BAM loggers
  • Collect the information and debugging

Understanding the key terminologies and the BAM architecture

Understanding the key terminologies and the BAM architecture is a prerequisite for troubleshooting the BAM applications. The key terminologies for BAM include Active Data, Active Data Cache, Report Cache, Report Server, ChangeList, Data Objects, Report, and so on.

Identifying the problem

Different issues may require different techniques to troubleshoot. For example, for a report design issue (for example, calculated fields do not show correct values), you should focus on the building blocks for the report design, instead of enabling loggings for the BAM server, which does not provide any help at all.

A BAM issue typically falls into the following categories:

  • Report design and report loading (static rendering)
  • Report rendering with Active Data (Active Data processing)
  • Issues with the key BAM Server components (Active Data Cache, securities, Report Cache, and Event Engine)
  • BAM Web applications (Active Viewer, Active Studio, Architect, Administrator, and Report Server)
  • Issues with BAM Integration Framework (EMS, Web services APIs, SOA Suite integration, and ODI integration)

To fully identify a problem, you need to first understand the problem description and the category to which the issue belongs. Then, you can gather relevant information, such as the time frame of when the issue happened, the BAM Server release information and patch level, BAM deployment topologies (single node or HA), and so on.

Setting up BAM loggers

Setting up BAM loggers with appropriate logging levels is the key for troubleshooting BAM issues.

BAM loggers can be set up to the following levels (Java logging): SEVERE, WARNING, INFO, CONFIG, FINE, FINER, and FINEST. In a normal situation, all the BAM loggers are set to INFO, by default. In the case of debugging, it is recommended to increase the level to FINER or FINEST.

Loggers contain hierarchies. You need to be careful when setting up root level loggers to FINE, FINER, or FINEST. Suppose that you want to troubleshoot a login issue with the BAM start page using the root logger oracle.bam.adc, which is set to FINEST. In this case, all the descendants that inherit from it have the same logging level. As a result, a large amount of unused log entries are produced, which is not helpful for troubleshooting, and can also impact the overall performance. Therefore, you should set up the corresponding child logger (oracle.bam.adc.security) without enabling the root logger.Collecting information and debugging.

Once the problem is identified and BAM loggers are set up appropriately, it is time to collect the logs to analyze the problem.

The following table lists the files that can be used to troubleshoot BAM issues:

Name

Description

<server_name>.out

This is the standard output file redirected by the Node Manager. If the server is started using the  tartManagedWebLogic.sh script directly, you need to refer to the standard output (either the command prompt output or another redirected file specified). This file is located in the following directory: <mserver_domain_dir>/servers/<server_name>/logs.

<mserver_domain_dir> refers to the domain home directory for the Managed Server for BAM; <server_name> refers to the name of the Managed Server for BAM, for example, WLS_BAM1.

Use this file to collect the server starting information and standard output.

<server_name>.log

This log provides information for the WebLogic Server that hosts BAM. This file is located in the following directory:

<mserver_domain_dir>/servers/<server_name>/logs.

<server_name>-diagnostic.log

Unlike the <server_name>.log file, this log file keeps a track of BAM-specific logs produced by BAM loggers.

The location of this file is as follows: <mserver_domain_dir>/servers/<server_name>/logs.

Debugging actually becomes easier once you have all this relevant information in place.

LEAVE A REPLY

Please enter your comment!
Please enter your name here