TIBCO BWPM Server Administration Guide. TIBCO ActiveMatrix BusinessWorks Process Monitor Server. Administration Guide

Transcription

1 TIBCO ActiveMatrix BusinessWorks Process Monitor Server Administration Guide Software Release Published: May

2 Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE LICENSE FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO, The Power of Now, TIBCO ActiveMatrix BusinessWorks, TIBCO Rendezvous, TIBCO Administrator, TIBCO Enterprise Message Service, TIBCO InConcert, TIBCO Policy Manager, and TIBCO Hawk are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM. THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON- INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. Copyright TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information 2

3 Contents Preface... 5 Introduction... 6 TIBCO BWPM Server... 6 Architecture... 6 Configuration... 8 Connections... 9 Database... 9 JMS Data Providers Overview Configuration System Management (minimal configuration) Runtime configuration User Management Manage Users Adding and Deleting Users Granting and Revoking Permissions Manage Passwords Manage Roles Adding and Deleting Roles Granting and Revoking Permissions System Management Status Unused Objects Database Data Providers Trace Settings Starting / Stopping System TIBCO BWPM Server

4 Starting TIBCO BWPM Server on Windows Starting TIBCO BWPM Server on UNIX Stopping TIBCO BWPM Server Data Processing Logging Loglevel Access Logfile Utilities Overview RegEx Tester Advanced topics Configuration files BWPM minimal configuration file Authentication Logging Performance considerations RAM CPU Database Log level Size of messages Amount of data / retention period NJAMS_T_ACTIVITY_STATISTICS NJAMS_T_STATISTICS and NJAMS_T_STATISTICS_HOUR

5 Preface This document explains the configuration and administration of TIBCO BWPM Server. See the TIBCO BWPM Server User Guide for information about how users can work with the TIBCO BWPM Server GUI. 5

6 Introduction This chapter gives an overview about the TIBCO BWPM Server and its architecture. TIBCO BWPM Server The TIBCO BWPM Server is the core component of any BWPM installation. It is responsible for processing log messages and providing user access to the logged data. Log messages are received via JMS and stored into the BWPM database. They originate from TIBCO BWPM Clients, which exist for various technologies. The clients use built- in or configurable rules to generate and send log messages. Users can view all available log information by logging in to the TIBCO BWPM Server GUI. See the TIBCO BWPM Server User Guide for information about how users can work with the TIBCO BWPM Server GUI. Architecture The TIBCO BWPM Server is a web application running inside the application web server. It is made up of several modules; the picture below gives a high level and simplified overview on its most important modules. When the TIBCO BWPM Server is started, it will check its configuration settings and start all configured Data Providers. A Data Provider is responsible for reading log messages from a channel (such as JMS) and 6

7 storing those messages in the underlying database. For each Data Provider the BWPM administrator can configure how many instances should run in parallel (A) and the channel to read data from (B). Some tuning settings are available, depending on the channel configured for the Data Provider. When using JMS, for example, the BWPM administrator may configure the JMS prefetch property to optimize JMS processing (C). When a log message is processed by the Data Provider, the Data Provider hands it over to the persistence layer of the TIBCO BWPM Server. The persistence layer connects to a RDBMS and accomplishes read and write operations against the BWPM database. The persistence layer is using a JDBC connection pool (D), which is shared between the Data Providers and GUI Services. The GUI Services are used by end users and process user requests The TIBCO BWPM Server GUI is a web browser based AJAX applications. 7

8 Configuration This chapter explains the configuration options available to the administrator. The system is configured using the TIBCO BWPM Server GUI and various property files. The GUI based administration is available to members of the admin role only. After login, the BWPM administrator can choose one of the topics available from the Administration category for configuration. For a minimum configuration of the TIBCO BWPM Server you need to configure: JDBC connection (typically done during installation) JMS connection Data Provider Run Config After having configured these settings, you can start data processing. 8

9 Connections The Connections node of the Administration category allows configuring the database (JDBC), JMS and mail server (SMTP) connections. must be configured. For proper operation of TIBCO BWPM Server the JDBC connection and at least one JMS connection must be configured. The mail server configuration is optional; however, if users should be notified by the system automatically, or be able to reset their (lost) passwords using the TIBCO BWPM Server GUI, the SMTP connection Database The database connection is configured during the initial setup of the TIBCO BWPM Server. See the TIBCO BWPM Server Installation Manual for more information. If you need to change the JDBC settings after the initial installation, first you have to stop all running Data Providers. See chapter Data Processing for more detail on this. Data Providers have to be restarted, after you have updated the JDBC configuration. When selecting the JDBC node of the Administration category, the following wizard is displayed: 9

