en_manual_03_02

Pic. 5 Launch application without graphical interface

Graphical interface

The application starts with graphical interface by default. To launch, you should to perform following steps, depending on the application's format:

• Open version (archive)
  • navigate to the folder, containing the unpacked application
  • run the application using the command
    • python lightprofiler.py
• Open version (deb-package)
  • use the shortcut, created during installation
  • or navigate to the application folder (by default - /usr/local/share/applications/lightprofiler), and execute command:
    • python lightprofiler.py
• Precompiled version (OS Windows)
  • use the shortcuts on desktop or Quick Launch bar, created during the installation process
  • or launch “Start” - “All programs” - “LightProfiler 0.8.00” - “LightProfiler”
  • or navigate to the application folder and execute file lightprofiler.exe

Appearance

When you run the application with GUI, you are automatically taken to the main window:

Pic. 6 Main window

On the main window can be highlighted following areas:

1. menu bar — provides access to all application features
2. toolbar — contain control elements for executing main operations with all profilers
3. workspace — area of the main window, which designed for layout windows of the profilers or tools
4. statusbar — showing status of the current profiler or tool

Shown early picture also contain sample of the profiler window (area 5), more detailed description you can found in relevant section Profiler.

Menu

The menu for current version of LightProfiler has the following structure:

• Profiler
  • Select file(s) — show dialog for selecting trace-file(s) for active or new profilers¹.
  • Export — show dialog for exporting parsed trace-file in xtrc-file.
  • Active
    • Cancel — cancels current operation for the active profiler.
    • Reset — resets state for the active profiler (removes parsed results, resets status on “created”).
    • Clear — clears the active profiler (removes parsed results, resets status on “created”, removes information about selected trace-file).
    • Parse — executes “Parse” operation for the active profiler (preparation and filling internal data structures, collecting stats for the trace-file, etc.)².
    • P&P — executes “Parse” and “Profile” operations for the active profiler in same time.
  • All
    • Cancel — cancels current operations for all profilers.
    • Reset — resets state for all profilers.
    • Clear — clears the all profilers.
    • Parse — executes “Parse” operation for all profilers.
    • P&P — executes “Parse” and “Profile” operations for all profilers.
  • Exit — exit the application.
• Reports
  • Examine — show brief stats about trace-file for the active profiler. Detailed description of the report can be found in the relevant section Examine.
  • Active
    • Profile — generate resource profile for the active profiler. Detailed description of the report can be found in the relevant section Resource profile.
  • All
    • Profile — generate resource profile for all profilers. Detailed description of the report can be found in the relevant section Resource profile.
  • Optimization — opens dialog for generating optimization reports. Detailed description of generation process and report's structures can be found in the relevant section Optimization.
  • <recently generated report> - list of the recently generated reports (“Profile”, “Optimization“).
• Tools³
  • LpDBMonitor — launches the relevant tool.
  • LpCombiner — launches the relevant tool.
  • LpSplitter — launches the relevant tool.
• Environment
  • Options — opens dialog for tuning app options⁴. Detailed description of available options can be found in the relevant section Options.
  • Commands – opens dialog for tuning app commands. Detailed description of tuning commands can be found in the relevant section Settings.
  • <list of configured commands> - this section displays headers for all configured commands.
• Window
  • Maximize — expands window of the active profiler or tool, on the entire application workspace.
  • Restore — restore default window size for the active profiler or tool.
  • Cascade — restore default window sizes for all windows and place them cascade in the workspace.
  • <list of profiler and tool windows>
• ?
  • Help — show dialog “Help”, containing list of available options.
  • Manual — open file “User manual”⁵ on the current application language⁶.
  • Website – open official website in your browser.

Pic. 7 Official site

• Got Idea! - open a page for ideas sharing in your browser.
• Donate — open a page for donating in your browser.

Pic. 8 Donating page

• Guestbook — open a guestbook page in your browser.
• Send comment — open a page in the browser to post a comment

Pic. 9 Page of the comment

• Send bug report — open a page in the browser to send a bug report

Pic. 10 Page of the bug report

• License — show dialog with brief information about license.
• Credits — show dialog with appreciations.
• Check for updates — check current version of the application, which available to download from the official website.
• About — show dialog “About”.

Note:

1. Depending on the profiler status, some operations with it, may be disabled..

Toolbar

