Oracle databases expose a huge amount of performance information through dynamic performance views. The difficult part is not obtaining a metric at this exact moment. It is retaining enough connected evidence to investigate what happened after the workload has already changed.
That is the problem I built Harry Performance Scraper for Oracle Database to solve.
Harry is an open-source performance data pipeline. It periodically collects SQL statistics, session activity, waits, blocking information, execution plans and system metrics from Oracle Database, stores that history in PostgreSQL, and makes it available through Grafana or plain SQL.
Grafana is the interface. The PostgreSQL repository is the evidence.
Performance monitoring needs more than current metrics
A conventional monitoring stack is excellent at answering operational questions:
- Is the database available?
- How much CPU is it using?
- Is a tablespace filling up?
- How many sessions are connected?
- Has a counter crossed an alerting threshold?
These are important questions, and tools such as Prometheus are extremely good at answering them.
Performance investigations require a different kind of information. If database activity increased twenty minutes ago, I want to know:
- which sessions were active;
- which SQL statements they were executing;
- which events they were waiting for;
- which modules and programs created the workload;
- whether sessions were blocking one another;
- which execution plans were involved;
- and how those facts changed during the same time window.
A graph showing that active sessions increased is a metric. The identities of those sessions, their SQL, waits, plans and relationships are the evidence required to explain the graph.
Once the sessions disconnect or begin doing something else, much of that evidence is gone unless something collected it.
The architecture
Harry separates the collection, storage and presentation layers:
The collectors run scheduled queries against Oracle dynamic performance views. Different types of information are collected at different intervals because not every fact changes at the same rate or has the same cost.
The default schedule currently includes:
| Data | Default interval |
|---|---|
| Database activity history | 2 seconds |
| SQL statistics, sessions and blocking | 15 seconds |
| Operational metrics | 1 minute |
| SQL text and execution-plan discovery | 2 minutes |
Every interval is configurable per collector. A small development database and a busy production estate do not need to use the same sampling policy.
Harry writes the collected information into a relational PostgreSQL schema. High-frequency samples are kept separate from SQL text, execution plans and other slowly changing data. Time-based data can be partitioned and retention is configurable.
This matters because repeatedly copying the full SQL text or execution plan into every sample would waste storage and make the repository harder to query. Harry instead stores different kinds of evidence according to their own lifecycle and connects them through relational keys.
Why PostgreSQL instead of Prometheus?
I use Prometheus extensively. It is an excellent choice for numeric time-series data, operational monitoring and alerting. Harry does not exist because Prometheus is bad at those jobs.
It exists because an Oracle performance incident is not only a collection of numeric time series.
The information involved includes high-cardinality identifiers and relationships:
- database and instance;
- session ID and serial number;
- SQL ID and plan hash value;
- module, action and program;
- wait class and wait event;
- blocking and blocked sessions;
- SQL text;
- execution-plan operations.
Some of these values make reasonable dimensions for a metric. Treating all of them as labels, however, can create a large number of series. SQL text and execution plans are not natural metric labels at all.
The questions asked during an investigation are relational as well:
- Show the SQL executed by the sessions contributing to this wait class.
- Compare the plans used by the same SQL during two different periods.
- Find the blockers behind the sessions visible in this activity spike.
- Group activity by module, program, event, SQL or session without deciding every future grouping when the data is ingested.
PostgreSQL gives Harry a natural representation for that information. It also means the collected data is not locked inside Harry: DBAs can query it directly, join it with their own information, build new Grafana panels or export it using standard tools.
Prometheus can continue monitoring the infrastructure and handling conventional metrics. Harry adds the detailed, relational history needed for Oracle performance analysis.
Harry's Database Activity History
One of Harry's main collectors samples active database work every two seconds and builds Database Activity History (DAH).
DAH can be explored by:
- wait class;
- wait event;
- SQL ID;
- session;
- module;
- program;
- instance;
- and other collected dimensions.
The corresponding Grafana dashboard presents the samples as an activity timeline with supporting SQL, session, wait, module and program breakdowns. Selecting a time range makes it possible to move from an overall workload spike to the SQL, sessions or waits that formed it.
This is not a summary generated after the incident. It is the sequence of samples retained while the activity was occurring.
Harry can then correlate that window with SQL statistics and session history instead of stopping at “database activity was high.”
From activity to the SQL responsible
The following demo workload shows how the Top Consumers dashboard connects a selected SQL statement with its workload, I/O, plan history, full text and execution plan.
From there, an investigation can continue into:
- executions and elapsed time;
- CPU and wait contribution;
- buffer activity and reads;
- SQL text;
- plan hash values;
- execution-plan contents;
- plan changes across time.
Grafana is useful here because the time range and variables provide a fast way to navigate the repository. It is not mandatory. The same information remains accessible as relational data through PostgreSQL.
That distinction is deliberate: dashboards should accelerate an investigation, not define the limits of what can be investigated.
ASH, AWR and Oracle licensing
Harry's Database Activity History is not Oracle Active Session History.
By default, Harry builds its own sampled history from non-ASH dynamic performance views. It does not present external sampling as a reimplementation of every semantic or capability provided by Oracle ASH or AWR.
Optional ASH collection can be enabled in environments that are appropriately licensed and configured to use it. Because Oracle feature licensing depends on the environment and contract, operators must verify their own licensing position before enabling optional collectors that query licensed sources.
Keeping this boundary explicit is important. The objective is to provide useful and transparent performance history, not to hide where the information originated.
Operating the collector
Performance history only has value if the collector is available when the incident occurs. Harry therefore supports multiple collector instances with leader election and automatic failover.
The PostgreSQL repository supports partitioned storage and configurable retention, allowing deployments to choose how much history to preserve. Grafana can also create native alerts directly from Harry's PostgreSQL data.
The components remain independent:
- Oracle Database is the performance source.
- Harry performs scheduled collection.
- PostgreSQL retains and relates the evidence.
- Grafana provides dashboards and alerting.
- Standard SQL provides unrestricted direct access to the repository.
This makes the deployment self-hosted and avoids a proprietary performance-data backend.
Try Harry
Harry Performance Scraper for Oracle Database is open source and under active development.
- Project and documentation: harryperformance.com
- Live Grafana demo: demo.harryperformance.com
- Source code: GitHub repository
- Published Grafana dashboard: Harry – Database Activity History for Oracle Database (DAH)
I am particularly interested in feedback from DBAs operating real Oracle workloads:
Which piece of evidence do you most often discover was missing only after a performance incident had already ended?
Top comments (1)
Nice approach to avoid the license!
Coming from system archiceture / game dev, I'm curious how does the collector behave under heavy DB load? Do you run a fixed polling interval, or is there any dynamic throttling to protect the target server when CPU spikes?