10 The wizard has two pages: JDBC settings and DB. Note: After the initial setup of the TIBCO BWPM Server you should make changes to the first page only. Settings on the second page of this wizard are only used if you wish to recreate the database. The first page let you change the following settings: JDBC Driver: chose from Oracle Thin or Microsoft SQL Server. JDBC Driver Class: for Oracle use oracle.jdbc.driver.oracledriver, for Microsoft SQL Server use com.microsoft.sqlserver.jdbc.sqlserverdriver Connection Type: chose from Simple or JDBC_URL; when the Simple option is selected, you can enter a database name, port and service identifies (SID) in the text boxes below the Connection Type field. This configuration is best suited for installations where only a single, non- HA/FT database is connected to BWPM. 10

11 Use JDBC_URL to configure a more complex connection string: The JDBC URL should be used to configure more complex connection strings, and control parameters such as cluster strings, address lists, etc. You can also refer to a TNSNAMES.ORA entry for more details. Please see the corresponding Oracle documentation 1 or Microsoft MSDN article 2 for more information on how to use this (recommended) connection type. Examples: Oracle: jdbc:oracle:thin:@localhost:1521:orcl MS SQL Server: jdbc:sqlserver://localhost:1433;databasename=adventureworks; Database Server: if Connection Type Simple is chosen, enter the fully qualified domain name of the database server, or its IP address. DB Server Port: if Connection Type Simple is chosen, configure the database listener port number. SID (Oracle only): if Connection Type Simple is chosen, set the Oracle database s system identified here. Username: the database user to be used by TIBCO BWPM Server to login to the database Password: the above user s password Database Schema: TIBCO BWPM Server allows to store its database objects in another schema than the database user s default schema. In most cases this value is identical to the user name. Ask your database administrator for the correct value to use. Use Partitions (Oracle only): if your database does support partitions, it is recommended to check this option. Installations with a very high number of log entries will see significant performance benefits, when using partitions. Check with your DBA for the availability of this option. Please note, this cannot be changed after installation. In this release, the setting has no effect on MS SQL Server based installations. Connection Pool Size: set the size of the JDBC connection pool. Note: the connection pool is used both for writing and reading data from the database. Hence it is recommended to set this value to <number of data provider threads> + 5 * < average amount of concurrent GUI users> You can test the updated settings by clicking on the Test Connection Settings button. 1 Oracle Database URLs and Database settings: 2 Building the Connection URL for MS SQL Server us/library/ms378428%28v=sql.90%29.aspx 11

12 The Save Settings button will test and save the connection settings in one go. If you just wanted to update the JDBC connection settings, and do not want to re- create the database, simply click on Save Settings. The changes come into effect immediately. Once the new settings are saved, you can restart the data providers. If you want to re- create the database, the second page of the wizard allows you to set the (logical) name of the BWPM Instance, and create a BWPM administrator user and password: After filling in the BWPM Instance information, you can either download the SQL file that contains all database statements for re- creating the BWPM database, or create the database directly. Database objects will be created in the schema configured on the first page of the wizard under Database Schema. In case you do not have a database user with sufficient privileges to create the required database objects (tables, indices, etc) or you want to inspect or change the contained DDL (for example to configure database storage options, etc), you can download the file to your local computer. To do so, click on the 12

13 Download File button. You can inspect, edit, make changes as necessary and forward the file to your DBA to execute it. Pressing the Create Database will result in the re- creation of the BWPM database objects. Before the script is executed, however, you will be prompted to enter valid credentials for a database user that has sufficient privileges to drop and re- create the BWPM database objects. The system will run the script and display the results. The most common reasons for potential failures during the database creation process are: Insufficient privileges: the database account used for database creation does not have sufficient privileges to create the required database objects in the database schema. Check the TIBCO BWPM Server Installation Guide for a list of the required privileges and grant the missing privileges, or switch to another user. Feature not available: you have checked Use Partitions on page one of the wizard, but your database does not support partitions. In that case return to page one, remove the option and retry, or ask your DBA to enable partitions for your database instance. Once the database is created, you will be logged out from the system automatically. You can now log in with the BWPM administrator account you configured on page two of the wizard. JMS The JMS connections are referenced by the Data Providers. When the system is installed, two default JMS connections are created; a queue connection and a topic connection. You may modify or delete the existing entries, or create new entries. When selecting the JMS node in the Administration accordion, a list of available connections is shown. 13

