Documentation Plugins Oracle data source Get started (Cloud)

Get started with Oracle on Grafana Cloud

This guide walks you through connecting your Oracle Database to Grafana Cloud and visualizing your first query. The entire process takes under 10 minutes.

Prerequisites

Before you begin, ensure you have:

• A Grafana Cloud Pro or Advanced plan.
• An Oracle Database instance.
• A database user with SELECT permissions on the tables you want to query. Refer to Create a least-privilege database user for setup instructions.
• If your database is on a private network: A Linux host in the same network to run the PDC agent.

Step 1: Install the plugin

1. In your Grafana Cloud instance, navigate to Administration > Plugins and data > Plugins.
2. Search for Oracle.
3. Click Install.

The plugin is ready to use immediately after installation.

Step 2: Connect to a private database (optional)

If your Oracle Database is behind a firewall or on a private network, set up Private data source connect (PDC) to create a secure tunnel:

1. Navigate to Connections > Private data source connect.

2. Click Add new network and follow the setup wizard.

3. Install the PDC agent on a host in the same network as your Oracle Database:

   Bash Copy

   curl -sL https://raw.githubusercontent.com/grafana/pdc-agent/main/production/install.sh | bash

4. Start the agent and verify it shows a Connected status in the Grafana Cloud UI.

5. Confirm the agent host can reach your Oracle Database: nc -zv <oracle-host> 1521.

For detailed instructions, refer to Configure Private data source connect.

Step 3: Configure the data source

1. Navigate to Connections > Add new connection.

2. Search for Oracle Database and select it.

3. Click Add new data source.

4. Fill in the connection settings:

   Expand table

   Setting	Value
   Host	Your Oracle host and port (for example, oracle-db.example.com:1521)
   Database	The service name or SID
   User	The database username
   Password	The database password

5. If you set up PDC in Step 2, select your PDC network from the Private data source connect dropdown.

6. Click Save & test.

On success, you’ll see a message like: Success: Oracle Database 19c Enterprise Edition Release 19.0.0.0.0 - Production.

If the connection fails, refer to Troubleshoot connection errors.

Step 4: Write your first query

1. Navigate to Explore in the left-side menu.

2. Select your new Oracle data source from the dropdown.

3. Paste the following query to verify connectivity and see active sessions:

   SQL Copy

   SELECT
     status,
     COUNT(*) AS session_count
   FROM V$SESSION
   WHERE username IS NOT NULL
   GROUP BY status

4. Click Run query. You should see a table with session statuses and counts.

Try a time-series query to see data on a graph:

SQL Copy

SELECT
  $__timeGroup(begin_time, '5m') AS time,
  metric_name AS metric,
  ROUND(average, 2) AS value
FROM V$SYSMETRIC_HISTORY
WHERE $__timeFilter(begin_time)
  AND metric_name = 'CPU Usage Per Sec'
GROUP BY $__timeGroup(begin_time, '5m'), metric_name, ROUND(average, 2)
ORDER BY time

Set the Format as dropdown to Time series to see the result as a graph.

Step 5: Build a dashboard

1. Click + > New dashboard > Add visualization.
2. Select your Oracle data source.
3. Paste a time-series query (like the CPU example above).
4. Choose a visualization type (Time series, Stat, Gauge, or Table).
5. Click Apply to add the panel.
6. Repeat for additional panels, then click Save dashboard.

Starter panels to consider:

Next steps

• Oracle query editor—macros, data types, and advanced query patterns.
• Template variables—create dynamic dashboards with drop-down filters.
• Annotations—overlay deployment or event markers on your graphs.
• Alerting—get notified when metrics cross thresholds.
• Troubleshooting—solutions for common issues.