Merge pull request #1152 from oracle-devrel/uschwinn_dbreplay

Uschwinn dbreplay

Author: AlexanderHodicke

data-platform/core-converged-db/real-application-testing/db-replay/README.md

@@ -0,0 +1,48 @@
+# Database Replay (DB Replay)
+
+Database Replay can be used to capture a real workload on the production system and replay it on a test system with the exact timing, concurrency, and transaction characteristics of the original workload. This enables you to test the effects of a system change without affecting the production system. Database Replay supports workload capture on a system running Oracle Database 10g Release 2 and newer releases. Because the database workload capture is stored in a platform-independent format, you can capture a workload on one OS platform, e.g. Windows, and replay on a different one, e.g. Linux. Keep in mind it should be used only within the Oracle Database. Other external components like application server, middleware, or client software cannot be considered when testing with Real Application Testing. Either the graphical interface via Enterprise Manager Cloud Control or the command-line API can be used.  
+
+
+Reviewed: 02.07.2024
+
+# When to use this asset?
+
+To learn about Database Replay using the command line API.  
+
+# How to use this asset?
+
+See the README in the files folder.
+
+Please note: Database Replay for Autonomous Database (ADB) works differently. It can be used e.g. to replay a recorded (captured) workload from On-Premises or cloud installations in an Autonomous Database. 
+For more details on the usage in ADB refer to the [documentation](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/autonomous-real-application-testing.html#GUID-EB8F065E-5FBB-480D-BAF6-5A0446740073) or the posting [Autonomous Database Replay](https://blogs.oracle.com/coretec/post/adb-database-replay).
+ 
+# Useful Links
+
+## Documentation
+
+- [Testing Guide](https://docs.oracle.com/en/database/oracle/oracle-database/19/ratug/database-replay.html#GUID-C5CAF3E6-0F1C-4BD6-BC03-F71744AD600E)
+- [PL/SQL Packages and Types Reference - DBMS_WORKLOAD_CAPTURE](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_WORKLOAD_CAPTURE.html#GUID-77C6507C-3DE6-4FB4-B180-530BEB840BE8)
+- [PL/SQL Packages and Types Reference - DBMS_WORKLOAD_REPLAY](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_WORKLOAD_REPLAY.html#GUID-FE03A123-2257-41FF-BA90-AD0114DC1A4F)
+- [Test Workloads with Oracle Real Application Testing - Autonomous Database](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/autonomous-real-application-testing.html#GUID-EB8F065E-5FBB-480D-BAF6-5A0446740073)
+- [PL/SQL Packages and Types Reference for Autonomous Database - DBMS_CLOUD_ADMIN](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/dbms-cloud-admin.html#GUID-D76B229E-781E-45C0-9F14-CAF30F9E6E3B)
+
+
+## LiveLabs
+
+- [Real Application Testing: SQL Performance Analyzer and Database Replay](https://apexapps.oracle.com/pls/apex/r/dbpm/livelabs/view-workshop?wid=858&clear=RR,180&session=112790027738609)
+
+
+# Team Publication
+
+- [Testing with Oracle Database Replay](https://blogs.oracle.com/coretec/post/testing-with-oracle-database-replay)
+- [Real Application Testing Database Replay Demo](https://blogs.oracle.com/coretec/post/rat-demo)
+- [Autonomous Database Replay](https://blogs.oracle.com/coretec/post/adb-database-replay)
+
+
+# License
+
+Copyright (c) 2024 Oracle and/or its affiliates.
+
+Licensed under the Universal Permissive License (UPL), Version 1.0.
+
+See [LICENSE](https://github.com/oracle-devrel/technology-engineering/blob/main/LICENSE) for more details.

data-platform/core-converged-db/real-application-testing/db-replay/files/README.md

@@ -0,0 +1,71 @@
+## Database Replay Scripts
+
+This folder provides SQL scripts for the usage of Database Replay (DB Replay). Please adapt and change the scripts to your conditions. 
+
+## Scripts
+
+You can find an example workflow, the executed scripts, and a detailed description in the posting [Testing with Oracle Database Replay](https://blogs.oracle.com/coretec/post/testing-with-oracle-database-replay).
+
+Keep in mind that appropriate permissions are required to
+- Create directory objects
+- Use DBMS_WORKLOAD_CAPTURE and DBMS_WORKLOAD_REPLAY packages
+- Act as a replay client user (e.g. wrc someuser/YOUR_PASSWORD or wrc USER=someuser PASSWORD=YOUR_PASSWORD) //PLEASE CHANGE YOUR_PASSWORD  TO A REAL PASSWORD!
+ 
+In the documentation [DBMS_WORKLOAD_CAPTURE Security Model]( https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_WORKLOAD_CAPTURE.html#GUID-77C6507C-3DE6-4FB4-B180-530BEB840BE8) you will get the detailed information about it.
+
+Before starting a workload capture, you should have a strategy in place to restore the database on the test system. Before a workload can be replayed, the logical state of the application data on the replay system should be similar to that of the capture system when replay begins.
+
+In general, please follow the suggested script order.
+
+### 1) Capture the Database Workload in the production environment 
+
+Before starting, check the [Workload Capture restrictions](https://docs.oracle.com/en/database/oracle/oracle-database/19/ratug/capturing-a-database-workload.html#GUID-4A1995F1-78F9-4080-8DFC-1E3EBCB3F4B8).
+
+- Provide an empty database directory 
+- (optional) Use filters: capturefilter.sql 
+- Start capture: capturestart.sql
+- (optional) Stop capture: capturestop.sql
+- Check capture results: capturemon.sql
+- Export AWR: exportawr.sql
+- Capture report: capturereport.sql
+
+(Note: it may be useful to generate an additional AWR spanning the capture period.) 
+
+### 2) Preprocess the (captured) Database Workload on the test environment  
+
+- Preprocess: processcapture.sql
+- (optional) Check duration: processmonitor.sql
+
+### 3) Replay the Database Workload on the test environment
+
+- (optional) Add filters: replayfilter.sql and replayfilterset.sql 
+- Initialize the replay: replayinitialize.sql
+- (optional) Map connections: remapping.sql
+- (optional) Use filters: replayusefilterset.sql 
+- Prepare the replay: replayprepare.sql
+
+- Workload Replay clients: Number estimation and start
+
+Estimate the number of Workload Replay Clients (WRCs) (e.g. $wrc mode=calibrate replaydir=../replay/..) 
+
+Start WRCs in the background on the replay machine or a separate machine (e.g. $wrc username/password mode=replay replaydir=../replay/...)
+
+- Start the replay: replaystart.sql
+- Monitor the replay: replaymon.sql
+
+### 4) Generate Reports
+ 
+- (optional) Divergence reports: divergences.sql, divergence_detail.sql
+- Replay report: replayreport.sql
+- Import capture AWRs: importAWR.sql
+- ComparePeriod report: comparereplayreport.sql 
+
+(Note: it may be useful to generate an additional AWR spanning the replay period.)      
+
+# License
+
+Copyright (c) 2024 Oracle and/or its affiliates.
+
+Licensed under the Universal Permissive License (UPL), Version 1.0.
+
+See [LICENSE](https://github.com/oracle-devrel/technology-engineering/blob/main/LICENSE) for more details.