Weblogic daigonestic

(1)

Oracle WebLogic Server 11g:

Diagnostics and Troubleshooting

Volume I • Student Guide

D61523GC20 Edition 2.0 May 2011 May 2011 D72553

(2)

This document contains proprietary information and is protected by copyright and

Author

Bill Bell

y y y g

other intellectual property laws. You may copy and print this document solely for your own use in an Oracle training course. The document may not be modified or altered in any way. Except where your use constitutes "fair use" under copyright law, you may not use, share, download, upload, copy, print, display, perform, reproduce, publish, license, post, transmit, or distribute this document in whole or in part without the express authorization of Oracle.

The information contained in this document is subject to change without notice. If you find any problems in the document, please report them in writing to: Oracle University, 500 Oracle Parkway, Redwood Shores, California 94065 USA. This document is not

t d t b f Technical Contributors and Reviewers Will Lyons TJ Palazzolo Serge Moiseev

Editors _{warranted to be error-free.}

Restricted Rights Notice

If this documentation is delivered to the United States Government or anyone using the documentation on behalf of the United States Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS

The U.S. Government’s rights to use, modify, reproduce, release, perform, display, or disclose these training materials are restricted by the terms of the applicable Oracle

Editors

Richard Wallis Malavika Jinka

Publishers

Jobi Varghese

Shaik Mahaboob Basha

disclose these training materials are restricted by the terms of the applicable Oracle license agreement and/or the applicable U.S. Government contract.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

(3)

iii

Sun HotSpot Garbage Collection 6-10 Garbage Collection (GC) Types 6-11 Setting WLS JVM Arguments 6-12 Basic Sun JVM Arguments 6-13 JRockit Garbage Collection 6-14 Basic JRockit JVM Arguments 6-15 Out of Memory 6-16 Out-of-Memory Response 6-17 Memory Leak 6-18 JVM Crash 6-19 JVM Error Log 6-20 Section Summary 6-21 Road Map 6-22 JVM Tool Varieties 6-23 Java Stack Trace 6-24

Java Thread Dump: Overview 6-25 Thread Dump Signal 6-26

JVM Crash Actions 6-27 Verbose GC 6-28

Sun JVM Profiler Agent 6-29

Sun JVM Diagnostic Tools: Overview 6-30 Sun Diagnostic Tools: Examples 6-31 JVisualVM 6-33

Using JVisualVM 6-34 Section Summary 6-36

Practice 6-1 Troubleshooting a Running JVM 6-37 Road Map 6-38

Console JVM Monitoring 6-39 JVM WLST: Example 6-40

WLS Low Memory Detection 6-41 Configuring Low Memory Detection 6-42 Section Summary 6-43

Road Map 6-44

JRockit Diagnostic Tools: Overview 6-45 JRockit Diagnostic Tools: Examples 6-46 Management Communication 6-47 JRockit Mission Control (JRMC) 6-48 JRockit Discovery Protocol (JDP) 6-49

(8)

viii

JVM Browser 6-50

Management Console: Features 6-51

Management Console: General > Overview 6-52 Management Console: Runtime > Threads 6-53 Management Console: MBeans > Triggers 6-54 JRockit Flight Recorder (JFR) 6-55

Integration of JRockit Flight Recorder and WLDF 6-56 Starting the Flight Recorder from JRMC 6-57

Flight Recorder Output 6-58 General > Overview 6-59 Memory: Object Statistics 6-60 Code > Overview 6-61

Memory Leak Detector (Memleak): Features 6-62 Memleak: Trend Tab 6-63

Memleak: Type Graph 6-64 Section Summary 6-65 Quiz 6-66

Summary 6-70

Practice 6-2 Troubleshooting Applications on JRockit 6-71

7 Troubleshooting Java Applications

Objectives 7-2

Java Exception-Handling Concepts 7-3 Exception Chains 7-4

“Class Not Found” Errors 7-5 Class Cast Errors 7-6

Classpath: Review 7-7

WebLogic Start Script: Review 7-8 Viewing the WLS Classpath 7-9 Manifest Files and the Classpath 7-10 Domain Libraries 7-11

Java Class Loaders 7-12 Searching Class Loaders 7-13

Searching Class Loaders: Example 7-14 Default WLS Class Loader Hierarchy 7-15 Java EE Packaging: Review 7-16

Prefer Web Application Classes 7-17 Prefer Enterprise Application Classes 7-18 Client Library Errors 7-19

Null Pointer Errors 7-20 Stack Overflow Errors 7-21

(9)

ix

Too Many Open Files Errors 7-22 Quiz 7-23

Summary 7-25

Practice 7-1 Investigating Classpath Problems 7-26

8 Troubleshooting Servers

WLS Message Catalog: Review 8-4 Server Startup Errors 8-5

Boot Identity Errors 8-6 WLS Native Libraries 8-7

Setting the Native Library Path 8-8 Causes of Unresponsive Servers 8-9 WLS Threading Architecture 8-10 Execute Thread State 8-11 Work Managers 8-12

Work Manager Architecture 8-13 Creating a Work Manager 8-14

Creating and Using a Request Class 8-15 Assigning Work Managers to Applications 8-16 Monitoring a Server Thread Pool 8-17

Monitoring Individual Server Threads 8-18 Server Monitoring: WLST Examples 8-19 Server WLDF Image Contents 8-20 Java Deadlock Concepts 8-21 Thread Analysis 8-22

Lock Chains 8-23

Stuck Thread Detection 8-24 Overload Protection 8-25

Configuring Overload Protection 8-26 Section Summary 8-27

Practice 8-1 Investigating Server Problems 8-28 Road Map 8-29

WLS Deployment: Review 8-30 Deployment Errors 8-32

