APPMUser Manual

Version 2.6.1

Table of ContentsOverview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1

Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1

Installation Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1

Minimum System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1

Graphical User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1

Linux service installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  2

Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3

Graphical Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5

Performance / Active History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5

Performance / Active Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9

Performance / Blocked Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9

Performance / Locked Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10

Performance / SQL Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10

SQL Patch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11

SQL Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  12

ASH Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  12

Graphical Interface Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  13

Session Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  13

SQL Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  14

Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  17

OverviewAPPM is Oracle database management and performance tuning tool. It offers similar functionalityas Oracle ASH, but it also works on Standard and Express Edition, where Oracle ASH is notpermitted. Special attention is dedicated to locking and SQL tracing.

Features• overview of problematic SQL statements with current execution plans

• simple analysis of Oracle trace files

• control of database performance

• problems diagnostics

• performance optimization

Installation Guide

Minimum System Requirements

Operating System Linux or Windows

RAM 1GB

HDD 30GB

CPU 2 core

Supported Oracle database versions are 11g and 12c, any edition.

Graphical User InterfaceYou may use portable version, which can be run using just JDK8:

java -jar appm-swarm.jar

Or you may install it on full featured wildfly using following instructions.

Install JDK

• Download Oracle JDK 1.8 (OpenJDK is not supported, use Oracle JDK)

• Install to /opt/abakus/java/jdk8/. On Windows, use default installation directory when possible.

1

Linux (as root):

cd /opt/abakus/java/tar zxvf jdk-8u151-linux-x64.tar.gzln -s jdk1.8.0_151 jdk8

Windows (as Administrator):

run jdk-8u151-windows-x64.exe (you may use default installation options)

Install WildFly

• Download Wildfly 11.0.0.Final

• Install to /opt/abakus/wildfly/

Linux (as root)

cd /opt/abakus/wildfly/tar zxvf wildfly-11.0.0.Final.tar.gzln -s wildfly-11.0.0.Final as

Windows (as Administrator)