14 You may also directly select a connection from the Administration tree; this has the same effect as selecting the connection from the JMS connection list and pressing the Edit button. Note: JMS connections referenced by currently running Data Providers cannot be edited or deleted. When creating a new entry the following dialog is displayed: From top to bottom you need to fill in all fields of the dialog: Name: the logical name of the connection. JMS connections are referenced by their name from Data Providers. It is recommended to choose a descriptive name that indicates the type of connections and connected JMS server. Provider URL: enter the JMS provider URL. Fault tolerant URLs are supported. Refer to your JMS provider s manual for the correct URL to use. Note: if you choose the JNDI option, enter a JNDI server URL here; if you decided to not use JNDI, enter the JMS server connection URL, instead. 14

15 Use JNDI: if checked, the connection will use JNDI to lookup the connection URL; if unchecked, the JMS destination type (Topic or Queue) must be chosen manually. Connection factory: the name of the connection factory to query the JNDI server for. Provider context factory: the Java class name for the initial context factory. For TIBCO Enterprise Message Service, set this value to: com.tibco.tibjms.naming.tibjmsinitialcontextfactory Username: the user name to use for this connection. This user will also be used for JNDI authentication. Password: the user s password To validate the settings made, press the Test connection button. Once the settings are validated, click on the Save settings button. Cancel discards all changes and closes the dialog. If you have unchecked the Use JNDI options, the dialog changes: All JNDI related settings are removed from the dialog and replaced by the Destination Type option. You have to select either Topic or Queue for this connection. Note: If you create a connection for a Topic destination type, you will be allowed to configure a durable subscriber for the Data Providers referencing this connection. The system may send messages. For example, a user can request a password reset at the login page. This will trigger an being sent to his mailbox, containing a URL to reset the password. To enable notifications, the administrator must configure a SMTP connection. 15

16 SMTP is the only protocol supported for communication. The SMTP connection must be configured as follows: Server URL: the name or IP address of the SMTP server Server Port: port of the SMTP server Enable TLS: enable this option to encrypt traffic between the SMTP and TIBCO BWPM Server Username: if the SMTP server requires authentication, enter a valid user name here. Leave it empty, if your SMTP server does not require authentication Password: the SMTP server user s password Reply address: the s sent by BWPM will use the value configured here as the sender s address s cannot be sent to the TIBCO BWPM Server. Data Providers A Data Provider is an internal TIBCO BWPM Server module that receives log messages via its referenced (JMS) connection and parses, validates and stores data into the BWPM database. Overview In a standard setup BWPM connects to a single JMS server and receives log messages from a single JMS destination. However, if you want to monitor multiple TIBCO BusinessWorks domains, you may have to connect to multiple JMS servers to receive all log messages. Or you may have to collect log messages from more than one JMS destination. Depending the scenario chosen, you may have to configure one or more Data Providers. The chapter Runtime configuration explains how to configure a Data Provider and to start it. 16

17 Configuration When the system is installed, two default Data Providers are created. One uses a queue and the other one uses a topic connection. You may modify or delete the existing entries, or create new entries. When selecting the Data Provider node in the Administration accordion, a list of all configured Data Providers in the TIBCO BWPM Server is shown: You may also directly select a Data Provider from the Administration tree; this is the same as selecting the Data Provider from the Data Providers list and pressing the Edit button. Note: Running Data Providers cannot be edited or deleted. When creating a new entry the following dialog is displayed: 17

18 Fill in all fields of the dialog: Name: the name of the Data Provider. It is recommended to choose a descriptive name that hints on the Data Provider s configuration. Destination: the base of the JMS destination name to use. If the connection referenced by the Data Provider uses JNDI, the destination name will be used in the JNDI lookup. The base name will be suffixed with event, error and command tokens. Hence, a base name of BWPM will result in the three destinations BWPM.event, BWPM.error and BWPM.command to be used by this data provider. Their purpose is as follows: - event: the Data Provider expects log messages at this destination. - error: if the Data Provider encounters any error while processing messages, those error messages will be moved to this destination - command: this destination is used to send command messages to the BWPM Clients. Create Destination: check this option, if you want the TIBCO BWPM Server to create the destination in the JMS server. The supplied user account must have sufficient privileges on the server and destination to do so. Thread Pool Size: the number of threads this Data Provider can use to process inbound log messages. Increase this number, if you experience backlogs on message processing and the TIBCO BWPM Server is not CPU bound. Data Provider Class: this cannot be changed and can be safely ignored for this release. 18