Application Staging 8-33

Deployment Memory Errors 8-34 Shared Library: Review 8-35 Library Errors 8-36

(10)

x

Application Error Handling 8-38 Application Monitoring: Review 8-39

Application Monitoring: WLST Examples 8-40 Section Summary 8-41 Quiz 8-42 Summary 8-45 9 Troubleshooting JDBC Objectives 9-2 JDBC: Review 9-3

Data Sources: Review 9-4

JDBC Management: WLST Examples 9-5 JDBC Runtime Attributes 9-6

JDBC Monitoring: WLST Examples 9-7 JDBC WLDF Image Contents 9-8 JDBC WLDF Monitor: Review 9-9 Data Source Diagnostic Profiling 9-10 Configuring Diagnostic Profiling 9-11 JDBC Debug Flags 9-12

Other JDBC Debugging Tools 9-13 Common Configuration Errors 9-14 Configuration Error Examples 9-15 Insufficient Connection Errors 9-16 Connection Leaks 9-17

Database Cursor Considerations 9-18 Common Connection Errors 9-19 Statement Timeout 9-20

Data Sources and Database Availability 9-21 Retry Frequency and Login Timeout 9-22 Connection Testing: Review 9-23

Testing Trusted Connections 9-24 Firewall Considerations 9-25 Multi Data Source: Overview 9-26 Multi Data Source: Architecture 9-27

Java Persistence API (JPA): Overview 9-28 JPA Configuration: Overview 9-29

Troubleshooting JPA: Overview 9-30 Quiz 9-31

Summary 9-34

(11)

xi 10 Troubleshooting JMS

Objectives 10-2 JMS: Review 10-3

WebLogic JMS Configuration: Review 10-5 JMS Transactions: Review 10-7

JMS Management: Overview 10-8 Console JMS Management 10-9

JMS Management: WLST Examples 10-10 JMS Runtime MBean Hierarchy 10-11 JMS Monitoring: WLST Examples 10-12 JMS Diagnostic Image Contents 10-13 JMS Message Logging 10-14

Configuring JMS Logging 10-15 JMS Debug Flags 10-16

Message Type Considerations 10-17 Common Configuration Errors 10-18 JMS Client Libraries 10-20

Out-of-Memory Errors and Quotas 10-21 Configuring a JMS Server Quota 10-22 Creating a Destination Quota 10-23 Message Paging 10-24

Too Many Pending Messages 10-25 Quota Blocking Policies 10-26 Thresholds and Flow Control 10-27 Configuring Thresholds 10-28 Tuning Flow Control 10-29 Lost Messages 10-30 Time to Live (TTL) 10-31 Expiration Policies 10-32 Delivery Mode 10-33 Message Redelivery 10-34 Time to Deliver (TTD) 10-35 Durable Subscriber Review 10-36

Monitoring and Managing Subscriptions 10-37 Duplicate Messages 10-38

Poison Messages 10-39

Consumer Acknowledgement Modes 10-40 Messages Out of Sequence 10-41

Unit of Order (UOO): Overview 10-42 Unit of Work (UOW): Overview 10-43

(12)

xii

MDB Capabilities 10-45

MDB Runtime Attributes 10-46

MDB Diagnostics and Debugging 10-47 Quiz 10-48

Summary 10-51

Practice 10-1 Investigating JMS Problems 10-52

11 Troubleshooting Security

Secure Sockets Layer (SSL): Review 11-4 SSL Communication: Review 11-5

WebLogic SSL Scenarios 11-6 Proxy Server SSL Scenarios 11-8 Keystore: Review 11-9 Trust Keystores 11-10 Keytool: Review 11-11 WebLogic SSL Support 11-13 SSL Configuration: Review 11-14 Restarting SSL 11-16 SSL Debug Flags 11-17 SSL Handshake Trace 11-18 Other SSL Traces 11-19

Invalid Format or Cipher Errors 11-20 Certificate Validation Errors 11-21 Host Name Verification Errors 11-22 Certificate Chains 11-23

WLS Chain Validation Utility 11-24 Missing Constraint or Policy Errors 11-25 Section Summary 11-26

Practice 11-1 Investigating SSL Problems 11-27 Road Map 11-28

Security Realm: Review 11-29 Security Provider Stores 11-30 Some Security Providers 11-31 Embedded LDAP: Review 11-32 Embedded LDAP Backups 11-33

Embedded LDAP Synchronization Issues 11-34 Viewing Embedded LDAP Contents 11-35 LDAP Concepts 11-36

(13)

xiii

LDAP Search Operations 11-38

Resetting Admin Password in Embedded LDAP 11-39 Database Store Cache Synchronization Issues 11-40 Auditing Provider 11-41

Security Audit Events 11-42

Configuring the Auditing Provider 11-43 Realm Debug Flags 11-44

Typical Authentication Trace 11-45 Typical Role Mapping Trace 11-47 Typical Authorization Trace 11-48 LDAP Trace Log 11-49

Authentication Provider Control Flags 11-50 External LDAP Authentication Providers 11-52 LDAP Provider Configuration: Overview 11-53 Common LDAP Issues 11-56

Section Summary 11-57 Quiz 11-58

Summary 11-62

Practice 11-2 Investigating Security Realm Problems 11-63

12 Troubleshooting Node Manager

Objectives 12-2

Node Manager (NM): Review 12-3 Node Manager Types: Review 12-4

Node Manager Configuration: Review 12-5 Basic Java Node Manager Properties 12-6 Java Node Manager Logging 12-7

Java Node Manager Availability 12-8 Basic Script Node Manager Interface 12-9 Node Manager Server Start Parameters 12-11 Configuring Server Start Parameters 12-13 Monitoring Node Managers 12-14

