Skip to main content

Starting a database trace

Suggest edit Updated on May 11, 2022

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 ConfigureSystemPerformanceDatabase Trace.
  2. Click Trace Options.
    The following trace options are available:
    LabelLog Event
    Add Batcheach add batch operation.
    Prepared Statement Queryeach query (SQL database read) operation.
    Prepared Statement Updateeach update (SQL database insert, update, or delete) operation.
    Prepared Statementall three types of prepared statements:

    Each read, update, or delete operation requested by the Pega Platform server results in a prepared statement query sent to the Pega Platform database.

    Get Database Metadataeach check of the rule cache.

    Checks typically occur first time that a table is accessed after startup and before read operations.

    Read blobeach time the Storage Stream column (pzPVStream) in a row is read. The size of the entry in the column is also reported.
    Write blobeach time Storage Stream column (pzPVStream) in a row is written.
    Commiteach time an internal database commit operation completes. (This is not directly related to the Pega Platform Commit method.)
    Rollbackwhen a PRPC Commit operation is in process but a database rollback operation occurred.
    Close Connectionwhen a connection is explicitly closed.
    Assign Connection to Threadwhen a database connection in a pool is reassigned to a new requestor thread.
    Cache Hit (found)when a rule cache hit occurred and the requested row was found.
    Cache Hit (not found)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 Misswhen a rule cache miss occurred.
    Run Listwhen a list rule (Rule-Obj-List rule type) was processed by the Obj-List method in an activity.
    List Result Countwhen a list rule completed and indicates the number of rows returned.
    Activity Startwhen an activity execution starts.
    Activity Endwhen an activity execution completes.
    Assembly Startwhen rule assembly starts.
    Assembly Endwhen rule assembly ends.
    Get Document From Bucketwhen a Couchbase document is retrieved from a bucket.Note: This is only applicable for a Couchbase database.
    Save Documents To Bucketwhen a Couchbase document is saved to a bucket.Note: This is only applicable for a Couchbase database.
  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
  • Viewing database trace results in Excel

    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 export this file to Microsoft Excel to view the results.

  • Generating a system-wide database trace

    As an alternative to using the Database Trace tool, you can trace system-wide database statistics. As a best practice, do this for very short periods on a non-production system.

Did you find this content helpful? YesNo

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us