19 Use durable subscriber: if the configured JMS connection is of type Topic, the Data Provider will create a durable subscriber on the JMS Topic. BWPM however will not delete durable subscribers created automatically, when a Data Provider is deleted or reconfigured! You have to remove the durable subscriber(s) manually. JMS Connection: select any of the configured JMS connections for this Data Provider to use. To save the new or updated Data Provider, click on the Save settings button. System Management (minimal configuration) The System Management node of the Administration tree grants access to the Run Config, Trace Settings, System Status and Logfile. This chapter will only discuss the Run Config. See chapter System Management for a full description of all System Management features. Runtime configuration The Runtime configuration of the TIBCO BWPM Server is used to activate and deactivate Data Providers. Any activated Data Provider will be started by the server automatically, if the hosting application server is restarted, or when the (Re)Start button is pressed. Selecting the Run Config from the Administration tree will open the Data Provider Cockpit: 19

20 The cockpit has two lists: the activated Data Providers on the left, and the available Data Providers on the right. You can move one or more entries from one list to the other by using the buttons between the lists. Right beneath the lists, the main status of the TIBCO BWPM Server is shown. A green triangle indicates that the TIBCO BWPM Server has started all activated Data Providers, while a red square indicates that data processing has been halted. Note: if a Data Provider experiences an unrecoverable error while running (i.e. it was disconnected from the JMS server), the TIBCO BWPM Server status is not changed to stopped, but stays running. To check the status of individual Data Providers, please see the Status page. If you changed the list of activated Data Providers, you have to restart the data processing by clicking on the (Re)Start button. To halt all data processing, press the Stop button. A change in configuration can be saved; without a restart of the data processing, however, the change will not be applied (i.e. Data Providers will not be started or stopped). Finally, at the bottom of the dialog, you can configure the log level of the TIBCO BWPM Server. Select an appropriate log level from the list and press the set log level button to immediately change the log level. Note: trace and debug log levels will produce a lot of log file entries quickly. After you finish tracing or debugging an issue revert the log level for the application to INFO to produce fewer entries in the log file. 20

21 User Management The User Management allows the administrator to manage users, roles and access rights. The User Management module is located in the Administration category: Manage Users To access the User Management, navigate to the Users node in the Administration Tree. This will open a list of available users in right side of the window. 21

22 Adding and Deleting Users Users can be edited, created and deleted using the corresponding buttons underneath the list. When creating a user you must supply a user name (which will act as the login id) and password. Optionally a comment can be added and a time interval that constraints the new user s validity be configured. Once created, the username cannot be changed afterwards. Select the Roles tab on top of the dialog to configure the new user s role memberships. 22

23 Once the user is created, a personal role of the same name as the user is created in the system and the user is added to that role automatically. Each user is a member of his own role. To edit a user you can either select it straight from the Administration Tree, or mark the entry in the list on the right side and click the Edit button. All changes to role memberships come into effect immediately then the user entry is saved. Users are not required to logout and login for these changes to be applied to their BWPM session. Select a user entry in the users table and press the Delete button to delete it. Confirm the delete request when prompted: Note: The admin user cannot be deleted. Granting and Revoking Permissions Permissions are managed via roles. To grant or revoke permissions from a user, the permission must be configured for a role the user is member of. To grant a permission to a single user, only, configure the permission for the user s personal role (a role that has the same name as the user; it gets created automatically when a new user is created). Manage Passwords When creating a user, an initial password must be set. That password should be changed by the new user after his first login. The password can be changed either by an administrator or by the user using the Profile dialog: 23

24 The user can change his first and last name (required for personalized s, etc), update the address and change the password. Also the user may configure which BWPM view should be presented when logging in to the system. 24

25 Manage Roles To access the management interfaces for roles, navigate to the Roles node in the Administration Tree. This will show a list of available roles on the right side of the window. 25

26 Adding and Deleting Roles Roles can be edited, created and deleted using the corresponding buttons underneath the list. When creating a new role, you must supply a name and a time interval that constraints the new role s validity. Once the role is created, privileges can be configured (see Granting and Revoking Permissions for more information) and user added. To edit a role you can either select it straight from the Administration Tree, or mark the entry in the list on the right side and click the Edit button. All changes to roles come into effect immediately when saved. Users are not required to logout and login for these changes to be applied to their BWPM session. To delete a role entry it must be selected from the users table and the Delete button must be pressed. Confirm the delete request when prompted: Note: 26