Node Manager: WLST Examples 12-15 Common Configuration Errors 12-16

Generating Template Properties for Java NM 12-17 Node Manager Authentication 12-18

Configuring Node Manager Credentials 12-19 Node Manager Trusted Domains 12-20 Machine Enrollment 12-21

Server Boot Identity 12-22

(14)

xiv

Practice 12-1 Investigating Node Manager Problems 12-27

13 Troubleshooting Clusters

Objectives 13-2 Road Map 13-3 Cluster Review 13-4 Proxy Plug-in Review 13-5

Obtaining and Using Plug-Ins 13-6 Oracle HTTP Server (OHS) Review 13-7

Oracle Process Manager and Notification Server (OPMN) Review 13-9 OPMNCTL Examples 13-10

OHS Logs 13-11

Plug-in Configuration Review 13-12 Basic Plug-in Parameters 13-13 Proxy Connection Architecture 13-14 Dynamic Server List 13-16

Connection Parameters 13-17 Common Connectivity Issues 13-18 Proxy SSL Issues 13-19

Proxy Debug Page 13-20 Proxy Debug Log 13-22 Typical Proxy Trace 13-23 Section Summary 13-24

Practice 13-1 Investigating Proxy Problems 13-25 Road Map 13-26

Cluster Communication Review 13-27 Unicast Architecture 13-28

Session Management Review 13-29 Session Persistence Review 13-30 In-Memory Replication Review 13-31 Cluster Monitoring WLST Examples 13-32 Session Monitoring WLST Examples 13-33 Session Monitoring Attribute 13-34

Session Instrumentation 13-35 Cluster Debug Flags 13-36

Typical Cluster Heartbeat Trace 13-37 Typical Replication Trace: Primary 13-38 Typical Replication Trace: Secondary 13-39 Common Replication Issues 13-40

(15)

xv

HttpSession API Overview 13-41 Serialization Overview 13-42

Serialization Debug Messages 13-43 Section Summary 13-44

Quiz 13-45

Lesson Summary 13-48

Practice 13-2 Investigating Cluster Replication Problems 13-49

A WebLogic SNMP

Simple Network Management Protocol (SNMP) A-2 SNMP Architecture A-3

Object Identifier (OID) A-4

Management Information Base (MIB) A-5 WLS MIB and OIDs A-6

Common SNMP Message Types A-7 WLS SNMP Architecture A-8

Creating an SNMP Agent A-10 Configuring an SNMP Agent A-11 SNMP Channels A-12

WLS SNMP Notifications A-13 Creating Trap Monitors A-14 Creating Trap Destinations A-15 SNMP Security A-16

Configuring Agent Security A-17

Configuring SNMP V3 Credentials A-18 Configuring Trap Destination Security A-19 WLS SNMP Utility A-20

(16)

(17)

Course Overview

(18)

Oracle WebLogic Server 11g: Diagnostics and Troubleshooting 1 - 2

Course Objectives

After completing this course, you should be able to:

• Monitor servers using the WebLogic Scripting Tool (WLST)

• Analyze a domain configuration by using Guardian

• Explain the capabilities of the WebLogic diagnostics

framework

• Configure diagnostic collectors and notifications

• Associate diagnostic monitors with custom applications

• Monitor memory usage with JRockit Mission Control

• Configure verbose logging for WebLogic subsystems

• Troubleshoot basic virtual machine, application server, and

cluster issues

(19)

If you are concerned about whether your experience fulfills the course prerequisites, ask the instructor.

Target Audience

• This course is intended for experienced WebLogic Server

administrators or those who have completed WebLogic

Server: Administration Essentials.

• Prerequisite skills include basic:

–

Administration Console navigation

–

WLST commands

–

JDBC and JMS configuration

(20)

Introductions

Introduce yourself.

Tell us about:

• Your company and role

• Your experience with WebLogic Server

(21)

The class schedule might vary according to the pace of the class. The instructor will provide updates.

Course Schedule

Day Lesson

1 AM WLST Monitoring Guardian

PM Diagnostic Framework Essentials Diagnostic Instrumentation

2 AM Diagnostic Instrumentation (continued) JVM Diagnostics

PM JVM Diagnostics (continued) Troubleshooting Java Applications Troubleshooting Servers

(22)

Course Schedule

Day Lesson

3 AM Troubleshooting JDBC PM Troubleshooting JMS

Troubleshooting Security

4 AM Troubleshooting Security (continued) Troubleshooting Node Manager PM Troubleshooting Clusters

(23)

Appendix A is intended to be additional reference material and will only be presented if time permits.

Course Appendix

(24)

Course Practices

• Each topic is reinforced with a hands-on exercise.

• Most exercises include a scripted solution to aid any

students who fall behind.

(25)

We hope that these guidelines help the class proceed smoothly and enable you to get the maximum benefit from the course.

Classroom Guidelines

• The instructor starts each session at the scheduled time.

• Do ask questions, but please be respectful of the topic at

hand and the interests of other students.

(26)

After you complete the course, Oracle provides a variety of channels for developers and administrators to access additional information.

For More Information

Topic Website

Education and Training http://www.oracle.com/education

Product Documentation http://www.oracle.com/technetwork/indexes/documentation Product Downloads http://www.oracle.com/technetwork/indexes/downloads Product Articles http://www.oracle.com/technetwork/articles

Product Support http://www.oracle.com/support/ Product Forums http://forums.oracle.com

Product Tutorials http://www.oracle.com/technetwork/tutorials Sample Code http://samplecode.oracle.com

(27)

Related Training

Course Title

Oracle WebLogic Server: Advanced Administration Oracle WebLogic Server: Monitor and Tune Performance

(28)

