Starting a database trace

The Database Trace tool produces a text file containing the SQL statements, rule cache hit statistics, timings, and other data that reflect your requestor session's interactions with the Pega Platform database or other relational databases. You can select the database options that are traced. Familiarity with SQL is required to interpret the output.

  • This tab is available only to users who hold the Code-Pega-.PerformanceTool privilege.
  • Additional database statistics are displayed by the Performance Analyzer. For more information, see Database access counts.
CAUTION:
Operating this tool can adversely affect performance, and can produce a large volume of output. Use this tool only in appropriate non-production debugging environments, for short periods.
  1. In the header of Dev Studio, click Configure > System > Performance > Database Trace.
  2. Click Trace Options.
    The following trace options are available:
    Label Operation
    Add Batch Causes the output to include a line for each add batch operation.
    Prepared Statement Query Causes the output to include a line for each query (SQL database read) operation.
    Prepared Statement Update Causes the output to include a line for each update (SQL database insert, update, or delete) operation.
    Prepared Statement Each read, update, or delete operation requested by the Pega Platform server results in a prepared statement query sent to the Pega Platform database.

    Causes the DB Trace output to include a line for all three types of prepared statements.

    Get Database Metadata Causes the Database Trace output to include a line for each check of the rule cache. Checks typically occur first time that a table is accessed after startup and before read operations.
    Read blob Causes the DB Trace output to include a line each time the Storage Stream column ( pzPVStream ) in a row is read. The size of the entry in the column is also reported.
    Write blob Causes the Database Trace output to include a line each time Storage Stream column ( pzPVStream ) in a row is written.
    Commit Causes the Database Trace output to include a line each time an internal database commit operation completes. (This is not directly related to the Pega Platform Commit method.)
    Rollback Causes the Database Trace output to include a line when a PRPC Commit operation is in process but a database rollback operation occurred.
    Assign Connection to Thread Causes the Database Trace output to include a line when a database connection in a pool is reassigned to a new requestor thread.
    Cache Hit (found) Causes the Database Trace output to include a line when a rule cache hit occurred and the requested row was found.
    Cache Hit (not found) Causes the Database Trace output to include a line when a rule cache hit occurred and the requested row did not exist. (For rules, the database cache records both the requests not found and successful requests.)
    Cache Miss Causes the Database Trace output to include a line when a rule cache miss occurred.
    Run List Causes the Database Trace output to include a line when a list rule (Rule-Obj-List rule type) was processed by the Obj-List method in an activity.
    List Result Count Causes the Database Trace output to include a line when a list rule completed and indicates the number of rows returned.
    Activity Start Causes the Database Trace output to include a line when an activity execution starts.
    Activity End Causes the Database Trace output to include a line when an activity execution completes.
    Assembly Start Causes the Database Trace output to include a line when rule assembly starts.
    Assembly End Causes the Database Trace output to include a line when rule assembly end.
  3. Click Trace to turn on tracing for the selected operation.
    Select only the minimal set of options that are required to aid your debugging.
  4. Optional: Click Generate stack trace to generate a full Java stack trace.
  5. Click Submit.
    The system saves this information in the pyDBTraceSettings page within your requestor page.
  6. To start tracing, on the Database Trace tab, click the Click to Start icon (green arrow).
What to do next: Viewing database trace results in Excel