Plugin info

name: ora-ts-status

Collects tablespace capacity statistics for an oracle database instance and emits low capacity events

Prerequisites

• Linux
  • User Groups: oinstall, dba
• Windows
  • Group Memeberships: ORA_HOMENAME_DBA

Important, if the connection to the database/ASM takes place over BEQ, the process resource limits for myrmex-ad must match those set for the oracle database/ASM processes. Set these limits in the systemd unit file for myrmex-ad and then reload and restart the myrmex-ad service. Refer to https://www.man7.org/linux/man-pages/man5/systemd.exec.5.html#PROCESS_PROPERTIES (opens new window) for the process limit directives and their ulimit equivalents.

Events

• myrmex/ora-ts-status/sid/tablespace/low set to 1 when tablespace capacity is low
  • Dimensions
    • sid: the SID the tablespace belongs to
    • tablespace: the name of the tablespace
• myrmex/plugins/error/plugin/msg set to error message on plugin execution failure
  • Dimensions
    • plugin the name of the plugin that failed

Configuration

Plugin is configured with a yaml file:

• instance_name: unique identifier for this database instance that will appear in emmited events. It does not affect the connection parameters.

• timeout: execution timeout in duration format (opens new window). Defaults to 10s

• source: the value that will appear as the source of metrics generated by this configuration. defaults to instance_name

• oracle_home: set this only if you are logging on via a local (BEQ) connection. Not required when connecting via Oracle Net

• oracle_sid: set this only if you are logging on via a local (BEQ) connection. Not required when connecting via Oracle Net

• oracle_logon: the connection string just like in sqlplus. If the username or password contain the characters '@', '/', ' ' escape them in double quotes just like you would do for sqlplus; for example:

  oracle_logon: '"user@name"/"passw@rd"@//localhost:1521/TEST'
  // same applies for secrets
  oracle_logon: '"user@name"/"${polaris.db.test.pwd}"@//localhost:1521/TEST'
  

• default_trigger_policy: defines when to trigger space allocation notifications for a tablespaces based on free space limit

  • free_limit: absolute or relative limit on the free space for a tablespace. format is <amount>%|g|gb|m|mb|k|kb

• trigger_policies: list of tablespce specific policies

  • name_regexp: specifies the tablespaces that uses this policy in terms of a regular expression
  • names: specifies a list if tablespaces that use this policy in terms of a list

Example Configuration

# the unique identifier for this database instance that will appear in the metrics. It does not affect the connection paramters
instance_name: suwpdb1

# set this only if you are logging on via a local (BEQ) connection. Not required when connecting via Oracle Net
oracle_home: /u01/app/oracle/product/12.2.0.1/dbhome_1
# set this only if you are logging on via a local (BEQ) connection. Not required when connecting via Oracle Net
oracle_sid: suwpdb1
# the connection string just like in sqlplus
# {<username>/<password>[@<connect_identifier>] | / } [AS {SYSDBA | SYSOPER | SYSASM}]
# local connection examples. make sure that you have set params oracle_home and oracle_sid above
#   - / as sysdba
#   - system/password as sysoper
# Oracle Net connection examples:
#   - system/password@//localhost:1521/MY_INSANCE
# Encypted parameters (such as password or usernames) can be referenced using ${param_name} format
# For example to connect as sys where the password was encrypted in paramter /oracle/MY_INSTNCE/sys_pwd:
#   - sys/${/oracle/MY_INSTNCE/sys_pwd}@//localhost:1521/MY_INSANCE
oracle_logon: '/ as sysdba'

# default policy which defines when to trigger space allocation for tablespaces via a free space limit.
# the limit can be an absolute value like 512mb or a relative limit like 5%
# this policy is used when no tablespace specific polices match
# configuration paramters:
#   - "free_limit" defines an absolute or relative limit on the free space for a tablespace
#     the format is "<amount>%|g|gb|m|mb|k|kb" 
default_trigger_policy:
  free_limit: 10%

# one or more tablespce specific policies. 
# configuration is the same as for default_trigger_policy but with additional parameters "name_regexp" and "names"
#   - "name_regexp" defines the tablespaces that use this policy in terms of a regular expression
#   - "names" defines the tablespaces that use this policy in terms of a list
# examples:
#   - any tablespace name that starts with USERS has a free limit of 1gb
#     trigger_policies:
#     - name_regexp: "^USERS"
#       free_limit: 1gb
#   - tablespaces DATA01 and INDEX01 have a free limit of 5%
#     trigger_policies:
#     - names:
#       - DATA01
#       - INDEX01
#       free_limit: 5%
trigger_policies:
  - name_regexp: "^USERS"
    free_limit: 20g
  - name_regexp: "^SYSAUX"
    free_limit: 90%

Validate Configuration

ora-ts-status --run-conf /path/to/config/file.yaml --validate

Testing

Run the plugin from the command line and get any emmited events on stdout

ora-ts-status --run-conf /path/to/config/file.yaml

List events emitted by this plugin

ora-ts-status --events