The Oracle by Example (OBE) series provides hands-on, step-by-step instructions on how to implement various technology solutions to business problems. OBE solutions are built for practical real-world situations, allowing you to gain valuable hands-on experience as well as to use the presented solutions as the foundation for production implementation, dramatically reducing time to deployment.

Oracle by Example (OBE)

OBE is a series of free online tutorials that cover specific

product features with step-by-step instructions.

(29)

WLST Monitoring

(30)

Objectives

After completing this lesson, you should be able to:

• Describe the relationship between JMX and WLST

• Compare the WLS MBean hierarchies

• Use some basic Jython and WLST commands

• Work with files, environment variables, and exceptions in

Jython

(31)

An Oracle WebLogic Server administration domain is a logically related group of Oracle WebLogic Server resources. Domains include a special Oracle WebLogic Server instance called the Administration Server, which is the central point from which you configure and manage all resources in the domain. Usually, you configure a domain to include additional Oracle WebLogic Server instances called Managed Servers. You deploy Web applications, EJBs, Web Services, and other resources onto the Managed Servers and use the

Administration Server for configuration and management purposes only.

You can use a single Oracle WebLogic Server installation to create and run multiple domains, or you can use multiple installations to run a single domain. How you organize your Oracle WebLogic Server installations into domains depends on your business needs. You can define multiple domains based on different system administrators’ responsibilities, application

boundaries, or geographical locations of the machines on which servers run. Conversely, you might decide to use a single domain to centralize all Oracle WebLogic Server administration activities.

For development or test environments, you can create a simple domain that consists of a single server instance. This single instance acts as an Administration Server and hosts the applications that you are developing.

WLS Domains: Review

Machine Product installation Domain A Server Server Domain B Server Machine Product installation Domain B Server Machine Product installation Domain A Admin server Admin server

(32)

A managed bean (MBean) is a Java object that provides a Java Management Extensions (JMX) interface. JMX is the Java EE solution for monitoring and managing resources on a network. Like SNMP and other management standards, JMX is a public specification and many vendors of commonly used monitoring products support it. WebLogic Server provides a set of MBeans that you can use to configure, monitor, and manage WebLogic Server

resources through JMX.

Each server in the domain has its own copy of the domain’s configuration documents (which consist of a config.xml file and subsidiary files). During a server’s startup cycle, it contacts the Administration Server to update its configuration files with any changes that occurred while it was shut down. Then it instantiates configuration MBeans to represent the data in the configuration documents.

Java Management Extension (JMX): Review

• All WLS configuration, management, and monitoring is

accomplished via JMX, which provides a standard Java

API for accessing management “objects” or MBeans.

• MBeans:

–

Are organized hierarchically

–

Can be accessed from remote systems

–

On the Administration Server act as proxies to MBeans on

managed servers

Managed server Admin server MBeans MBeans JMX client JMX client

(33)

All WebLogic Server MBeans can be organized into one of several general types. Runtime MBeans contain information about the runtime state of a server and its resources. They generally contain only data about the current state of a server or resource, and they do not persist this data. When you shut down a server instance, all runtime statistics and metrics from the runtime MBeans are destroyed. Configuration MBeans contain information about the configuration of servers and resources. They represent the information that is stored in the domain’s XML configuration documents.

All edits to MBean attributes occur within the context of an edit session, and only one edit session can be active at a time within each WebLogic Server domain. Changing an MBean attribute or creating a new MBean updates the in-memory hierarchy of pending configuration MBeans. If you end your edit session before saving these changes, the unsaved changes will be discarded. When you activate your changes, WebLogic Server copies the saved, pending configuration files to all servers in the domain. Each server evaluates the changes and

indicates whether it can consume them. If it can, it updates its active configuration files and in-memory hierarchy of configuration MBeans.

WLS MBean Hierarchies

• Every WebLogic Server hosts several different MBean

containers or “servers.”

• The Server Configuration hierarchy lets you view the

current configuration settings for resources.

• The Server Runtime hierarchy:

–

Lets you monitor resource statistics

–

Provides historical data since last server restart

• Administration servers also include an Edit Configuration

hierarchy to create, update, and delete configuration

MBeans for all servers in the domain.

(34)

As an alternative to using WebLogic Scripting Tool (WLST) to interactively browse a server’s runtime MBeans, you can use the online WebLogic Server MBean Reference guide.

1. Select the Runtime MBeans category in the tree found on the left. Select an MBean. 2. Then select a link to see information about that MBean.

When connecting to a managed server, the root of the runtime hierarchy is

ServerRuntimeMBean. From this MBean, you can then obtain references to all resources targeted to this server.

Configuration MBeans expose attributes and operations for configuring WebLogic Server resources. This reference document organizes configuration MBeans into the following categories:

• Domain Configuration MBeans, which configure clusters, server instances, containers

within the server (EJB and Servlet), and other services.

• System Module MBeans, which configure independently deployed modules that are

available as resources to all applications. These include JDBC, JMS, and diagnostic modules.

• Security MBeans, which configure WebLogic security providers and provide

security-related utilities such as listing and managing lockouts on user accounts.

WLS MBean Reference Documentation

• Each MBean consists of attributes and operations.

• All MBeans have a name attribute.

• Attributes may reference other MBean objects (children).

1

(35)

MBeans, like any Java objects, consist of attributes, which can be simple types such as Strings or doubles, or they can be other MBeans. In other words, MBeans can contain other MBeans and define a hierarchy of management objects. MBeans provide standard methods for managing these relationships, which are typically of the form createXYZ, destroyXYZ, or lookupXYZ, where XYZ is the type of child MBean. For example, the DomainMBean includes an operation named lookupServer(String name), which takes as a parameter the name that was used to create a server instance.