The application toolbar has the following control elements:

• profiler windows management control elements (“New”, “Close”, “Cascade”)
• main operations control elements for all profilers (“Cancel all”, “Reset all”, “Parse all” etc.)

Profiler

Profiler — built-in application's tool, designed to analyze trace-files and generate reports. When you run a GUI application you can use any number of profilers.

Below is an example of profiler window:

Pic. 11 Profiler window

For profiler window can be highlighted following areas:

1. toolbar — contains the following control elements:
• call operations on the active profiler (“Cancel”, “Reset”, “Clear”, “Parse”, “Profile”, etc.)
• opening the log files and the generated profile (“Open profile”, “Open log”)
• call the dialog for changing profiler's options (“Options”)⁷. When you open a new profiler window's its options are populated from the application's options. Before starting any operation you can change it.⁸
• control elements to show some sections from generated profile (“Show events”, “Show statements”, “Show cursors”, “Show snapshots”). Below is an example of profiler's window and profile's section:

Pic. 12 Windows for profiler and profile's section

1. work area - consists of three tabs: “General,“ “Log“, “Debug“. A detailed description of each tab below.
2. status bar — shows current process state.

General

This tab contains control elements for trace-file selection and writing comment⁹.

Pic. 13 Tab “Common”

Log

This tab is used to display log of the active profiler. The contents of a tab can be cleared (click button “Clear“) or uploaded to a file (click button “Upload“).

Pic. 14 Tab “Log”

Also, the log has built-in search tool, which you can call by pressing Ctrl + F.

Pic.15 Search dialog

Search result(s), are highlighted in the log (this selection will be reset when re-search, or after pressing the button “Reset All”).

Note:

1. After trace-file's selection, log contents will be duplicating in the file, defaults to the path <application folder>\logs\<trace-file name>.log. You can open this file by clicking “View log” on the profiler's toolbar.

Debug

Note:

1. Using debug mode can significantly reduce application's performance!

Using the application in debug mode allows you to collect additional information for SQL statements: source lines of the trace-files, the details of the performed calculations as well as generate sdmp-files (see Glossary)

Pic.16 Tab “Debug”

On this tab can be highlighted the following groups of elements:

1. Debug log with built-in search tool
2. Switcher for debug mode
3. List of debugging SQL cursor's identifiers (SQL cursor's identifier – value of field “hv” in the section PARSING IN CURSOR)¹⁰.
4. Debug-list's control elements: field identifier, buttons for add/delete record.

The current version of application allows you to debug with the following modes:

• Sdmp - generate sdmp-files for the selected SQL statements
• All - all debugging information for the selected SQL statements

Note:

1. By default, sdmp-files generating in <Application folder>\dmp\<trace-file name>_<identifier>.csv.

Tools

This section describes the basic tools as well as the necessary information about their development.

LpCombiner

LpCombiner – this tool was designed for extracting session data from one or more trace-files.

Pic. 17 Tool “LpCombiner”

Depending on configuration of the Oracle server and used OS, in the trace-file data can be placed several sessions or data of one session can be placed in several trace-files. To solve these problems and designed this instrument. It parses contents of the trace-files in search of session IDs (strings like *** SESSION ID :...) and arranges them in the correct order (according to date), forming a new “pseudo“ trace-file.

There is toolbar in the upper part of the “Control” tab, that allows you:

• select file(s) - opens dialog to choose processed trace-files
• parse file(s) - search for session IDs
• combine file(s) - create a new “pseudo“ trace-file
• clear all - clear all data
• mode switcher
  • parallel execution — selected trace-files contain data for multiple concurrent sessions, ie “pseudo“ trace-file will contain all of these sessions in order of execution.
  • snipe select — selected trace-files contain particular session , ie “pseudo” trace-file will contain only it data.

In the lower part you can see list of trace-files selected for analyze.

LpSplitter

LpSplitter – this tool was designed for splitting trace-file on some parts.

Pic. 18 Tool “LpSplitter”

To perform splitting of the trace-file you need:

• select trace-file
• specify size of the fragments (in bytes)¹¹ - using the input field or key combinations: Ctrl-<number> - multiply the current value of the field on <number>, Alt-<number> - set size equal to the <number> MB
• execute operation, by pressing the button “Split file”

If necessary, you can include trace-file's preamble to the generated trace-files, by checking the field “Add preamble in file”.