27 The admin role cannot be deleted. Granting and Revoking Permissions To grant or revoke access rights for a certain domain object an administrator can assign three different privileges to each role and domain object: Read: a role with this privilege can access all process instances relating to this domain object. All reports and statistics displayed to the user including this domain object. Data: the user is granted the right to access all data collected automatically by a BWPM Client. This includes data generated by trace points and detailed stack traces; such trace point and stack trace data may include sensitive information and hence access is protected by this privilege. Manage: a user with this privilege is entitled to manage trace points (enable, disable, set duration). To update a role s privileges navigate to the Privileges tab of the Role Edit dialog. Then navigate to the domain object you want to manage a privilege for. Privileges are assigned using a hierarchical order. If a privilege is granted or revoked on a higher level, it will be granted or revoked on all its child elements. For example: granting the Manage privilege to the fs_dev domain (see picture above) will grant the privilege to its entire domain objects (Deployments, Engines and Processes) automatically. 27

28 In order to assign users to roles, select the Users tab and mark all users that should be members of that role. To remove a user from a role, uncheck the entry. Then save the changes using the Save settings button at the bottom of the table. 28

29 System Management This chapter will explain the functions available within the TIBCO BWPM Server GUI that allow an administrator to understand the current status and health of the BWPM system. All functions introduced here can be reached by navigating to the System Management node and sub nodes in the Administration tree. Status When selecting the System Management node or its Status sub node an overview about the current status of the system is presented to the administrator: At the top of the page the following information is shown from left to right, general server information (A) and summary of active users (B) and domain objects (C). The server information has the name of the BWPM instance, its uptime (since the BWPM web application was started) and the database instance it is connected with. The summaries of active users and domain objects show the current and past activities. You can click on the numbers of each line to get a list of users or domain objects that have been active or inactive in the given timeframe. 29

30 The bottom section (D) shows the state of the database jobs required by BWPM. At a glance the administrator can check the state (on/off), the most recent and next planned execution time and the interval the job is scheduled at. The middle section (E) lists all Data Providers configured in the system. This section shows the state of each Data Provider and its current level of activity. Unused Objects In the two top sections (B) and (C) the administrator can find information about how many users are using the system currently and in the past; by clicking on a number, a list of all active/inactive users will be shown to the administrator. The same information is available for Domain Objects. In large installations it can become quite hard to find out which domain objects are still in use. Based on the information provided here, the administrator will be able to better manage privileges and data retention for domain objects. Database BWPM is using a set of database jobs for routine tasks. These jobs manage data retention (delete data after expiration) and aggregate statistical information used by the various reports of the TIBCO BWPM Server GUI. All jobs must be enabled (Run status must be ON ) all the time. If a database job experiences issues repeatingly, the database will disable the job; its status will be shown as OFF and the row be highlighted in red: 30

31 The table lists all jobs required by the TIBCO BWPM Server. It shows their last and next run date, status, interval, current error count and name of the stored procedures they call. The database will increase the error count by one for every subsequent failure during a job execution. It is reset to zero, if a next run of the job executes successfully. The Oracle RDBMS will disable a job when the error count reaches 16. You can pick the next run date manually for a job by clicking into the Next Run Date column for the job. This will open a date picker to choose the next run date. By clicking on the Run Status switch, you can manually disable and enable a job. If the database has disabled a job, contact your DBA to understand the underlying issue. Once the issue has been removed, you can restart the job. NJAMS_JOB_DATA_MANAGEMENT This job runs daily at midnight (00:00). It is responsible for deleting expired data and dropping table partitions, as well as creating new partitions for partitioned tables. If the database was created without the partitioning option enabled, the database job deletes all entries relating to a certain domain object based on the policy current date retention period. That means, if the retention period is 1 day, and the current date is :00:00, all data that is older than :00:00 will be deleted. Consequently, when logging in to the system on :00:00, data from :00:00 until then will be shown. Data relating to should not be visible, though. Data is deleted in batches of records. In large installations this database job can run multiple minutes, or even few hours. When using partitioning in the database, the database job will check for the MAXIMUM retention setting of ALL domain objects. For example: Process1.process has a retention setting of 1 day, Process2.process has a retention setting of 2 days. If the current date is :00:00, the job checks for the MAX setting (2 days) and drops all partitions older than :00:00. If a user logs in to the system on :00:00 he will see data from both Process1.process AND Process2.process relating to dates after :00:00. As opposed to delete data row by raw, dropping a partition takes few milliseconds, hence using partitions is the recommended setup. Please note that this job will only delete data relating to process instances. It will not delete domain objects or other data from the database. Hence, even if this job deleted all data of process instances of a 31