MBean interface can also include other arbitrary system operations that JMX clients can invoke remotely. For example, JMS destinations can be administratively paused, resumed, purged, and so on. Note that each attribute also has an implicit operation named get<name>, where <name> is the attribute name. For configuration MBeans that are not read-only, there may also be a matching set<name> operation.

WLS MBean Reference Documentation

3

Links to child MBean types

(36)

Every time that a resource, service, or application object can be monitored, a Monitoring tab is available in the console for that object. Clicking it shows you the available monitoring

information for the selected object. Moreover, when the monitoring page shows information in tabular format, you may change the way that the information is displayed. To do this, click “Customize this table” and choose which columns to display and on what columns to sort the table.

One way to determine which MBean types and attributes correspond to the displayed columns is by using the context-sensitive Help link found at the top of the console. For each column, the Help page provides a description and the corresponding MBean information. You cannot monitor the activity of one domain through another domain. For example, you cannot open the Administration Console for domain Y and try to monitor servers within domain Z.

Console Monitoring: Review

Monitoring tabs

View console Help to determine corresponding MBeans.

(37)

After connecting to a running server, the serverRuntime() WLST command navigates to the last MBean to which you navigated in the runtime MBean hierarchy or to the root of the hierarchy, ServerRuntimeMBean. This read-only hierarchy stores the runtime MBeans that represent the server to which WLST is currently connected.

You may then use all of the standard WLST browsing commands such as cd(), get(), and ls()to navigate the runtime MBean hierarchy for a server and to retrieve the desired

attributes.

WebLogic Scripting Tool (WLST): Review

• WLST provides a command-line and scripting interface for:

–

Creating new WLS domains

–

Retrieving and updating WLS domain configurations

–

Deploying applications

–

Obtaining runtime server statistics

• With WLST, navigating MBean hierarchies is similar to

navigating folders on a file system.

connect('user','password','myhost:7001')

serverRuntime()

jvm = getMBean('/JVMRuntime/server1')

print 'Free Heap: ' , jvm.getHeapFreePercent()

wm = getMBean('/WorkManagerRuntimes/weblogic.kernel.Default') print 'Pending: ' , wm.getPendingRequests()

(38)

In the WLST file system, MBean hierarchies correspond to drives; MBean types and

instances are directories; MBean attributes and operations are files. In WLST, you traverse the hierarchical structure of MBeans by using commands such as cd(), ls(), and pwd() in a way similar to how you would navigate a file system in a UNIX or Windows command shell. For example, to navigate back to a parent configuration or runtime bean, enter cd('..'). To get back to the root bean after navigating to a bean that is deep in the hierarchy, enter

cd('/'). After navigating to an MBean instance, you interact with the MBean using WLST commands.

WLST MBean Syntax: Review

Access a child MBean from a parent by using the child’s name

attribute.

getMBean('/JMSRuntime/ServerC.jms/JMSServers/HRJMS/Destination s/BenefitsJMSModule!SyncBenefitsQueue') JMSDestinationRuntime Name: BenefitsJMSModule!SyncB enefitsQueue JMSServerRuntime Name: HRJMS JMSDestinations: <list> JMSRuntime Name: ServerC.jms JMSServers: <list>

(39)

Server runtime MBeans expose monitoring, runtime control, and the current configuration settings (read-only) of a specific WebLogic Server instance.

Some runtime MBeans are only available on the Administration Server, such as several types of security MBeans. Access these “domain-wide” MBeans by using the domain runtime

hierarchy. This MBean server also acts as a single point of access for MBeans that reside on other managed servers within the same domain.

If your client monitors runtime MBeans for multiple servers, or if your client runs in a separate JVM, Oracle recommends that you connect to the domain runtime MBean hierarchy on the Administration Server instead of connecting separately to the runtime MBean hierarchy on each server instance in the domain. Your script then only needs to construct a single URL for connecting to the domain runtime hierarchy on the Administration Server, instead of working with multiple address/port combinations.

Using the domain runtime hierarchy, you can also route all administrative traffic in a domain through the Administration Server’s secured administration port. Additionally, you could use a firewall to prevent direct connections to managed server administration ports from outside some network boundary.

Domain Runtime

• Use the

serverRuntime()

command to monitor a single

server.

• Alternatively, use the

domainRuntime()

command to

monitor the runtime hierarchy of multiple servers via the

admin server.

Server Admin Server WLST WLST Server Server Server

(40)

Jython programs start with the first line of code that is not commented, not indented, and is not a function definition (def keyword). Leading white space (spaces and tabs) at the

beginning of a logical line is used to compute the indentation level of the line, which in turn is used to determine the grouping of statements. First, tabs are replaced (from left to right) by one to eight spaces so that the total number of characters up to and including the

replacement is a multiple of eight (this is intended to be the same rule as used by UNIX). The total number of spaces preceding the first non-blank character then determines the line’s indentation. Indentation cannot be split over multiple physical lines by using backslashes; the white space up to the first backslash determines the indentation.

Jython is an interpreted language. As a result, the developer is not required to declare the variable types at design time. The Jython interpreter assigns the types at run time. However, each type object has an application programming interface (API), and if the API of one object is used by your code and the type has been assigned by the interpreter to another type at run time, the interpreter throws an exception at run time. Ensure that the correct API is used based on the type that you expect to assign to an object at run time.

Basic Jython Syntax: Review

list = ['ab','cd','ef'] if len(list) >= 3:

for x in list:

print 'length: ', len(x) print 'done'

else:

print 'list too small'

Conditional expressions For loop def doSomething(value): i = 1 while i <= 5: if value.endswith(str(i)): print 'invalid:' + value break i += 1 ... doSomething('mypassword5') List variable While loop Function definition String concatenation Print a number. Use indentation to define code blocks.

