Quickstart

Before you start

  • Check if your database servers have Diagnostics Pack license (required to generate AWR reports)
  • Check if Python is installed and working
  • Alternatively, setup Statspack
  • Verify AWR retention and interval
  • Verify if SAR (sysstat) is working, see sysstat for details.
  • On UNIX, NMON can be an alternative
  • Prepare to run dbcollect on ALL database hosts (including all RAC nodes)
  • If you have many hosts (say, more than 5), check Ansible

Install

Installing dbcollect is very simple:

  1. Download DBcollect
  2. Put the dbcollect file in /usr/local/bin
  3. Make it executable.

Additional steps may sometimes be required depending on OS and configuration, see below.

Python 2.6+ or 3.6+ needs to be available on the system.

Also see Detailed install instructions

Usage

In order to run dbcollect, these are the high level steps to perform:

  1. Install DBCollect
  2. Run dbcollect on ALL database hosts
  3. Pick up the dbcollect ZIP files and upload them to our secure FTP or other upload site

Also see Important Notes below!

Downloading

DBCollect is a single exeutable file. It can be downloaded here: latest version

Ideally, dbcollect is executed as root (see Security for more info).

If you do not have root access (just DBA rights) you can also install it as any user, however, some configuration details will not be picked up (as they require root access)

Install as root

Just copy dbcollect to /usr/local/bin and make it executable:

chmod 755 /usr/local/bin/dbcollect

If your machine has internet (https) access, you can also use an install oneliner:

curl -L https://github.com/bsjerps/dbcollect/releases/latest/download/dbcollect -o /usr/local/bin/dbcollect && chmod 755 /usr/local/bin/dbcollect

Install as DBA user

The user must have sysdba rights (usually this is the oracle user).

Just copy dbcollect to $HOME/bin and make it executable:

chmod 755 $HOME/bin/dbcollect

If your machine has internet (https) access, you can also use an install oneliner:

curl -L https://github.com/bsjerps/dbcollect/releases/latest/download/dbcollect -o $HOME/bin/dbcollect && chmod 755 $HOME/bin/dbcollect

Verify installation

run dbcollect with the help or version option:

dbcollect -h or dbcollect --version

This requires Python to be installed and setup correctly. DBCollect is a ZipApp package which uses a shebang so it can be executed with python directly (without running it with the python command). If it does not work, just run it with python directly:

python3 /usr/local/bin/dbcollect

On older systems you may need python2. If installed as DBA user, provide the correct full path to dbcollect.

Run dbcollect

Simply run dbcollect without any parameters (should work in most cases):

dbcollect

Sometimes you get an error such as this:

[DBC-E021] No AWR or Statspack detected for <instance> (try --license-ok)

This is because dbcollect generates AWR reports, which requires a Diagnostics Pack license. If you have Diagnostics Pack, run dbcollect like this:

dbcollect --license-ok

This will generate all AWR reports even if prior AWR usage is not detected.

The runtime may vary but is usually a few minutes to a few hours (depending on how many databases, retention, etc)

How to get the workload data

After dbcollect is finished, get the dbcollect zip files from /tmp/dbcollect-<hostname>-<timestamp>.zip

Cleanup old DBCollect files

run dbcollect --cleanup.

Important notes

  1. DBCollect should run on all database hosts (including all RAC nodes). Do not skip RAC nodes (we need all data)!
  2. Do NOT install dbcollect in /tmp, /root or any other protected directories. Best is to simply stick with /usr/local/bin.
  3. Do not try to install dbcollect using git clone. It is not designed to run from source code directly.
  4. Transfer the DBCollect ZIP files unmodified (do not unzip and then re-zip). Use BINARY transfer in tools such as WinSCP or FileZilla.