32 particular domain object, the domain object will still be available in the technical view. You can use the filter buttons in the technical and business view to filter for active domain objects. NJAMS_JOB_STATISTICS This job runs every minute and produces by- the- minute aggregated statistical data for all domain objects that have been processed since it ran the last time. This job is expected to run for a few seconds, only, even in high load scenarios. NJAMS_JOB_STATISTICS_HOUR Every five minutes the statistical data created by the database job NJAMS_JOB_STATISTICS is aggregated into hourly information. This job is expected to run for a few seconds, only, even in high load scenarios. NJAMS_JOB_CHECK_TRACE_SETTINGS This database job purges expired trace settings from the database. It is only visible in the UI, if a trace point has been configured. It is created when a user enables a trace point; it runs exactly once and is scheduled for the expiration date and time of the next due trace point. For example, if a trace point is enabled to last until :00:00, this job will run at the specified time and remove itself from the database. If, however, another trace point is enabled before this job ran and the new trace point expires before the original due date of this job, the job is rescheduled to run at the new trace point s expiration time. The job will check for the next due trace setting and reschedule itself to run at that time. In this release you cannot change the interval of the jobs using the GUI. Ask your DBA to set the interval to any value that suits your situation better (i.e. reschedule the data management job to a time when there s less load on the database). It is not recommended to change the interval of the statistic jobs (PROC_STATISTICS and PROC_STATISTICS_HOUR). Data Providers At the bottom of the page all Data Providers configured for this BWPM Instance are listed. The list shows the current state of the Data Provider (running / stopped), its name, uptime, processed messages since last restart, total errors since last restart, number of messages on the error queue, last message processing time, destination length, the send timestamp of the oldest JMS message on the destination (Queues only) and the last activity timestamp of the data provider: 32

33 The list can be sorted and filtered. It is informational, only. In order to start or stop a Data Provider, please refer to chapter Runtime configuration. Trace Settings Trace points are set in the process diagram. BWPM provides a summary of the tracing settings for the administrator to know which trace point has been set in which process and whether it is active or not. The administrator can choose to enable or disable a trace point and change the validation time interval or the maximum number of traces (Limit) to be collected for a trace point. Starting / Stopping System TIBCO BWPM Server The TIBCO BWPM Server is a standard web application running inside a web application server; starting the web application server and the BWPM web application ensure the TIBCO BWPM Server is up and running. Starting TIBCO BWPM Server on Windows Example with Tomcat as a web application server: the Tomcat server has been registered as a Windows service, the corresponding Windows service must be started. Alternatively, the Tomcat server can be started from the command line as follows: Open a DOS prompt and navigate to the Tomcat bin directory. Then run the Tomcat startup script startup.bat. 33

34 Note: your Tomcat installation home may vary! Open the web browser and navigate to the following URL: where - - BWPM_SERVER is the name of the server running the Tomcat server which hosts the BWPM web application PORT is the port of the Tomcat server (default is 8080) If you can see the login page, the server has been started. Starting TIBCO BWPM Server on UNIX On Unix change the current directory to the Tomcat bin directory and run the startup script startup.sh. Note: your Tomcat installation home may vary! Open the web browser and navigate to the following URL: 34

35 where - - BWPM_SERVER is the name of the server running the Tomcat server which hosts the BWPM web application PORT is the port of the Tomcat server (default is 8080) If you can see the login page, the server has been started. Stopping TIBCO BWPM Server To stop the TIBCO BWPM Server the Tomcat server (or the BWPM web application) must be stopped. If the Tomcat server has been registered as a Windows service, the corresponding Windows service must be stopped. In all other cases navigate to the Tomcat bin directory and run the stop script shutdown.bat (Windows) or shutdown.sh (Unix). Data Processing When the Apache Tomcat and the BWPM web application are started, the TIBCO BWPM Server will automatically start all activated Data Providers. You can validate the run status by navigating to the Run Config node in the Administration tree. The Data Provider Cockpit will show the current server status: If the status is stopped, you can start the Data Providers by clicking the (Re)Start button. 35