(41)

WLST enables you to navigate a hierarchy of MBeans in a similar fashion to navigating a hierarchy of files in a file system. For example, to navigate back to a parent MBean, enter the cd('..')command.

In the WLST file system, MBean hierarchies correspond to drives, MBean types and instances are directories, and MBean attributes and operations are files. In WLST, you traverse the hierarchical structure of MBeans by using commands such as cd(), ls(), and pwd()in a way similar to how you would navigate a file system in a UNIX or Windows command shell.

After navigating to an MBean instance, you can interact with the MBean using other WLST commands, such as get(), set(), and invoke(). The built-in variable cmo is set to the current MBean each time you change directory. With this variable, you can perform

operations directly against the current management object. However, an alternative approach is the getMBean() command, which returns the management object for a given WLST path. Unlike cd(), getMBean() does not change the current path pointed to by cmo.

Basic WLST Commands

Command Description

connect() Connect to a server by using supplied credentials. disconnect() Disconnect from the current server.

getMBean() Retrieve the MBean object at the given location.

cd() Navigate to the MBean at the given location and update

the current management object (cmo) global variable.

ls() Print the attributes and values of the cmo MBean. pwd() Print the current location in the MBean hierarchy. startEdit() Begin a new change session.

activate() Commit all changes in the current session. deploy() (Re-)Deploy an application to servers.

(42)

Parameterize your WLST scripts. Provide variables defined and initialized in a preamble at the top of the script. This practice promotes reuse and can aid in troubleshooting.

Alternatively, you can define variables in a separate text file and import them as variables by using the loadProperties WLST command, as in the following example:

loadProperties('c:/temp/myLoad.properties')

Variable Declaration

• Use variables in scripts, instead of hard-coding MBean

attribute values.

• Declare variables at the top of scripts so that they can be

easily modified.

# Variable definitions url = 'localhost:7020' username = 'user' password = 'password' dsName = 'MyDS' targetName = 'MyServer'

connect(username, password, url) ...

jdbcSystemResource = create(dsName, 'JDBCSystemResource') targetServer = getMBean('/Servers/' + targetName)

(43)

The storeUserConfig() command creates a user configuration file and an associated key file for the identity of the current user you are connected to WLS with. The user configuration file contains an encrypted username and password. The key file contains a secret key that is used to encrypt and decrypt the username and password. Only the key file that originally encrypted the username and password can be used to decrypt the values. If you lose the key file, you must create a new user configuration and key file pair. If you do not specify file names or locations, the command stores the files in your home directory as determined by your JVM. The location of the home directory depends on the SDK and type of operating system on which WLST is running. The default file names are

<username>-WebLogicConfig.propertiesand <username>-WebLogicKey.properties. If you do not specify credentials as part of the connect() command, and a user

configuration and a default key file exists in your home directory, then the command uses the credentials found in those files. This option is recommended if you use WLST in script mode because it prevents you from storing unencrypted user credentials in your scripts.

Alternatively, you can provide the specific locations and names of these files by using the userConfigFileand userKeyFile command arguments.

Password Management

To avoid using plain text credentials in your scripts, do one of

the following:

• Require them as command-line arguments.

• Prompt the user to enter them.

• Create and use an encrypted password file.

Connect to a server using the current password file: connect(url=myurl)

...

Create encrypted password file for previously used credentials: connect(username, password, myurl)

storeUserConfig() Stored in OS user’s home directory by default

File retrieved from the home directory by default

(44)

The first example shows the use of a try/except block as part of creating a new server resource, such as a JDBC data source. The try/except block is used while attempting to navigate to a specific configuration MBean with the cd() command. If this code block succeeds without an exception, the MBean already exists and the script is terminated. If an exception is thrown (the expected case), the rest of the script is executed to create the new resource. The Python “pass” statement is a required placeholder, although it performs no actual work.

The second example shows how similar functionality can be accomplished using the getMBean()command. Unlike the cd() command, getMBean() does not throw an exception if the given MBean is not found.

The use of print statements to inform the user of script progress and successful completion is also a good practice.

Error Handling

• Before reading, updating, or deleting resources, confirm

that they exist.

• Before creating new resources, confirm that they do not

already exist.

try:

cd('/JDBCSystemResources/' + dsName)

print 'The JDBC Data Source ' + dsName + ' already exists.' exit()

except WLSTException: pass

jdbcSystemResource = create(dsName, 'JDBCSystemResource')

ds = getMBean('/JDBCSystemResources/' + dsName) if ds != None:

(45)

Jython includes a built-in file type and a built-in function open() for creating variables of this type. In addition to supplying the file name and path, you can optionally indicate a mode ('r', 'w', 'a', for reading, writing and appending, respectively). In append mode, all write operations are appended to the end of any existing file contents. The mode flag can also include a 't' or 'b' suffix to indicate text or binary mode. In text mode, newline characters are automatically converted to the current platform's line terminator, and vice versa.

The read() command reads until the end of the file or up to a specified number of bytes, and returns a string. If a size is not indicated, the whole file is read. This command returns an empty string if the end of the file has been reached. The readline() command is similar, but also stops reading if a line terminator is found. Finally, the readlines() command returns a list of strings.

The write() command writes the supplied string to the file, and the writelines() command writes a list of strings to the file.

File I/O

• Jython includes standard file operations.

• Consider writing script output to log files instead of to the

standard output stream.

outfile = open('script.log','w') ...

outfile.write('Server State: ' + server.getState() + '\n') outfile.close() infile = open('data.in','r') line = 'temp' while len(line) != 0: line = infile.readline() ...

(46)

