Universal Logging System

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== ULS-Agent for Oracle Weblogic =====

Aka the WLS_TOOLS, is the [[http://www.gnu.org/licenses/gpl.txt|GPLv3]]-based ULS-agent for gathering runtime metrics 
and status information about Oracle WebLogic servers 
running on Unix-like operating systems.

==== Overview ==== 

The [[wls_tools]] consists of several python/wlst scripts and bash scripts to:

  * gather runtime metrics of an Oracle WebLogic Server instance

It requires WLST to run and the [[:uls:agents:linux]] for data transmission to the ULS-server.

All results and/or reports are generated as ULS value files in the [[uls:agents:value_file_format]]
which are sent to the ULS-server by using the [[:uls:agents:linux]].

The WLS_TOOLS are a collection of scripts that can monitor 
an Oracle Weblogic server regularly.
It is currently used only on Unix-like operating systems.

Start and stop scripts for an Oracle Weblogic server (cold standby) cluster package 
in conjunction with the SCript-CLuster are provided, see :TODO:.

The monitoring script uses the WLST, but only reads metrics. 
No extra user is needed but the "weblogic" account is used.
Usage of a more restrictive user is currently under development.

All results and/or reports are sent to the ULS-server for 
analysis and monitoring.

-----

==== Installation ====

=== Overview ===

  * be sure to have installed an uls-client-2.x or later :ref:`uls_client_for_linux` 
  * copy the :file:`WLS_TOOLS_{yyyy-mm-dd}.zip` to ~weblogic/WLS_TOOLS/
  * extract :file:`WLS_TOOLS_{yyyy-mm-dd}.zip`
  * find or create a script to set the proper Oracle Weblogic server environment, e.g. :file:`weblogic_env`
  * create the crontab entries


=== Preparations ===

Login to your server where you want to use the WLS_TOOLS
and try this command to check for the necessary ULS-client:

<code bash>
$ whereis flush_test_values
flush_test_values: /usr/local/bin/flush_test_values
</code>

If not, you must install or update the ULS-client first, see :TODO:.

Login as the user "weblogic"
(the owner of the software installation and the user that can connect as weblogic)
change to its home directory and create a sub-directory:

<code bash>
$ mkdir WLS_TOOLS
$ cd WLS_TOOLS
</code>

Download the the current version of the WLS_TOOLS 

:TODO:`WLS_TOOLS_2012-03-29<WLS_TOOLS_2012-03-29.zip>`

If you got that file in the software depot of your ULS-server 
you can use the commands to download the zip-archive from there.

Check the checksums by using one of these:

<code bash>
$ md5sum WLS_TOOLS_*.zip
$ sha1sum WLS_TOOLS_*.zip
$ cksum WLS_TOOLS_*.zip
</code>

:TODO: add the checksums

Unpack the zip-archive:

<code bash>
$ unzip WLS_TOOLS_*.zip
Archive:  WLS_TOOLS_2012-03-29.zip
  inflating: watch_wls.py
  inflating: watch_wls.sh
  inflating: sccl_wls_startstop
  inflating: README.txt
  inflating: COPYING.txt
  inflating: zip_it.txt
</code>

A directory listing should look like:

<file>
$ ls -al
-rw-------   1 weblogic   oinstall     32473 Feb  2  2012 COPYING.txt
-rw-------   1 weblogic   oinstall      1033 Nov 22  2011 README.txt
-rw-r--r--   1 weblogic   oinstall     22110 Nov  1 11:41 WLS_TOOLS_2012-03-29.zip
-rwx------   1 weblogic   oinstall       378 Aug 24  2011 sccl_wls_startstop
-rw-------   1 weblogic   oinstall     28967 Mar 29  2012 watch_wls.py
-rwx------   1 weblogic   oinstall      1616 Nov  1 11:52 watch_wls.sh
</file>

Be sure to have a script (e.g. `weblogic_env`)
that sets the necessary environment 
for the Oracle Weblogic server. At least needed are the following:

<code bash>
# That is needed
WL_HOME=/oracle
export WL_HOME

ADMIN_PORT=7001
export ADMIN_PORT
</code>

=== Customization ===

You **must** customize the script 'watch_wls.sh' to your needs!

Set the correct server name. 
That may be the hostname (default if not set) or a cluster name:

<code bash watch_wls.sh>
  # -----
  # set environment
  . ~weblogic/wls_env
  if [ $? -ne 0 ] ; then
    echo
    echo "Error: Cannot source Oracle's environment script '~weblogic/wls_env'"
    echo
    exit 1
  fi
  
  # -----
  # Set environment variables

  export ULS_HOSTNAME=`hostname`
</code>

Check also the othe possible settings in the `watch_wls.sh` like:

  * ULS_DATA_CACHE (directory to place the resulting ULS value files)
  * ULS_SECTION ("Weblogic Server" is the default, the domain will be appended like "Weblogic Server [domain]")
  * ADMIN_PORT (may also be set in the environment script)
  * WLS_ADMIN_URL (complete url to the admin server)


=== Credentials ===

See also: `Security for WLST <http://download.oracle.com/docs/cd/E12840_01/wls/docs103/config_scripting/using_WLST.html#wp1093630>`_.

Enter the credentials on the command line, 
then use the storeUserConfig command to create a user configuration file 
that contains your credentials in an encrypted form and a key file 
that WebLogic Server uses to unencrypt the credentials. 
On subsequent WLST sessions (or in WLST scripts), supply the name of the file 
instead of entering the credentials on the command line. 
This option is recommended if you use WLST in script mode because 
it prevents you from storing unencrypted user credentials in your scripts.

For example, to create the user configuration file and key file:

<code bash>
$ cd ~weblogic/WLS_TOOLS/
$ $WL_HOME/common/bin/wlst.sh

Initializing WebLogic Scripting Tool (WLST) ...

Welcome to WebLogic Server Administration Scripting Shell

Type help() for help on available commands

wls:/offline>
</code>

.. code-block:: python

  wls:/offline> connect('weblogic', 'welcome', 'localhost:7001')
  wls:/domain/serverConfig> storeUserConfig('./wls_watch_configfile.secure', './wls_watch_keyfile.secure')

  Creating the key file can reduce the security of your system if it is not kept in a secured location after it is created. Do you want to create the key file? y or ny
  The username and password that were used for this WebLogic Server connection are stored in ./wls_watch_configfile.secure and ./wls_watch_keyfile.secure.

  wls:/domain/serverConfig> exit()

These files should have been created in the current directory
and they are then automatically used in the monitoring script.

A directory listing should now look like:

.. code-block:: bash

  $ ls -al
  -rw-------   1 weblogic   oinstall     32473 Feb  2  2012 COPYING.txt
  -rw-------   1 weblogic   oinstall      1033 Nov 22  2011 README.txt
  -rw-r--r--   1 weblogic   oinstall     22110 Nov  1 11:41 WLS_TOOLS_2012-03-29.zip
  -rwx------   1 weblogic   oinstall       378 Aug 24  2011 sccl_wls_startstop
  -rw-------   1 weblogic   oinstall     28967 Mar 29  2012 watch_wls.py
  -rwx------   1 weblogic   oinstall      1616 Nov  1 11:52 watch_wls.sh
  -rw-r-----   1 weblogic   oinstall       227 Nov  1 12:48 wls_watch_configfile.secure
  -rwxr-x---   1 weblogic   oinstall        64 Nov  1 12:48 wls_watch_keyfile.secure

Try the script:

.. code-block:: bash

  $ ./watch_wls.sh

Check the log file:

.. code-block:: bash

  $ more  


Usage
-----------------------------------------------------------
Universal Logging System

User Tools

Site Tools

Page Tools