LpDBMonitor

LpDBMonitor – a light-weight Oracle database monitor. Show database sessions and related information. Also it allow start/stop tracing or disconnect session.

Note:

1. The current version of the tool has been implemented using the library cx_Oracle 5.1 (http://cx-oracle.sourceforge.net) and client app for Oracle database - InstantClient 11.2.0.1 (http://www.oracle.com). In this configuration, the tool can be used with database version 9i or later.

Pic. 19 Tool “LpDBMonitor”

The tool's window can be divided on following areas:

1. toolbar — calls dialog “Connection manager” or “New connection”. When using dialog “Connection manager”, connection settings will be saved for later use¹².
2. Bookmark's toolbar for current connections — shows open connections with Oracle instances.
3. Current connection's toolbar — allows you to perform operations on a sessions or change the display settings. This toolbar contains the following fields and control elements:
• the field “Rows” - displays the number of sessions for the active connection (active / total)
• the checkbox “Non-system users”- allows you to “hide“ sessions, belonging to system users
• the field-list “Filter” and the input field - allows you to change conditions of displaying sessions
• “Refresh” button - updates information about sessions (or you can use Ctrl - F5)
• the checkbox “Auto-refr.” and the field-list - enables you to turn on auto-update of session's information
• the field-list “Level” - selects the trace level
• the button “Start trace” - allows you to set event 10046 with a given level (from keyboard - “+”) for the specified session
• the button “Stop trace” - disables tracing for the session (with the keyboard - “-”)
• the button “Close connection“ - close current connection and the active tab
1. The panel of sessions — contain table for displaying database's sessions in the active connection. Depending on some conditions, table row, may be highlighted with color:
• Yellow — own session of the tool
• Green — the new session, which appeared in select result for the first time since last access to the database
• Blue — for this session was started tracing
1. The detail panel — contains tabs to display additional information on selected session:
• SQL statement - displays text of the current (last) query
• Open cursors - displays open cursors in the session
• Events - displays wait event stats for the session (name, number, duration)
• Statistics - displays general statistics for the session
• Blocking, Blocked by - a brief info about the sessions that are blocking current session or that, are blocked by current session¹³
• SQL plan - the current execution plan from the view v$sql_plan

Development

Tool – this is application, written in Python language, has an interface that uses tkinter library, and formed according to specific requirements.

The files, used for tool, are placed in the separate folder (hereinafter – tool's folder), which has a specified structure. Below is the structure for the tool LpSplitter:

• lpsplitter - tool's folder¹⁴
  • locale – folder for translations
    • ru – folder for one language of translation
      • LC_MESSAGES — folder for common messages
        • lpsplitter.mo – file with translation
  • lpsplitter.py - main module for tool
  • tool.dsc – file with tool's description (contains required information, necessary for plugging tool in the LightProfiler)

Consider process of developing your own tool called usertool on OS Windows:

1. Download file usertool.zip from the official site: http://www.lightprofiler.org page Downloads
2. Unpack the contents of usertool.zip to the folder <application folder>/resources/usertool. Contents of the directory should like as:
• _write_dsc.py – script to generate dsc-file
• 00.create_dsc.bat – batch-file that launch dsc-file generation
• 01.translate_tool.bat – batch-file to create a localization of the tool using a previously installed application - PoEdit (the latest versions and instructions for using this application can be found on the official site of the project — http://www.poedit.net)
• msgfmt.py, pygettext.py – required scripts to create localization of the tool, also be used similar scripts from <Python folder>/Tools/i18n.
• usertool.py – the tool's main module
1. Edits the file usertool.py, observing following requirements:
   1. If you planning localization for the tool, then, source code must include following fragment:

##########################

### global translator

##########################

go_translator = cl_ToolTranslator()

_ = go_translator.get

_u = go_translator.get

, where cl_ToolTranslator — a object that imported from module lptoolapi

1. You must create following global variables:
   1. __toolid__ - tool's identifier (must be same as name for tool folder)
   2. __toolname__ - header for tool
   3. __toolversion__ - version for tool
   4. __toolhelp__ - list of strings, representing a brief description or help for tool
   5. __toolmw__ - minimum width of the tool's window in application workspace
   6. __toolmh__ - the minimum height of the tool's window in application workspace
2. The tool itself, should be a class, named cl_Tool, inherited from cl_ToolAPI (imported from module lptoolapi)
3. Below is the recommended appearance of the class constructor:

def __init__(self,**kw):

global go_translator

kw['helptext'] = __toolhelp__

kw['translator'] = go_translator

kw['toolpath'] = os.path.split(__file__)[0]

kw['toolid'] = __toolid__

kw['toolname'] = __toolname__

kw['toolversion'] = __toolversion__

if 'mw' not in kw:

kw['mw'] = __toolmw__

if 'mh' not in kw:

kw['mh'] = __toolmh__

cl_ToolAPI.__init__(self,**kw)

self.__guiitem = cl_ToolAPI.api_get_guiitem(self)

1. For additional operations on the initialization, we recommend to override the following methods:
   1. user_pre_init_mdichild(self, **kw) — this method is called before tool interface initialization (kw – init parameters).
   2. user_post_init_mdichild(self, **kw) — this method is called after tool interface initialization (kw – init parameters).
2. To create an widgets for tool we recommend to use the following method:
   1. user_fill_content(self, pw_controltab) — this method is called on interface generating (pw_controltab — frame for “Control” tab of the tool).
3. Edit _write_dsc.py – if necessary, you can specify icon for the tool¹⁵.
4. Launch file 00.create_dsc.bat for generating dsc-file.

On this step – process of creating the tool is completed – a new tool is available for use in the LightProfiler:

Pic. 20 Addition of new tool

Commands

“Commands” - a mechanism that allows to execute commands in the OS or run other applications from LightProfiler, if necessary, using the attributes of the active profiler.

Settings

Setting up commands is done in the dialog “Commands”, that can be accessed via the application menu (Environment/ Commands), or from the toolbar (button “Commands”).

Pic. 21 Dialog “Commands”

The dialog consists of the following areas:

1. List of commands - displays a list of existing commands.
2. The toolbar for the list of commands - contains control elements for positioning of command in the menu and the toolbar.
3. The control elements for working with commands - add, edit, delete commands.

Creating or editing commands are done in the “Command editor” - dialog, designed for entering text and command's parameters.

Pic. 22 Dialog “Command editor”

Parameters

When editing the command, you can use special tags "Parameters" - snippets of text that will be replaced with specific values when you run the command.

In the current version of application you can use the following parameters:

• <srcpath> - full path to trace-file of the active profiler
• <srcfolder> - folder of trace-file for the active profiler
• <srcfile> - filename and extension of trace-file for the active profiler
• <srcname> - filename of trace-file for the active profiler (without extension)
• <output> - folder for reports, specified by application settings
• <profile> - filename and extension of generated report "Resource profile" of the active profiler
• <prfpath> - full path to generated report "Resource profile" of the active profiler
• <log> - filename and extension of log file for the active profiler
• <logpath> - full path to log file for the active profiler
• <username> - current OS username
• <ossep> - OS separator
• <sysdate> - current date in YYYYMMDD format
• <systime> - current time in the format HHMISS
• <resources> - folder with resources, specified during application's startup

Execution

You can execute configured commands as follows:

1. Via application menu (choose it from the list in the menu "Environment")
2. Via toolbar (choose it in the toolbar's list and click button "Execute command")

1The application will create missed profilers if a user will select few trace-files

2“Parse” operation must be executed before generating of any report

3Was listed only basic tools of the current application version

4This dialog also can be called with key combination Ctrl-O

5You need pdf-viewer for opening such file

6By default, application supplied with English version of the manual, if necessary, you can download manual on other languages and place it in the “doc” folder

7Dialog for tuning options may be called by pressing Ctrl+P

8The profiler has less available options then the entire application

9If the “Comment” field was filled, its contents will be included as an additional section of the report “Resource profile”

10The application uses an identifier that builded according rule: 0_RPC_<unique serial number for subprogram in trace-file> for RPC CALL statement

11Size of the generating trace-files may differ from the specified value, because occurring line-by-line copying during split, and not calculated size of the trace-file's preamble.

12Passwords NOT saving by security reasons

13You can use key combination Ctrl-L for jump to selected session from this tabs

14Tool's folders are placed in <Application folder>/resources

15The tool icon can be added in the text format, detailed description can be found in recipe: http://code.activestate.com/recipes/52264

< Previous section Content Next section >