The sys module includes some general purpose global variables. The sys.argv variable is a list that contains the command-line arguments passed to the Jython interpreter. The

expression argv[0] evaluates to the script name.

The os module provides a portable way of using operating system–dependent functionality. For example, the os.environ variable is a map object that provides access to system environment variables. This module also has listdir(), makedir(), rename(), and rmdir()functions. If you simply want to read or write a file, use the built-in open() function. If you want to manipulate system paths, see the os.path module instead.

Jython includes several modules for working with times and dates. The time module, for example, includes a sleep() function.

Standard Jython Libraries

import sys targetServer = sys.argv[1] timeout = sys.argv[2] ... import os if os.environ.has_key('APP_HOME'):

os.rename(filename, filename + '.bak') ... Command-line arguments Environment variables Create or rename files.

import time as jythontime

jythontime.sleep(10) ...

Avoid collision with the

weblogic.time Java package.

Pause the program (seconds).

(47)

The example in the slide connects to a server and prints the values of various JMS runtime MBean attributes every 60 seconds. The loop is written so that it runs indefinitely, until the process is terminated. In this example, the WLST script connects to and disconnects from the server each time data is collected. Connection creation is a relatively expensive operation, so this approach can have an impact on the script’s or server’s responsiveness. Alternatively, create an initial connection, reuse it, and automatically re-create it if the connection ever fails.

WLST Example: Monitor a JMS Server

server = 'serverA' jmsserver = 'DefaultJMSServer' while true: connect('user','password','myhost:7001') serverRuntime() jms = getMBean('/JMSRuntime/' + server + '.jms/JMSServers/' + jmsserver)

print 'Messages: ' , jms.getMessagesCurrentCount() print 'Pending: ' , jms.getMessagesPendingCount()

disconnect() time.sleep(60)

(48)

Answer: a, c , d, e

Quiz

Name four valid Jython keywords.

a.

def

b.

deploy

c.

try

d.

for

(49)

Answer: c

Quiz

Which is not a WLST command included in a WLS installation?

a.

connect()

b.

cd()

c.

move()

d.

ls()

(50)

Answer: d

Quiz

What WLST command is necessary to monitor the health or

performance of WLS resources?

a.

serverConfig()

b.

redeploy()

c.

startEdit()

d.

serverRuntime()

e.

validate()

(51)

Summary

In this lesson, you should have learned how to:

• Describe the relationship between JMX and WLST

• Compare the WLS MBean hierarchies

• Use some basic Jython and WLST commands

• Work with files, environment variables, and exceptions in

Jython

(52)

Practice 2-1

Connecting to the Classroom Grid

This practice covers the following topics:

• Identifying your classroom virtual machine (VM) instance

• Connecting to a classroom virtual machine by using an NX

client

(53)

Practice 2-2

Developing a Custom Monitoring Script

This practice covers the following topics:

• Initializing a sample domain

• Navigating the WLS runtime MBean hierarchy

• Retrieving and displaying MBean attributes

(54)

(55)

Guardian

(56)

Objectives

After completing this lesson, you should be able to:

• Explain the purpose of a Guardian agent

• Install and update Guardian

• Generate domain inventories and evaluation summaries

• Browse problem signatures, bundles, and remedies

• Use Guardian to help generate a support request

(57)

Oracle Guardian is a diagnostic tool for identifying potential problems in your environment before they occur, and then providing specific instructions for resolving them. Using Guardian is like having the entire Oracle Customer Support team scrutinize your domain and

immediately present its findings and recommendations to you at your convenience.

Each Guardian installation maintains a registry of active domains. A domain is considered active when it is capable of being evaluated. You can activate and deactivate domains at will, and select which to evaluate at any given time. You can also organize the domains in

Guardian into domain groups for easier management.

When you conduct an evaluation that detects a problem pattern or “signature,” you can create a service request directly from a selected signature in an evaluation summary. Guardian creates and saves the service request data as a service request archive for later submission to Oracle Support.

Guardian Capabilities

Oracle Guardian:

• Is like a virus scanner for WebLogic Server

• Checks domains for common configuration and runtime

problems and then recommends solutions

• Includes graphical and command-line interfaces

• May also scan other Oracle products running on WLS

• Is free to those who have an Oracle support account

(58)

As you develop an application and migrate from development to quality assurance to production, you can run an evaluation at each stage. Guardian will help ensure that each phase of your development process is compliant with Oracle best practices. After you update an existing application, you can run an evaluation to assess the deployment. Guardian will help you find any potential problems that could impact your upgrade. If Guardian earlier detected a signature, and you subsequently applied the remedy or made other changes to your system, you can run an evaluation to confirm that the signature is no longer detected and no new issues were introduced.

After you install a new Oracle patch, service pack, or upgrade, or install or upgrade third-party software, you can run an evaluation to identify any new issues that may have been

introduced.

Some signatures are designed to evaluate runtime domain settings. Running an evaluation under heavy load can detect potential problems that would not otherwise be detected. Oracle recommends conducting these evaluations during load and performance testing. If you are concerned about domain settings being incorrectly changed overnight, or if your domain is approaching certain resource limits, you can schedule evaluations to run overnight. You can review the Evaluation Summary in the morning and decide if any detected signatures merit further investigation.

Using Guardian

Use Guardian to evaluate domains:

• After their initial creation and setup

• As part of each development cycle, prior to production

• After any Oracle patch or service pack has been applied

• After introducing or upgrading any third-party software

• Periodically in production (each night, for example)

(59)

The Guardian agent is a lightweight Web application that gathers the data used for

evaluations. It collects data from the server via JMX, from the JVM, and inspects application resources such as deployment descriptors.

Both graphical and command-line Guardian clients are available. The first time you launch the Guardian interface it will generate a workspace folder. Guardian stores all settings,