36 You can stop all Data Providers by pressing the Stop button. Note: even if the server s status is stopped, the TIBCO BWPM Server GUI will be fully functionally. However, new log messages will not be processed until the Data Providers are started. Logging The TIBCO BWPM Server will write log information to the TIBCO BWPM Server logfile located at <TOMCAT_WEBAPPS>\BWPM\WEB-INF\logs\BWPM.log. You can change all aspects of the log file using the log4j.properties file located at <TOMCAT_WEBAPPS>\BWPM\WEB-INF\data}log4j.properties. Loglevel The log level can be changed in two ways: either by directly updating the log level in the log4j.properties file (the TIBCO BWPM Server will pick up the changes configuration immediately), or by using the GUI. In the Administration tree navigate to System Management - > Log Files. At the top of the dialog you can select your preferred log level from the pick list. Press update to activate the new setting immediately: The default log level is INFO. If you change this setting to a more aggressive level (debug, trace), a lot of data will be written to the log file. This can have an impact on the server s overall performance, and may fill up the disk space rapidly! Access Logfile The most convenient method to work with the log file is to inspect it using the TIBCO BWPM Server GUI. Navigate to System Management Logfile to display the most recent 100 kb of the log file. By pressing the + and - buttons you can increase and decrease the amount of data that should be displayed in steps of 100 kb. Also, the file can be downloaded in total (select the disc symbol), or the view refreshed: 36

37 Note: depending on your log level the size of the log file can become quite large. The default setting is INFO, and the default Log4j appender used is a DailyRollingFileAppender. Consider this when downloading the entire log file to your computer. 37

38 Utilities This section discusses the various utilities available for the BWPM administrator. Overview All utilities can be found in the Utilities node of the Administration tree: This release has one utility, only: the regular expression tester. RegEx Tester When configuring a BWPM Client for BW the user or administrator may configure rules that extract data from the engine s inbound event stream. See the BWPM Client for BW User Guide for more information on this feature. The RegEx Tester in the TIBCO BWPM Server GUI allows the BWPM administrator to quickly test such rules for correctness. Also, it will automatically provide the correct format of the regular expression to be put into the configuration file of the BWPM client: 38

39 To use the RegEx Tester, the BWPM administrator can type or paste the event stream s data (of which attributes should be extracted from) into the text box in the upper half of the dialog. Next, a regular expression can be typed in to the Pattern field. The line below (In Java) will show the correctly escaped expression that must be placed into the BWPM Client s configuration file. After providing the data and regular expression, pressing the Check regex pattern on text button will run the regular expression; results are displayed in the bottom field. If the text in the Result field is green, the regular expression produced a match, which is displayed inline the text. In the screenshot above the user provided a regular expression to extract the value of an XML element CityName from an XML document. Note: the tester will always return the first match a regular expression produces, only. If your regular expression would return more than one match, the remaining matches are ignored (and so they are by the BWPM Client!). 39

40 Advanced topics Configuration files Almost all configuration information is stored in the database. However, there are three files that hold additional configuration information. The BWPM.minimal.config.properties file holds the very limited information required by the TIBCO BWPM Server to connect to its database. Authentication mechanisms are based on Jaas and are configured in the java.login.config file. Finally, the Log4j configuration can be found in the log4j.properties file. BWPM minimal configuration file This file holds the very minimum information required by the TIBCO BWPM Server to connect to its database. It is created during the initial configuration of the system, which is part of the TIBCO BWPM Server installation process. Any change made to the JDBC settings using the TIBCO BWPM Server GUI will be saved into this file. You can edit this file at your discretion. Any manual change, however, will only come into effect by restarting the BWPM web application. The file can be found at this location: <TOMCAT_WEBAPPS>\BWPM\WEB-INF\data\njams.minimal.config.properties Authentication The TIBCO BWPM Server uses Jaas for its authentication routine. By default users connecting to the TIBCO BWPM Server GUI are authenticated via the built- in authentication routine of BWPM. Using Jaas you can configure the TIBCO BWPM Server to authenticate users using any other authentication mechanism you want. Jaas The Jaas configuration file can be found at: <TOMCAT_WEBAPPS>\BWPM\WEB-INF\data\java.login.config If you want BWPM to authenticate users not using the internal mechanisms but, for example, an LDAP server, you can add the following sample configuration to the Jaas configuration file: com.sun.security.auth.module.ldaploginmodule REQUIRED userprovider="ldap://ldap-svr1 ldap://ldap-svr2" authidentity="cn={username},ou=people,dc=example,dc=com" authzidentity="staff" debug=true; Follow this link to learn more about the LdapLoginModule that comes with Oracle Java: 40

