final modifications

final modifications

Author: rishabh-ghosh24

manageability-and-operations/observability-and-manageability/database-management/Custom Metrics/README.md

@@ -1,26 +1,27 @@
-# Creating Metric Extensions for Database using OCI Database Management Service
+# Creating Metric Extensions for Oracle Database using OCI Database Management Service
 
-Metric Extensions are helpful when the metric you are looking for doesn't exist out of the box. In such cases, you may create your own custom metric and use it for monitoring the database.
+Metric extensions are useful when the metric you are looking for does not exist out of the box. In such cases, you can create your own custom metric and use it for monitoring your database.
 
 This guide explains how to create metric extensions step by step.
 
 ## What Are Metric Extensions?
 
-**Metric Extensions** are custom, user-defined SQL-based metrics collected by OCI Database Management. They supplement standard metrics, providing additional insights (e.g., error counts, job statuses, or resource KPIs not tracked by default).
+**Metric extensions** are custom, user-defined, SQL-based metrics collected by OCI Database Management. They supplement standard metrics, providing additional insights (for example, error counts, job statuses, or resource KPIs not tracked by default).
 
 ## Note
-[Metric Extensions](https://docs.oracle.com/en-us/iaas/database-management/doc/work-metric-extensions.html#DBMGM-GUID-6D5E80AA-ABA5-4FBA-A63F-106CEE39C3F7) is currently only available for External Databases. Hence if the database is an OCI database, as in this case (Oracle Base Database), then it needs to be registered in Database Management as an External Database.
+[Metric extensions](https://docs.oracle.com/en-us/iaas/database-management/doc/work-metric-extensions.html#DBMGM-GUID-6D5E80AA-ABA5-4FBA-A63F-106CEE39C3F7) are currently available **only for External Databases**. Therefore, if your database is an OCI database (as in this case, Oracle Base Database), it must be registered in Database Management as an External Database.
 
 ## Prerequisites
 
-- OCI tenancy with Database Management enabled
-- Target Oracle Database registered in Database Management as [External Database](https://docs.oracle.com/en-us/iaas/database-management/doc/external-database-related-prerequisite-tasks.html#DBMGM-GUID-84B74F18-F672-4DDC-8505-ACF249293D64)
-- Have the required [policies](https://docs.oracle.com/en-us/iaas/database-management/doc/perform-general-oracle-cloud-infrastructure-prerequisite-tasks.html#DBMGM-GUID-DCC3067D-5123-468E-A938-D310CC685674) in place
+- OCI tenancy with Database Management enabled.
+- Target Oracle Database registered in Database Management as an [External Database](https://docs.oracle.com/en-us/iaas/database-management/doc/external-database-related-prerequisite-tasks.html#DBMGM-GUID-84B74F18-F672-4DDC-8505-ACF249293D64).
+- Required [policies](https://docs.oracle.com/en-us/iaas/database-management/doc/perform-general-oracle-cloud-infrastructure-prerequisite-tasks.html#DBMGM-GUID-DCC3067D-5123-468E-A938-D310CC685674) in place.
 
 ## Step-by-Step Guide
-[Implementation Steps](./create_metric_extension.md)
 
-# License
+See [Implementation Steps](./create_metric_extension.md) for details.
+
+## License
 
 Copyright (c) 2025 Oracle and/or its affiliates.
 

manageability-and-operations/observability-and-manageability/database-management/Custom Metrics/create_metric_extension.md

@@ -1,5 +1,4 @@
-
-# **Implementation Steps**
+# Implementation Steps
 
 <table>
 <tbody>
@@ -13,14 +12,12 @@
 <td align="left">1</td>
 <td align="left">
 <b>Navigate to Database Management</b><br>
-
-• Go to OCI Console > Observability & Management > Database Management.<br>
-• Click on Administration > Metric Extensions.<br>
-• Choose the target database for which you want to create the metric extension.<br><br>
-
-<img src="./images/ME1.png" height="100" width="200" align="left">
-
-&nbsp;
+<ul>
+<li>Go to OCI Console &gt; Observability &amp; Management &gt; Database Management.</li>
+<li>Click on <b>Administration &gt; Metric Extensions</b>.</li>
+<li>Choose the target database for which you want to create the metric extension.</li>
+</ul>
+<img src="./images/ME1.png" height="100" width="200">
 </td>
 <td align="left">
 Ensure that Database Management is already enabled for your target database before proceeding with metric extension creation.
@@ -30,88 +27,78 @@ Ensure that Database Management is already enabled for your target database befo
 <tr>
 <td align="left">2</td>
 <td align="left">
-<b>Create Metric Extension at the CDB level</b><br>
-
-• Click on Create Metric Extension.<br>
-• Fill in the metric extension details as shown below —
+<b>Create a Metric Extension at the CDB Level</b><br>
+<ul>
+<li>Click on <b>Create Metric Extension</b>.</li>
+<li>Fill in the metric extension details as shown below:</li>
+</ul>
 
 <b>Example: Current Number of Active Sessions</b><br>
 
-```sql
-SELECT COUNT(*) AS active_sessions 
+<pre><code>SELECT COUNT(*) AS active_sessions 
 FROM V$SESSION 
-WHERE STATUS = 'ACTIVE';
-```
+WHERE STATUS = 'ACTIVE';</code></pre>
+<p>Use this when the target level is CDB.</p>
 
-Use this when target level is CDB.
-
-<img src="./images/ME2.png" height="100" width="200" >&nbsp;&nbsp;&nbsp;
-<img src="./images/ME3.png" height="100" width="200" ><br>
-
-&nbsp;
+<img src="./images/ME2.png" height="100" width="200"><br><br>
+<img src="./images/ME3.png" height="100" width="200"><br>
 </td>
 <td align="left">
-The SQL must return only one value to represent the metric point on the graph. It could be a string or a number.
-
-The unit field must be a valid unit: 'percent', 'count', 'seconds', 'MB', etc.
+The SQL must return only one value to represent the metric point on the graph. It must be a numeric value.<br><br>
+The unit field must be a valid unit: <code>percent</code>, <code>count</code>, <code>seconds</code>, <code>MB</code>, etc.
 </td>
 </tr>
 
 <tr>
 <td align="left">3</td>
 <td align="left">
 <b>Test the Metric Extension</b><br>
-
-Enter the details as shown in the example above and click on Create and test.
-
-In the next window, select the database to test with and click on Test as shown below.
-
+<ul>
+<li>Enter the details as shown in the example above and click on <b>Create and test</b>.</li>
+<li>In the next window, select the database to test with and click on <b>Test</b> as shown below.</li>
+</ul>
 <img src="./images/ME4.png" height="100" width="200"><br>
-
-It may take a few seconds to a couple of minutes to complete the tests and return the results. Once you see “Success,” the results will be displayed.
-
+<p>It may take a few seconds to a couple of minutes to complete the test and return the results. Once you see “Success,” the results will be displayed.</p>
 <img src="./images/ME5.png" height="100" width="200"><br>
-
-Note the Test ID here.
+<p>Note the Test ID here.</p>
 </td>
 <td align="left">
 The metric extension will fail if:<br>
-- SQL is invalid.<br>
+- The SQL is invalid.<br>
 - Required privileges are missing.<br>
-- Output columns or types are incorrect.<br>
-
-Hence login to the DB beforehand and test the SQL first to ensure the queries are valid and return the expected data.
+- Output columns or data types are incorrect.<br>
+<br>
+It is recommended to log in to the database and test your SQL query beforehand to ensure it is valid and returns the expected data.
 </td>
 </tr>
 
 <tr>
 <td align="left">4</td>
 <td align="left">
 <b>Verify Metric in Monitoring Service</b><br>
-• Leave the previous page as it is and open a new tab or duplicate the tab and follow the steps below.<br>
-• From the main menu — OCI Console > Observability & Management > Monitoring > Metrics Explorer<br>
-• Now select the following as shown. Note that the metric namespace would be the one ending with appmgmt_test and click on Update Chart.<br>
-
+<ul>
+<li>Leave the previous page as is, and open a new tab (or duplicate the tab) to follow these steps:</li>
+<li>From the main menu, go to OCI Console &gt; Observability &amp; Management &gt; Monitoring &gt; Metrics Explorer.</li>
+<li>Select the following options as shown. Note that the metric namespace will end with <code>appmgmt_test</code>. Click on <b>Update Chart</b>.</li>
+</ul>
 <img src="./images/ME6.png" height="100" width="200"><br>
 <img src="./images/ME7.png" height="100" width="200"><br>
-Then you will be able to view this metric in the metric graph above.
+<p>You will be able to view the metric in the chart above.</p>
 </td>
 <td align="left">
-During testing phase, use the namespace ending with "appmgmt_test" to verify the metric is working correctly before publishing.
+During the testing phase, use the namespace ending with <code>appmgmt_test</code> to verify that the metric is working as expected before publishing.
 </td>
 </tr>
 
 <tr>
 <td align="left">5</td>
 <td align="left">
 <b>Publish the Metric</b><br>
-
-Now that we successfully see what we want, let us go ahead and publish this metric.<br>
-Go back to the metric extension page, click on Publish and then confirm Publish.
-
+<ul>
+<li>Once you have confirmed the metric is working, return to the metric extension page and click on <b>Publish</b>. Then confirm the publish operation.</li>
+</ul>
 <img src="./images/ME8.png" height="100" width="200"><br>
-
-It should now be listed in the main page of Metric Extensions as shown.<br>
+<p>The metric extension will now be listed on the main page of Metric Extensions as shown:</p>
 <img src="./images/ME9.png" height="100" width="200"><br>
 </td>
 <td align="left">
@@ -122,109 +109,97 @@ Publishing makes the metric extension available for enabling on target databases
 <tr>
 <td align="left">6</td>
 <td align="left">
-<b>Enable Metric Extension</b><br>
-
-Click on the 3-dots menu and click on Enable > Select resources.<br> 
-Select the database from the list and click Enable on selected resources.<br>
-Confirm Enable again when asked.<br>
-
-<img src="./images/ME10.png" height="100" width="200"><br>
-
-
-<img src="./images/ME11.png" height="100" width="200"><br>
-
+<b>Enable the Metric Extension</b><br>
+<ul>
+<li>Click on the three-dots menu and select <b>Enable &gt; Select resources</b>.</li>
+<li>Select the database from the list and click <b>Enable on selected resources</b>.</li>
+<li>Confirm the enable action when prompted.</li>
+</ul>
+<img src="./images/ME10.png" height="100" width="200"><br><br>
+<img src="./images/ME11.png" height="100" width="200"><br><br>
 <img src="./images/ME12.png" height="100" width="200"><br>
-
-This will take some time to execute and once you see success, check back after at least 5–6 minutes to see at least 2 metric points on the Metrics Explorer graph as shown below.
+<p>This may take some time to execute. After you see success, check back after at least 5–6 minutes to see at least two metric points on the Metrics Explorer graph, as shown below.</p>
 </td>
 <td align="left">
-Allow sufficient time for the metric collection to start. Initial data points may take 5-6 minutes to appear in the monitoring system.
+Allow sufficient time for metric collection to start. Initial data points may take 5–6 minutes to appear in the monitoring system.
 </td>
 </tr>
 
 <tr>
 <td align="left">7</td>
 <td align="left">
 <b>View Metrics in Monitoring Service</b><br>
-
-Now that we have already published the metric extension, make sure to select the namespace appmgmt and not the test one as before.<br>
-
+<ul>
+<li>After publishing the metric extension, make sure to select the namespace <code>appmgmt</code> (not the test one used earlier).</li>
+</ul>
 <img src="./images/ME13.png" height="100" width="200"><br>
-
-Click on Update Chart and review the graph.<br>
+<p>Click on <b>Update Chart</b> and review the graph:</p>
 <img src="./images/ME14.png" height="100" width="200"><br>
-
-Click on Show Data Table to see the metric values clearly<br>
+<p>Click on <b>Show Data Table</b> to see the metric values clearly:</p>
 <img src="./images/ME15.png" height="100" width="200"><br>
-
 </td>
 <td align="left">
-After publishing, use the "appmgmt" namespace (not the test namespace) to view production metrics data.
+After publishing, use the <code>appmgmt</code> namespace (not the test namespace) to view production metrics data.
 </td>
 </tr>
 
 <tr>
 <td align="left">8</td>
 <td align="left">
-<b>Create Metric Extension at the PDB level — % Storage Used in SYSTEM Tablespace in PDB</b><br><br>
-
-```sql
-SELECT
+<b>Create a Metric Extension at the PDB Level — % Storage Used in SYSTEM Tablespace in PDB</b><br>
+<br>
+<pre><code>SELECT
     ROUND((1 - (b.BYTES_FREE / a.BYTES_ALLOC)) * 100, 2) AS pct_used
 FROM
     (SELECT SUM(BYTES) AS BYTES_ALLOC
      FROM DBA_DATA_FILES
      WHERE TABLESPACE_NAME = 'SYSTEM') a,
     (SELECT SUM(BYTES) AS BYTES_FREE
      FROM DBA_FREE_SPACE
-     WHERE TABLESPACE_NAME = 'SYSTEM') b;
-```
-
-Use this when Target Level is PDB.
-
-Follow the exact same steps as we did for CDB query above. I will only note the changes below.<br>
+     WHERE TABLESPACE_NAME = 'SYSTEM') b;</code></pre>
+<p>Use this when the target level is PDB.</p>
+<ul>
+<li>Follow the same steps as for the CDB-level query above. Note the following changes:</li>
+</ul>
 <img src="./images/ME16.png" height="100" width="200"><br>
-Select Pluggable DB for PDB level query. Test, Publish and Enable as we did earlier.<br>
+<p>Select Pluggable DB for PDB-level queries. Test, publish, and enable as before.</p>
 <img src="./images/ME17.png" height="100" width="200"><br>
-
 </td>
 <td align="left">
-For PDB-level metrics, ensure you select "Pluggable DB" as the target level and that the SQL query is appropriate for PDB context.
+For PDB-level metrics, ensure you select "Pluggable DB" as the target level and that the SQL query is appropriate for the PDB context.
 </td>
 </tr>
 
 <tr>
 <td align="left">9</td>
 <td align="left">
 <b>View PDB Metrics</b><br>
-
-Go to Monitoring -> Metrics Explorer and select these options.<br>
-
+<ul>
+<li>Go to Monitoring &gt; Metrics Explorer and select the appropriate options.</li>
+</ul>
 <img src="./images/ME18.png" height="100" width="200"><br>
-
-Click on Update to view the captured metrics.<br>
+<p>Click <b>Update</b> to view the captured metrics.</p>
 <img src="./images/ME19.png" height="100" width="200"><br>
 </td>
 <td align="left">
 PDB-level metrics will appear under the same monitoring namespace but will be specific to the pluggable database context.
 </td>
 </tr>
-
 </tbody>
 </table>
 
-## **Important Notes**
+## Important Notes
 
-- The SQL must return only one value to represent the metric point on the graph. It could be a string or a number.
-- The unit field must be a valid unit: 'percent', 'count', 'seconds', 'MB', etc.
+- The SQL must return only one value to represent the metric point on the graph. It must be a numeric value.
+- The unit field must be a valid unit: <code>percent</code>, <code>count</code>, <code>seconds</code>, <code>MB</code>, etc.
 - The metric extension will fail if:
-  - SQL is invalid.
+  - The SQL is invalid.
   - Required privileges are missing.
   - Output columns or types are incorrect.
 
-Here's an example of what an incorrect SQL query error would look like during Test phase.<br>
+Here is an example of an error that would occur with an incorrect SQL query during the test phase:<br>
 <img src="./images/ME20.png" height="100" width="200"><br>
-Hence login to the DB beforehand and test the SQL first to ensure the queries are valid and return the expected data.
+It is recommended to log in to the database and test the SQL first to ensure the queries are valid and return the expected data.
 
 ---
 

manageability-and-operations/observability-and-manageability/database-management/README.md

@@ -14,6 +14,7 @@ Reviewed: 27.09.2024
 - [Database Management Demo](https://www.youtube.com/watch?v=3k9jrkOlBkc)
 - [OCI Database Management PDB Support](https://learnoci.cloud/oci-database-management-new-features-announced-f9991cba2cc2)
 - [How to enable OCI Observability for OCI native database deploy](https://medium.com/@erikasciunzi/enable-observability-for-oci-native-database-deploy-235484953e46)
+- [Creating Metric Extensions for Oracle Database using OCI Database Management Service](./Custom%20Metrics/README.md)
 
 # Useful Links