plugin_name: python.d.plugin
modules:
  - meta:
      plugin_name: python.d.plugin
      module_name: oracledb
      monitored_instance:
        name: Oracle DB
        link: "https://docs.oracle.com/en/database/oracle/oracle-database/"
        categories:
          - data-collection.database-servers
        icon_filename: "oracle.svg"
      related_resources:
        integrations:
          list: []
      info_provided_to_referring_integrations:
        description: ""
      keywords:
        - database
        - oracle
        - data warehouse
        - SQL
      most_popular: false
    overview:
      data_collection:
        metrics_description: "This collector monitors OracleDB database metrics about sessions, tables, memory and more."
        method_description: "It collects the metrics via the supported database client library"
      supported_platforms:
        include: []
        exclude: []
      multi_instance: true
      additional_permissions:
        description: |
          In order for this collector to work, it needs a read-only user `netdata` in the RDBMS.
      default_behavior:
        auto_detection:
          description: "When the requirements are met, databases on the local host on port 1521 will be auto-detected"
        limits:
          description: ""
        performance_impact:
          description: ""
    setup:
      prerequisites:
        list:
          - title: Install the python-oracledb package
            description: |
              You can follow the official guide below to install the required package:
              
              Source: https://python-oracledb.readthedocs.io/en/latest/user_guide/installation.html
          - title: Create a read only user for netdata
            description: |
              Follow the official instructions for your oracle RDBMS to create a read-only user for netdata. The operation may follow this approach
              
              Connect to your Oracle database with an administrative user and execute:
              
              ```bash
              CREATE USER netdata IDENTIFIED BY <PASSWORD>;
              
              GRANT CONNECT TO netdata;
              GRANT SELECT_CATALOG_ROLE TO netdata;
              ```
          - title: Edit the configuration
            description: |
              Edit the configuration troubleshooting:
              
              1. Provide a valid user for the netdata collector to access the database
              2. Specify the network target this database is listening.
      configuration:
        file:
          name: "python.d/oracledb.conf"
        options:
          description: |
            There are 2 sections:
            
            * Global variables
            * One or more JOBS that can define multiple different instances to monitor.
            
            The following options can be defined globally: priority, penalty, autodetection_retry, update_every, but can also be defined per JOB to override the global values.
            
            Additionally, the following collapsed table contains all the options that can be configured inside a JOB definition.
            
            Every configuration JOB starts with a `job_name` value which will appear in the dashboard, unless a `name` parameter is specified.
          folding:
            title: "Config options"
            enabled: true
          list:
            - name: update_every
              description: Sets the default data collection frequency.
              default_value: 5
              required: false
            - name: priority
              description: Controls the order of charts at the netdata dashboard.
              default_value: 60000
              required: false
            - name: autodetection_retry
              description: Sets the job re-check interval in seconds.
              default_value: 0
              required: false
            - name: penalty
              description: Indicates whether to apply penalty to update_every in case of failures.
              default_value: yes
              required: false
            - name: user
              description: The username for the user account.
              default_value: no
              required: true
            - name: password
              description: The password for the user account.
              default_value: no
              required: true
            - name: server
              description: The IP address or hostname (and port) of the Oracle Database Server.
              default_value: no
              required: true
            - name: service
              description: The Oracle Database service name. To view the services available on your server run this query, `select SERVICE_NAME from gv$session where sid in (select sid from V$MYSTAT)`.
              default_value: no
              required: true
            - name: protocol
              description: one of the strings "tcp" or "tcps" indicating whether to use unencrypted network traffic or encrypted network traffic
              default_value: no
              required: true
        examples:
          folding:
            enabled: true
            title: "Config"
          list:
            - name: Basic
              folding:
                enabled: false
              description: A basic example configuration, two jobs described for two databases.
              config: |
                local:
                    user: 'netdata'
                    password: 'secret'
                    server: 'localhost:1521'
                    service: 'XE'
                    protocol: 'tcps'
                
                remote:
                    user: 'netdata'
                    password: 'secret'
                    server: '10.0.0.1:1521'
                    service: 'XE'
                    protocol: 'tcps'
    troubleshooting:
      problems:
        list: []
    alerts: []
    metrics:
      folding:
        title: Metrics
        enabled: false
      description: "These metrics refer to the entire monitored application."
      availability: []
      scopes:
        - name: global
          description: ""
          labels: []
          metrics:
            - name: oracledb.session_count
              description: Session Count
              unit: "sessions"
              chart_type: line
              dimensions:
                - name: total
                - name: active
            - name: oracledb.session_limit_usage
              description: Session Limit Usage
              unit: "%"
              chart_type: area
              dimensions:
                - name: usage
            - name: oracledb.logons
              description: Logons
              unit: "events/s"
              chart_type: area
              dimensions:
                - name: logons
            - name: oracledb.physical_disk_read_writes
              description: Physical Disk Reads/Writes
              unit: "events/s"
              chart_type: area
              dimensions:
                - name: reads
                - name: writes
            - name: oracledb.sorts_on_disks
              description: Sorts On Disk
              unit: "events/s"
              chart_type: line
              dimensions:
                - name: sorts
            - name: oracledb.full_table_scans
              description: Full Table Scans
              unit: "events/s"
              chart_type: line
              dimensions:
                - name: full table scans
            - name: oracledb.database_wait_time_ratio
              description: Database Wait Time Ratio
              unit: "%"
              chart_type: line
              dimensions:
                - name: wait time ratio
            - name: oracledb.shared_pool_free_memory
              description: Shared Pool Free Memory
              unit: "%"
              chart_type: line
              dimensions:
                - name: free memory
            - name: oracledb.in_memory_sorts_ratio
              description: In-Memory Sorts Ratio
              unit: "%"
              chart_type: line
              dimensions:
                - name: in-memory sorts
            - name: oracledb.sql_service_response_time
              description: SQL Service Response Time
              unit: "seconds"
              chart_type: line
              dimensions:
                - name: time
            - name: oracledb.user_rollbacks
              description: User Rollbacks
              unit: "events/s"
              chart_type: line
              dimensions:
                - name: rollbacks
            - name: oracledb.enqueue_timeouts
              description: Enqueue Timeouts
              unit: "events/s"
              chart_type: line
              dimensions:
                - name: enqueue timeouts
            - name: oracledb.cache_hit_ration
              description: Cache Hit Ratio
              unit: "%"
              chart_type: stacked
              dimensions:
                - name: buffer
                - name: cursor
                - name: library
                - name: row
            - name: oracledb.global_cache_blocks
              description: Global Cache Blocks Events
              unit: "events/s"
              chart_type: area
              dimensions:
                - name: corrupted
                - name: lost
            - name: oracledb.activity
              description: Activities
              unit: "events/s"
              chart_type: stacked
              dimensions:
                - name: parse count
                - name: execute count
                - name: user commits
                - name: user rollbacks
            - name: oracledb.wait_time
              description: Wait Time
              unit: "ms"
              chart_type: stacked
              dimensions:
                - name: application
                - name: configuration
                - name: administrative
                - name: concurrency
                - name: commit
                - name: network
                - name: user I/O
                - name: system I/O
                - name: scheduler
                - name: other
            - name: oracledb.tablespace_size
              description: Size
              unit: "KiB"
              chart_type: line
              dimensions:
                - name: a dimension per active tablespace
            - name: oracledb.tablespace_usage
              description: Usage
              unit: "KiB"
              chart_type: line
              dimensions:
                - name: a dimension per active tablespace
            - name: oracledb.tablespace_usage_in_percent
              description: Usage
              unit: "%"
              chart_type: line
              dimensions:
                - name: a dimension per active tablespace
            - name: oracledb.allocated_size
              description: Size
              unit: "B"
              chart_type: line
              dimensions:
                - name: a dimension per active tablespace
            - name: oracledb.allocated_usage
              description: Usage
              unit: "B"
              chart_type: line
              dimensions:
                - name: a dimension per active tablespace
            - name: oracledb.allocated_usage_in_percent
              description: Usage
              unit: "%"
              chart_type: line
              dimensions:
                - name: a dimension per active tablespace