41 oginmodule.html Note: when you configure Jaas to use a different authentication mechanism than the built- in one, you still have to create users and roles and manage privileges using the BWPM user management. BWPM cannot be configured to synchronize with external LDAP servers in this release. The user you create in BWPM must match their configured identity entry in your LDAP server. Logging BWPM uses Log4j for logging. By configuring the log4j system, you can control where and how log files are created and managed. Log4j The Log4j configuration file is located at: <TOMCAT_WEBAPPS>\BWPM\WEB-INF\data\log4j.properties. Please refer to the official Log4j documentation on how to configure the log4j system. Performance considerations Improving and maintaining an adequate performance of the TIBCO BWPM Server is important because: 1) If the server is not able to process all inbound messages at the rate they arrive at the server, a backlog will build up (inside the JMS server). In a worst case, the server will never catch up with the amount of data being created and the backlog grows infinite. Eventually the JMS server will run out of resources, which may lead to a loss of (log) messages or other outages. 2) If the server is under heavy load the GUI will become less responsive. The TIBCO BWPM Server s performance is constrained by RAM, CPU and the database. RAM The server caches search results in memory. This speeds up navigating in result sets, such as filtering or paging the main table. Also, of two identical queries the second will be served from RAM, rather than querying the database. The more RAM the Server has available, the more data it can cache. CPU Log messages arriving at the server need to be parsed from their XML structure into Java objects. This process consumes CPU and typically is the predominant consumer of CPU. It is the responsibility of the Data Providers to receive, parse and store the log messages in the database. Since Data Providers are multi- threaded (see chapter Data Providers for more detail), adding more threads to a Data Provider may improve the server s performance (if the server is not CPU bound and the database has not become 41

42 the bottleneck). Check your server s CPU consumption and coordinate with your DBA to validate that more threads for Data Providers could improve the overall performance of the server. Database When looking into database related performance, we need to distinguish between client and server side. In this context TIBCO BWPM Server acts as the database client, and the database instance itself is the server. JDBC Connection Pool The BWPM administrator can configure the JDBC connection pool size. Almost every interaction with the TIBCO BWPM Server GUI results in one or more (simultaneous) database accesses. Also the Data Providers use the configured connection pool to store date in the database (processing the inbound event stream from the BWPM clients). As long as the TIBCO BWPM Server s host does not run out of CPU and the database can respond to request without delay, increasing the connection pool size can lead to faster data processing. As a rule of thumb the value for the connection pool should be <number of data provider threads> + 5 * < average amount of concurrent GUI users> Database tuning BWPM collects and stores a lot of data into its database. Every received log message needs to be stored in the database, which results in a high write pressure to the database s data files (redo logs, dbf files, etc). Secondly, the TIBCO BWPM Server GUI requires reading a lot of data from the database, depending on the users interactions. And finally, expired data must be deleted from the system as quickly as possible. When available, BWPM uses the partitioning feature of the underlying database. This helps in dramatically reducing the effort it takes for the database to read data, as it better understands where the data is located that should be read. Also, deleting expired data is implemented in BWPM by the means of dropping expired partitions. When you feel the system is becoming too slow, check with your DBA where the bottlenecks are, and try to fine tune them. In general the system will benefit from (unsorted order): Partitioning being enabled data files being located on different devices redo logs and archives to being located on different devices multiple LGWR processes Log level The more granular the log level is set to, the less the overall performance of the TIBCO BWPM Server will be. TIBCO BWPM Server will produce a lot of log data, if the log level is set to DEBUG or TRACE. Make 42

43 sure to use this log levels only when absolutely required and revert them back to INFO or WARNING as soon as possible. Size of messages The amount of data transported by a log message also affects performance. The more data is contained in a message, the longer its processing will take. When configuring your BWPM Clients make sure to collect information as efficiently as possible (for example: in a loop do not send a message or create an event per iteration, but collect results and send them in a single message / event). Please refer to your BWPM Clients User Guides for more information on how to efficiently log information. Amount of data / retention period The more data that needs to be managed by the system, the slower the system will get (especially the TIBCO BWPM Server GUI is affected from big data volumes). Always set the retention period for your data to the shortest possible time. A user can improve his experience with the TIBCO BWPM Server GUI by querying the system as precisely as possible. For example: instead of searching for every process instance recorded by BWPM in the last 48h (which may produce quite a large result set that takes long to read from the DB, transfer and render in the browser), limit the search to a specific status, domain object and smaller time window. The following tables are constantly growing and are not purged by the system automatically. It is advised to frequently purge data from these tables, once they are not required by users (i.e. external reporting engines): NJAMS_T_ACTIVITY_STATISTICS This table contains statistical information about execution times (and more) for every executed activity of a process. The data is required by the njams server for 48h, after which it can be deleted safely. NJAMS_T_STATISTICS and NJAMS_T_STATISTICS_HOUR These tables hold statistical information about processes execution times, etc. The BWPM server also uses data in this table to optimize its search strategy (for faster search results). Data from these tables can be deleted, only after the configured retention period of the related domain object has expired. 43