Skip to content

Commit 4a73285

Browse files
rishabh-ghosh24rishabh-ghosh24
committed
creating Metric extensions for Oracle Database
added new documentation for creating metric extensions for Oracle databases
1 parent 5fc257a commit 4a73285

File tree

27 files changed

+267
-0
lines changed

27 files changed

+267
-0
lines changed

‎.DS_Store‎

2 KB
Binary file not shown.

‎manageability-and-operations/.DS_Store‎

6 KB
Binary file not shown.

‎manageability-and-operations/observability-and-manageability/.DS_Store‎

6 KB
Binary file not shown.

‎manageability-and-operations/observability-and-manageability/database-management/.DS_Store‎

6 KB
Binary file not shown.

‎manageability-and-operations/observability-and-manageability/database-management/Custom Metrics/.DS_Store‎

8 KB
Binary file not shown.

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Creating Metric Extensions for Database using OCI Database Management Service
2+
3+
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.
4+
5+
This guide explains how to create metric extensions step by step.
6+
7+
## What Are Metric Extensions?
8+
9+
**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).
10+
11+
## Note
12+
[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.
13+
14+
## Prerequisites
15+
16+
- OCI tenancy with Database Management enabled
17+
- 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)
18+
- 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
19+
20+
## Step-by-Step Guide
21+
[Implementation Steps](./create_metric_extension.md)
22+
23+
# License
24+
25+
Copyright (c) 2025 Oracle and/or its affiliates.
26+
27+
Licensed under the Universal Permissive License (UPL), Version 1.0.
28+
29+
See [LICENSE](https://github.com/oracle-devrel/technology-engineering/blob/main/LICENSE) for more details.

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

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
2+
# **Implementation Steps**
3+
4+
<table>
5+
<tbody>
6+
<tr>
7+
<th align="left">Steps</th>
8+
<th align="left">Description</th>
9+
<th align="left">Notes</th>
10+
</tr>
11+
12+
<tr>
13+
<td align="left">1</td>
14+
<td align="left">
15+
<b>Navigate to Database Management</b><br>
16+
17+
• Go to OCI Console > Observability & Management > Database Management.<br>
18+
• Click on Administration > Metric Extensions.<br>
19+
• Choose the target database for which you want to create the metric extension.<br><br>
20+
21+
<img src="./images/ME1.png" height="100" width="200" align="left">
22+
23+
&nbsp;
24+
</td>
25+
<td align="left">
26+
Ensure that Database Management is already enabled for your target database before proceeding with metric extension creation.
27+
</td>
28+
</tr>
29+
30+
<tr>
31+
<td align="left">2</td>
32+
<td align="left">
33+
<b>Create Metric Extension at the CDB level</b><br>
34+
35+
• Click on Create Metric Extension.<br>
36+
• Fill in the metric extension details as shown below —
37+
38+
<b>Example: Current Number of Active Sessions</b><br>
39+
40+
```sql
41+
SELECT COUNT(*) AS active_sessions
42+
FROM V$SESSION
43+
WHERE STATUS = 'ACTIVE';
44+
```
45+
46+
Use this when target level is CDB.
47+
48+
<img src="./images/ME2.png" height="100" width="200" >&nbsp;&nbsp;&nbsp;
49+
<img src="./images/ME3.png" height="100" width="200" ><br>
50+
51+
&nbsp;
52+
</td>
53+
<td align="left">
54+
The SQL must return only one value to represent the metric point on the graph. It could be a string or a number.
55+
56+
The unit field must be a valid unit: 'percent', 'count', 'seconds', 'MB', etc.
57+
</td>
58+
</tr>
59+
60+
<tr>
61+
<td align="left">3</td>
62+
<td align="left">
63+
<b>Test the Metric Extension</b><br>
64+
65+
Enter the details as shown in the example above and click on Create and test.
66+
67+
In the next window, select the database to test with and click on Test as shown below.
68+
69+
<img src="./images/ME4.png" height="100" width="200"><br>
70+
71+
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.
72+
73+
<img src="./images/ME5.png" height="100" width="200"><br>
74+
75+
Note the Test ID here.
76+
</td>
77+
<td align="left">
78+
The metric extension will fail if:<br>
79+
- SQL is invalid.<br>
80+
- Required privileges are missing.<br>
81+
- Output columns or types are incorrect.<br>
82+
83+
Hence login to the DB beforehand and test the SQL first to ensure the queries are valid and return the expected data.
84+
</td>
85+
</tr>
86+
87+
<tr>
88+
<td align="left">4</td>
89+
<td align="left">
90+
<b>Verify Metric in Monitoring Service</b><br>
91+
• Leave the previous page as it is and open a new tab or duplicate the tab and follow the steps below.<br>
92+
• From the main menu — OCI Console > Observability & Management > Monitoring > Metrics Explorer<br>
93+
• 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>
94+
95+
<img src="./images/ME6.png" height="100" width="200"><br>
96+
<img src="./images/ME7.png" height="100" width="200"><br>
97+
Then you will be able to view this metric in the metric graph above.
98+
</td>
99+
<td align="left">
100+
During testing phase, use the namespace ending with "appmgmt_test" to verify the metric is working correctly before publishing.
101+
</td>
102+
</tr>
103+
104+
<tr>
105+
<td align="left">5</td>
106+
<td align="left">
107+
<b>Publish the Metric</b><br>
108+
109+
Now that we successfully see what we want, let us go ahead and publish this metric.<br>
110+
Go back to the metric extension page, click on Publish and then confirm Publish.
111+
112+
<img src="./images/ME8.png" height="100" width="200"><br>
113+
114+
It should now be listed in the main page of Metric Extensions as shown.<br>
115+
<img src="./images/ME9.png" height="100" width="200"><br>
116+
</td>
117+
<td align="left">
118+
Publishing makes the metric extension available for enabling on target databases in production.
119+
</td>
120+
</tr>
121+
122+
<tr>
123+
<td align="left">6</td>
124+
<td align="left">
125+
<b>Enable Metric Extension</b><br>
126+
127+
Click on the 3-dots menu and click on Enable > Select resources.<br>
128+
Select the database from the list and click Enable on selected resources.<br>
129+
Confirm Enable again when asked.<br>
130+
131+
<img src="./images/ME10.png" height="100" width="200"><br>
132+
133+
134+
<img src="./images/ME11.png" height="100" width="200"><br>
135+
136+
137+
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.
138+
</td>
139+
<td align="left">
140+
Allow sufficient time for the metric collection to start. Initial data points may take 5-6 minutes to appear in the monitoring system.
141+
</td>
142+
</tr>
143+
144+
<tr>
145+
<td align="left">7</td>
146+
<td align="left">
147+
**View Metrics in Monitoring Service**
148+
149+
Now that we have already published the metric extension, make sure to select the namespace appmgmt and not the test one as before.
150+
151+
<img src="../images/MONITORING_PROD.png" height="100" width="200" align="left">
152+
153+
&nbsp;
154+
155+
Click on Update Chart and review the graph.
156+
157+
Click on Show Data Table to see the metric values clearly.
158+
</td>
159+
<td align="left">
160+
After publishing, use the "appmgmt" namespace (not the test namespace) to view production metrics data.
161+
</td>
162+
</tr>
163+
164+
<tr>
165+
<td align="left">8</td>
166+
<td align="left">
167+
**Example 2: PDB-Level Metric — % Used in SYSTEM Tablespace in PDB**
168+
169+
```sql
170+
SELECT
171+
ROUND((1 - (b.BYTES_FREE / a.BYTES_ALLOC)) * 100, 2) AS pct_used
172+
FROM
173+
(SELECT SUM(BYTES) AS BYTES_ALLOC
174+
FROM DBA_DATA_FILES
175+
WHERE TABLESPACE_NAME = 'SYSTEM') a,
176+
(SELECT SUM(BYTES) AS BYTES_FREE
177+
FROM DBA_FREE_SPACE
178+
WHERE TABLESPACE_NAME = 'SYSTEM') b;
179+
```
180+
181+
Use this when Target Level is PDB.
182+
183+
Follow the exact same steps as we did for CDB query above. I will only note the changes below.
184+
185+
Select Pluggable DB for PDB level query. Test, Publish and Enable as we did earlier.
186+
187+
<img src="../images/PDB_METRIC.png" height="100" width="200" align="left">
188+
189+
&nbsp;
190+
</td>
191+
<td align="left">
192+
For PDB-level metrics, ensure you select "Pluggable DB" as the target level and that the SQL query is appropriate for PDB context.
193+
</td>
194+
</tr>
195+
196+
<tr>
197+
<td align="left">9</td>
198+
<td align="left">
199+
**View PDB Metrics**
200+
201+
Go to Monitoring -> Metrics Explorer and select these options.
202+
203+
<img src="../images/PDB_MONITORING.png" height="100" width="200" align="left">
204+
205+
&nbsp;
206+
207+
Click on Update to view the captured metrics.
208+
</td>
209+
<td align="left">
210+
PDB-level metrics will appear under the same monitoring namespace but will be specific to the pluggable database context.
211+
</td>
212+
</tr>
213+
214+
</tbody>
215+
</table>
216+
217+
## **Important Notes**
218+
219+
- The SQL must return only one value to represent the metric point on the graph. It could be a string or a number.
220+
- The unit field must be a valid unit: 'percent', 'count', 'seconds', 'MB', etc.
221+
- The metric extension will fail if:
222+
- SQL is invalid.
223+
- Required privileges are missing.
224+
- Output columns or types are incorrect.
225+
226+
Here's an example of what an incorrect SQL query error would look like during Test phase.
227+
228+
Hence login to the DB beforehand and test the SQL first to ensure the queries are valid and return the expected data.
229+
230+
---
231+
232+
# License <!-- omit from toc -->
233+
234+
Copyright (c) 2025 Oracle and/or its affiliates.
235+
236+
Licensed under the Universal Permissive License (UPL), Version 1.0.
237+
238+
See [LICENSE](/LICENSE) for more details.

‎manageability-and-operations/observability-and-manageability/database-management/Custom Metrics/images/ME1.png‎

83 KB
Loading

‎manageability-and-operations/observability-and-manageability/database-management/Custom Metrics/images/ME10.png‎

12 KB
Loading

‎manageability-and-operations/observability-and-manageability/database-management/Custom Metrics/images/ME11.png‎

7.93 KB
Loading

0 commit comments

Comments
 (0)