preferences, domain inventories and domain evaluations in this workspace. To perform an evaluation, the Guardian client communicates with the agents deployed on your servers. The Guardian repository contains the locally persisted store of problem signatures available for evaluation. When you download signatures from the Guardian update site, they arrive in a Java Archive (JAR) file. The JAR file is stored in the repository/archives directory of your Guardian installation directory.

To safeguard your domains, Guardian requires valid login credentials for all communications between Guardian and your Guardian domains. Whenever you conduct an evaluation or activate a domain, Guardian prompts you for the username and password of an Administrator or Monitor account on the target domain.

SSL encryption is available for all communication with Oracle over the Internet and for all communication with Guardian agents in your target domain(s).

Guardian Architecture

Guardian client GUI or script Domain HTTP(S) Admin server Guardian agent JMX Managed server Guardian agent JMX Domain Oracle Support Repository

(60)

To quickly deploy the Guardian agent Web application bundled with your WebLogic Server installation:

1. Launch the console and select the domain name in the Domain Structure panel. 2. Select the Enable Oracle Guardian Agent check box and click Save.

3. Restart all servers in your domain.

The Guardian agent included with WLS can be found at <WL_HOME>/server/lib/bea-guardian-agent.war. If a new version of the agent becomes available, you can simply replace this file and perform an application update, or delete the application deployment and reinstall the new file. Do not change the default name of the Guardian agent when deploying it manually.

Agent Installation

• A Guardian agent (.war) is bundled with WLS.

• Either deploy the agent manually to each server or use the

shortcut option available in the console.

• Update and redeploy the agent as new versions become

available from Oracle Support.

2

1

(61)

Collected Data

During an evaluation, the following types of data are collected

by the agent:

• JMX (configuration and runtime)

• Application deployment descriptor settings

• JVM system properties

(62)

1. Install Guardian:

a. Launch guardian_installer.exe/bin.

b. Select the location in which to install Guardian. Accept the default, or click Choose to open a file browser from which you can select a location. If you already have Guardian installed, be sure to install it to a different location from that of the previous Guardian installation.

c. Review your installation details and click Install to proceed. d. Click Done to dismiss the wizard.

2. Launch Guardian and select a Workspace location. The workspace is the directory in which all of your Guardian data is stored, including user preferences, domain

inventories, and domain evaluation summaries. To prevent loss of work when Guardian is updated or uninstalled, select a workspace location outside of the Guardian

installation directory.

If you select the “Use this as the default workspace and do not ask again” check box, Guardian will use the current location from then on when starting. To resume opening the Select Workspace dialog box at startup, select the “Prompt for workspace on startup” check box in the “Startup and Shutdown” section of the Guardian Preferences menu.

Client Installation

• Download the client installer from the Oracle Support site

(Windows or Linux).

• An existing JVM (1.5 or later) must be in the OS path

before you run the installer.

• Launch Guardian and select a workspace location in which

to store user preferences and evaluation data.

2

(63)

The main Guardian toolbar is located below the main menu bar and contains action buttons for the most common Guardian tasks. You can place your cursor over a button to get a brief description of its functionality. The Open button opens the current selected entity in one of the tabs, such as a domain inventory, evaluation summary, or signature. These resources are shown in separate tabbed document panels on the right side of the interface (by default). To print the contents of the current active document panel, use the Print button.

The navigation pane in Guardian resides on the left side of the interface and contains several tabs to access various explorer panels. The Domain Explorer view enables you to browse, manage, and monitor the domains you have registered with Guardian. The Signature Explorer view allows you to browse the problem signatures in Guardian’s repository and view their details.

Explorer and document panels contain title bar buttons and can be individually maximized, minimized, or closed as needed. You can also drag and drop panels to reorder them. These types of customizations are automatically saved in your workspace for subsequent Guardian sessions.

The online help for Guardian provides a detailed overview of the tool’s capabilities. However, for specific instructions on using the client interface, use Guardian’s integrated Help system (available from the main menu).

Guardian User Interface

View domain inventories and evaluations. Browse all problem signatures. Main toolbar Browse signatures by bundle. Create shortcuts for commonly performed actions.

(64)

1. Either click the Activate button in the main toolbar or select File > New > Domain from the main menu.

2. On the General tab, enter the following:

- Protocol: Select “http://” or “https://.” Oracle recommends using the SSL

encryption (“https://”) option for communication between Guardian clients and agents. Guardian utilizes open source, 128-bit encryption.

- Host Name: This is the listen address for the domain’s Administration Server.

- Port Number: This is the listen port for the domain’s Administration Server.

- Username/Password: A domain account that has administrator or monitor

privileges

- Remember Username/Password: Store the supplied credentials securely in the

Guardian workspace to avoid entering them for every subsequent task.

Activating a Domain

Activating a domain:

• Registers the domain in your workspace

• Generates an initial domain inventory using the agent

1

2

Location of admin server

(65)

After activating a domain, a node is added to the Domain Explorer view, in the Target Domains folder. An initial domain inventory entry is also added to the domain node’s Inventory History folder. Double-click an inventory to view its details in the document pane.

To explicitly create a new inventory file for a domain:

1. Either click the Inventory button in the main toolbar or select File > New > Inventory from the main menu.

2. Select one of the available activated domains. If prompted, also specify the Username/Password to access this domain.

To compare two domain inventories:

1. Within the Domain Explorer, expand the Inventory History folder for a domain. 2. Select two inventory files using the Ctrl or Shift keys.

3. Right-click the selected items and select Compare. A document panel then highlights the differences between the two files. Various box and connector shapes are used to indicate content that has been added, removed, or updated. Right-click within this panel to see additional display options.