unzip wildfly-11.0.0.Final.zip to `C:\Program Files\Wildfly\`

Linux service installationCreate wrapper for standalone.sh|bat in /opt/abakus/wildfly/wildfly.sh:

#!/bin/bash -euexport JAVA_HOME=/opt/abakus/java/jdk8/export PATH="$JAVA_HOME/bin/:$PATH"export JAVA_OPTS="-Xmx256m -Xms256m -Djava.net.preferIPv4Stack=true"/opt/abakus/wildfly/as/bin/standalone.sh -b 0.0.0.0

Create service user (if not using a pre-existing user) and change wildfly ownership. If user isdifferent than default, change service definition accordingly.

adduser wildflychown -R wildfly:wildfly /opt/abakus/wildflychmod a+x /opt/abakus/wildfly/wildfly.sh

You may create (Linux) system-d service by putting following in/usr/lib/systemd/user/wildfly.service:

2

[Unit]Description=WildFly application serverAfter=network.target

[Service]Type=simpleUser=wildflyGroup=wildflyExecStart=/opt/abakus/wildfly/wildfly.sh

[Install]WantedBy=multi-user.target

and then enable it by running:

systemctl enable /usr/lib/systemd/user/wildfly.service

If you’re running older version of Linux (OEL 6 and bellow), you may need to create traditional initservice like this:

/etc/init.d/wildlfy

export JAVA_HOME='/opt/abakus/java/jdk8/'export PATH="$JAVA_HOME/bin/:$PATH"export JBOSS_CONF='/opt/abakus/wildfly/as/bin/init.d/wildfly.conf'export JBOSS_HOME='/opt/abakus/wildfly/as/'export JBOSS_USER='wildfly'export JBOSS_PIDFILE='/opt/abakus/wildfly/wildfly.pid'export JBOSS_CONSOLE_LOG='/opt/abakus/wildfly/console.log'export JAVA_OPTS="-Djboss.bind.address=0.0.0.0-Djboss.bind.address.management=127.0.0.1 -server -Xms256m -Xmx256m-Djava.net.preferIPv4Stack=true -Djava.awt.headless=true"/opt/abakus/wildfly/as/bin/init.d/wildfly-init-redhat.sh $@

Deploy APPM application

Deploy appm.war by copying appm.war file to /opt/abakus/wildfly/as/standalone/deployments/. Youmay rename that file to ROOT.war in order to deploy at root context.

Database SchemaOpen https://your-server/ in your browser and login by providing credentials of one of the DBAusers (any user, that has DBA role granted, one of such users is SYSTEM). If you login using a user thatdoes not have DBA privilege, error message will appear, stating that you need to login as DBA userin order to perform installation or upgrade.

If database schema need is not yet installed or if it needs upgrading, you will be prompted for

3

SYSDBA user. This can be any user that has SYSDBA role granted - SYS is one of such users. You willalso need to select a temporary folder on database server where the datapump file will be put. Justmake sure that selected folder exists and that Oracle software owner has read/write access on it.

After that, run the installation by clicking Install button.

Database Implications

Schema APPM is created. Everything regarding APPM product resides in this schema. Besides thisschema, a few global objects (such as directory objects). Every global object create is named likeAPPM_<MAGIC>_<NAME>, where APPM_ is constant prefix, <MAGIC> is random-generated (database-specific) part to avoid name collisions and <NAME> is some meaningful name of the object.

Created schema is about to take up to 20GB of disk space (depending on how much history isrequired to be kept).

Graphical Interface

Login

You can login using any database account, which has been granted one of the following roles:

• APPM_<MAGIC>_USER

• DBA

• SYSDBA

To specify which database to connect to, use the following syntax:

host:port/service

where host is hostname of the database server, port is the port on which database listener isaccepting new connections and service is listener service name. Note that APPM does not usetnsnames.ora.

Note that after install, user APPM can be used to login for the first time in order to assign appm roles

4

to other users. After that, we recommend that you lock the APPM user account.

Dashboard

Dashboard shows basic info about the database that you’re connected to. Left upper corner saysConnected to: following standard Oracle banner showing database version. Right to this banner isinfo about how big the database is - allocated space is the actual space occupied by database andreserved space is space calculated with autoextend maximum sizes.

Database attributes table show basic data from v$database.

Instance attributes table shows basic data for each instance from v$instance. Note that OracleReal Application Clusters can have many instances.

Connection attributes table show basic data about current session - your username and privileges,along with session ID.

Services table show list of all services available from this database. You have the option tostart/stop the services from this page if you have a DBA role.

Database Parameters form allows you to see all the database parameters, including hiddenparameters.

Performance / Active History

5

Query Parameters form specifis data source and range for everything else on this page:

Data Source

• appm$ash_raw - ASH data collected by APPM in last few hours (most recent partition).

• appm$ash_hist_raw - All the ASH data collected by APPM so far.

• gv$active_session_history - data from Oracle ASH. If Oracle ASH is not enabled (this is legallyavailable only in Enterprise editions of Oracle database), then there is simply no data todisplay.

• dba_hist_active_sess_history - historcal data from Oracle AWR. If AWR/ASH is notconfigured, then this won’t display any data.

Last Hours

Number of hours from current time to show the data - e.g. "display data for last n hours.". Notethe 5s, 15s, 1m and Manual option boxes - those refere to automatic refresh rate. If Historicaloption box is selected, this field is "renamed" to Date From and Date To to allow user-specifiedtime range.

For Instance

If you’re using Real Application Clusters (RAC), then you can use this dropdown menu to displaydata regarding only one specific instance.

Sample By

Depending on size of the selected date range (see "Last Hours" field) you may decide to rendergraph differently. Grouping samples by minute usually yields best visual results, but if you havelarge range, you may use hours or day. Similary, if you only show data of few minutes range, youcan group by seconds.

6

Average Active Sessions per Event Class

The graph shows timeline on X axis and number of sessions in wait on Y axis. Colors of graph referto different wait classes (legend is on the right of the grapth). Graph also shows horizontal red line -this red line refers to CPU_COUNT. Users are likely to complain about poor performance if there ismore active sessions than there is CPUs available!

You may click on the legend to only display sessions which were waiting for one specific wait classonly.

If you have selected Historical refresh rate, you may also click-and-drag through graph to narrowselected time range. You must click Refresh button after selection to actually render selected timerange.

Top Waits

The data comes from gv$session_wait_history, which displays last 10 wait events for each activesession. So, this table shows events that were waited on the most.

Inst

Instance ID

Event

Name of the event. List of wait events and their descriptions are published in official Oracledocumentation.

Time

Amount of time waited (in hundreths of a second).

Count

Number of those wait events (e.g. number of "log file sync" events)

Time (µ)

Amount of time waited (in microseconds).

Since Last (µ)

Time elapsed (in microseconds) since the end of previous wait in wait history.

Current Waits

The data comes from gv$session_wait which displays the current or last wait for each session.

SID

Session identifier; maps to V$SESSION.SID

Seq

A number that uniquely identifies the current or last wait (incremented for each wait)

Event

7

Resource or event for which the session is waiting

P1, P2, P3

Event parameters and their descriptions/units.

Wait Time (µ)

Amount of time waited (in microseconds). If the session is currently waiting, then the value isthe time spent in the current wait. If the session is currently not in a wait, then the value is theamount of time waited in the last wait.

Remaining (µ)

Value is interpreted as follows:

• > 0 - Amount of time remaining for the current wait (in microseconds)

• 0 - Current wait has timed out

• -1 - Session can indefinitely wait in the current wait

• NULL - Session is not currently waiting

State

value is interpreted as follows:

• WAITING - Session is currently waiting

• WAITED UNKNOWN TIME - Duration of the last wait is unknown; this is the value when theparameter TIMED_STATISTICS is set to false

• WAITED SHORT TIME - Last wait was less than a hundredth of a second

• WAITED KNOWN TIME - Duration of the last wait is specified in the WAIT_TIME column

ASH Top Tabs

The data for those tabs comes from selected Data Source (at the top of the page). Different tabsshow same data from different perspective. Each tab has Activity column which displays a graph.This graph shows amount of waits that were waited on for each dimension.

SQL

Displays sql statements that took most waiting. Note that you can click on values in SQL IDcolumn to display full sql text and it’s sql plan.

PL/SQL

Displays PL/SQL procedures which took most waiting.

Objects

Displays database objects that took most waiting.

Sessions

Displays sessions that waited the most. Note that you may click on SID,Serial# column values todisplay session’s details.

8

Background Sessions

Displays only background sessions.

Files

Displays data files that were used the most.

Modules, Actions, Clients

Those are all based on what application told the databases using dbms_application_info.

Top Waits

This is different from Top Waits in the right middle of the screen, because this has ASH for datasource (in selected date range).

Top Waits by SQL

As the tab says - which wait event took the most waiting in a sql statement.

Top Waits by Session

Which wait event took most waiting in a single session.

Performance / Active Sessions

Basically displays data from gv$session. You may click on any session (in Sid,Serial# column) todisplay [Performance / Session Dialog] with session details.

Performance / Blocked Sessions

Display tree of blocked sessions. If this page is empty, that means that there are no sessions blockingother sessions. Firstly, only blocking sessions are shown. If you want to see blocked sessions, click

9

the blue triangle on left of the table to expand the table.

Performance / Locked Objects

This page displays all the objects that have locks on them. If the object is locked by a session thatdoes not mean that other sessions must wait.. At least not until they want to access the same object.If that happens, the session is blocked and it will show in Performance / Blocked Sessions. Here, wejust list all currently held locks.

You may filter those locks by their object. If you click the object, you will see list of locks on thatobject. For example, Table (is an object) can have many different rows locked by different sessions.

Performance / SQL Trace

You can start the trace by going to Performance / Active Sessions and then selecting one specificsession. A popup appears and under a "Trace session" heading you can start the trace.

Note the Session Identifier value, you can pick any meaningful name here, but remember it as thisis the key by which you’ll find your trace later on.

Tracing Sessions table displays all sessions with their basic attributes which currently have tracingenabled. You can click on first column value to open the same popup that you’ve used to start thetrace.

Traces shows list of completed traces. Plain option allows you to download raw, unprocessed tracefile as it was created by Oracle. TVDXTAT option will process the raw trace file through tvdxtat andthen download the resulting file. The tvdxtat utility is embedded within this GUI tool. tkprof willrun the raw trace file through the tkprof as provided in $ORACLE_HOME of the instance that you’recurrently connected to.

10

You need to have APPM_TRACE role granted to be allowed to start/stop the traces anddownload/process trace files.

SQL Patch

This page lists all SQL Patches.

Columns of the table are as follows:

SQL ID

SQL ID of the statement for which the patch was created. If patch was created manually (withoutAPPM), then this column displays SQL signature number. Editing of such manually created patchis not possible.

Name

User defined (or auto generated) name of SQL Patch. This is unique among all SQL patches.

Hint

Hints that are applied using this patch. Those written in blue color are valid hint names andthose in red color have syntax error.

Status

Tells if this patch is enabled or disabled. Only one SQL Patch may be enabled at a time. (Note toadvanced user: only one patch per group may be active, but APPM only operates in DEFAULTgroup).

F. Match

If force matching is used.

Created

Date when the patch was craeted.

Last Modified

Date when the patch was last modified.

Opts

You may enable/disable or delete or edit any patch listed.

11

SQL Statements

Page lists all SQL statements that are currently known to the database or were known at some pointand were sampled by APPM.

Data Source

Tell APPM where to look for SQL statements - in SGA (currently known sql statements) or inAPPM repository.

SQL Text (contains)

Search for all SQL statements that contains this text (case insensitive).

ASH MonitorThis feature allows you to monitor ASH on multiple connections at once.

First, you need to open connection to multiple databases. You can do that by clicking "ActiveConnections" on upper left corner, as shown on the following screenshot:

Login in as usual. Note that list of already open database connections is available in "ActiveConnections" frame.

12

After successful login, the list of currently active connections is available by clicking "ActiveConnections". Each connection has it’s designated color so that you know which connection iscurrently selected. Currently selected connection color is the color of upper banner:

Finally, when you have logged in to all of relevant databases, click on "Ash Monitor" button toobtain ASH graph for all connections at once. It looks like this:

Graphical Interface Dialogs

Session DialogThis dialog is available whenever session’s SID and SERIAL# are known.

Active Session

Displays basic info from v$session. It allows you to start a sql trace for this session if you haveAPPM_TRACE role granted. And if you have DBA role granted, you have an option to kill this session. Ifthis session is currently executing a SQL statement, this statement is shown under "Current SQL"accordion.

Active Session Statistics

13

Displays data from from v$sesstat about user session statistics.

History Session

Displays data from ASH collected by APPM. This is relevant if session would already ended - this isinfo about a session in the past.

History Graph

Displays data from ASH collected by APPM. Note that data by default comes from most recent APPMpartition. You can only select other data source if this dialog is displayed from Performance / ActiveHistory page.

The table lists all the samples and the graph renders the samples. Note that you if you hover yourmose over the table, location of the sample is highlighted on the graph.

SQL DialogThis dialog is available whenever SQL ID is known.

14

SQL Text

First tab displays exact SQL text for selected SQL ID.

Execution Plans

Second tab displays list of all known SQL Plans. This is basically list of plans from v$sql.

If child number was known when the dialog was open, then this child number is highlighted withyellow color as seen on the screenshot.

Columns are as following:

Plan Hash / Child Instance

Plan hash is numeric representation of the current SQL plan for this cursor. Comparing onePLAN_HASH_VALUE to another easily identifies whether or not two plans are the same (ratherthan comparing the two plans line by line). Child instance is number of child cursor.

Last Active

Time at which the query plan was last active.

Executions

Number of executions that took place on this object since it was brought into the library cache.

**Elapsed

Elapsed time (in microseconds) used by this cursor for parsing, executing, and fetching. If thecursor uses parallel execution, then ELAPSED_TIME is the cumulative time for the querycoordinator, plus all parallel query slave processes. This value is divided by number ofexecutions.

**Rows

Total number of rows the parsed SQL statement returned. This value is divided by number ofexecutions.

**Fetches

Number of fetches associated with the SQL statement. This valid is divided by number of

15

executions.

**Buffer Gets

Number of buffer gets for this child cursor. This value is divided by number of executions.

SQL Patch

Name of SQL Patch used to produce this plan, if any.

SQL Patches

This tab displays list of SQL patches for this SQL ID. Note that patches are actually applied toexact_matching_signature or force_matching_signature, rather than to SQL_ID. Different SQLs mightshare such signature.

Buttons available: Create Patch:: is used to create new patch.

Flush SQL

Flushed the SQL so it must be reparsed on next invocation.

/*+ gather_plan_statistics */

Generates new SQL Patch for this statements using gather_plan_statistics hint.

Columns of the table are as follows:

Name

User defined (or auto generated) name of SQL Patch. This is unique among all SQL patches.

Status

Tells if this patch is enabled or disabled. Only one SQL Patch may be enabled at a time. (Note toadvanced user: only one patch per group may be active, but APPM only operates in DEFAULTgroup).

Force Matching

If force matching is used.

Category

Category of SQL Patch. APPM automatically moves disabled patches into auto generated disabledgroup.

Created

Date when the patch was craeted.

Last Modified

Date when the patch was last modified.

16

Hint

Hints that are applied using this patch.

Opts

You may enable/disable or delete any patch listed.

PlanThis dialog displays Execution Plan (known by plan_hash_value and child_number).

Plain Plan

This is plan formatted using dbms_xplan.display% function. You can also specify formatting optionsto this procedure using "Plan Format" field.

TAB Explain Plan

The same plan formatted using collapsible tree table graphical component.

SQL Info

This tab displays all known fields from v$sql.

17