Skip to content
logo
Percona Server for MySQL
The ProcFS plugin
Initializing search
    percona/psmysql-docs
    percona/psmysql-docs
    • Home
      • Release notes index
      • Percona Server for MySQL 8.0.33-25 Update (2023-08-02)
      • Percona Server for MySQL 8.0.33-25 (2023-06-15)
      • Percona Server for MySQL 8.0.32-24 (2023-03-20)
      • Percona Server for MySQL 8.0.31-23 (2023-02-09)
        • Percona Server for MySQL 8.0.30-22 Update (2022-11-21)
        • Percona Server for MySQL 8.0.30-22 (2022-11-21)
        • Percona Server for MySQL 8.0.29-21 (2022-08-08)
        • Percona Server for MySQL 8.0.28-20 (2022-06-20)
        • Percona Server for MySQL 8.0.28-19 (2022-05-12)
        • Percona Server for MySQL 8.0.27-18 (2022-03-02)
        • Percona Server for MySQL 8.0.26-17 (2022-01-26)
        • Percona Server for MySQL 8.0.26-16 (2021-10-20)
        • Percona Server for MySQL 8.0.25-15 (2021-07-13)
        • Percona Server for MySQL 8.0.23-14 (2021-05-12)
        • Percona Server for MySQL 8.0.22-13 (2020-12-14)
        • Percona Server for MySQL 8.0.21-12 (2020-10-13)
        • Percona Server for MySQL 8.0.20-11 (2020-07-21)
        • Percona Server for MySQL 8.0.19-10 (2020-03-23)
        • Percona Server for MySQL 8.0.18-9
        • Percona Server for MySQL 8.0.17-8
        • Percona Server for MySQL 8.0.16-7
        • Percona Server for MySQL 8.0.15-6
        • Percona Server for MySQL 8.0.15-5
        • Percona Server for MySQL 8.0.14
        • Percona Server for MySQL 8.0.13-4
        • Percona Server for MySQL 8.0.13-3
        • Percona Server for MySQL 8.0.12-2rc1
      • Limiting the disk space used by binary log files
      • Extended mysqlbinlog
      • Slow query log rotation and expiration
      • Extended SELECT INTO OUTFILE/DUMPFILE
      • Support for PROXY protocol
      • SEQUENCE_TABLE(n) function
      • Trigger updates
      • Expanded fast index creation
      • Kill idle transactions
      • Percona Toolkit UDFs
      • Utility user
      • The ProcFS plugin
        • Install the PLUGIN manually
        • Access privileges required
        • Using the ProcFS plugin
        • Tables
          • PROCFS
        • Variable
          • procfs_files_spec
        • Limitations
        • Uninstall plugin
      • Adaptive network buffers
      • Thread pool
      • Quickstart guide for Percona Server for MySQL
      • Install Percona Server for MySQL from repositories
        • Use APT repositories
        • Files in DEB package
        • Build APT packages
        • Downloaded DEB packages
        • Apt pinning
        • Run Percona Server for MySQL
        • Uninstall
        • Use RPM repositories
        • Files in RPM package
        • Downloaded RPM packages
        • Run Percona Server for MySQL
        • Uninstall
        • Install with binary tarballs
        • Binary tarballs available
        • Install Percona Server for MySQL from a source tarball
        • Compile Percona Server for MySQL 8.0 from source
        • Install using Docker
        • Docker environment variables
      • Upgrade guide
      • Upgrade using the Percona repositories
      • Upgrade from systems that use the MyRocks or TokuDB storage engine and partitioned tables
      • Upgrade using Standalone Packages
      • Downgrade
      • Binary logs and replication improvements
      • Post-installation
      • Working with AppArmor
      • Working with SELinux
      • Extended SHOW GRANTS
      • Backup and restore overview
      • Backup locks
      • Extended mysqldump
      • Start transaction with consistent snapshot
        • Using LDAP authentication plugins
        • LDAP authentication plugin system variables
      • Data masking
      • PAM authentication plugin
      • SSL improvements
      • Server variables
      • FIDO authentication plugin
      • Encryption functions
        • Data at Rest Encryption
        • Use the keyring component or keyring plugin
          • Using the Key Management Interoperability Protocol (KMIP)
          • Use the Amazon Key Management Service (AWS KMS)
          • Encrypt File-Per-Table Tablespace
          • Encrypt schema or general tablespace
          • Encrypt system tablespace
          • Encrypt temporary files
          • Encrypt Binary Log Files and Relay Log Files
          • Encrypting the Redo Log data
          • Encrypt the undo tablespace
          • Rotate the master key
          • Advanced encryption key rotation
          • Encrypt doublewrite buffers
          • Verify the encryption for tables, tablespaces, and schemas
      • Manage group replication flow control
      • Group replication system variables
      • Audit log plugin
      • Jemalloc memory allocation profiling
      • User statistics
      • Slow query log
      • Process list
      • Misc. INFORMATION_SCHEMA tables
      • Use Percona Monitoring and Management (PMM) Advisors
      • Too many connections warning
      • Handle corrupted tables
      • Thread based profiling
      • Stacktrace
      • Libcoredumper
        • The Percona XtraDB storage engine
        • Improved MEMORY storage engine
        • Improved InnoDB I/O scalability
        • Enforcing storage engine
        • Extended show engine InnoDB status
        • Show storage engines
        • Compressed columns with dictionaries
        • InnoDB full-text search improvements
        • XtraDB changed page tracking
        • XtraDB performance improvements for I/O-bound highly-concurrent workloads
        • Multiple page asynchronous I/O requests
        • Prefix index queries optimization
        • Limit the estimation of records in a Query
        • InnoDB page fragmentation counters
        • Percona MyRocks introduction
        • Percona MyRocks installation guide
        • Updated supported features
        • MyRocks limitations
        • Differences between Percona MyRocks and Facebook MyRocks
        • MyRocks Information Schema tables
        • MyRocks server variables
        • MyRocks status variables
        • Gap locks detection
        • Data loading
        • Installing and configuring Percona Server for MySQL with ZenFS support
        • TokuDB introduction
        • TokuDB installation
        • Use TokuDB
        • Fast updates with TokuDB
        • TokuDB files and file types
        • TokuDB file management
        • TokuDB background ANALYZE TABLE
        • TokuDB variables
        • TokuDB status variables
        • TokuDB fractal tree indexing
        • TokuDB troubleshooting
        • TokuDB Performance Schema integration
        • Frequently asked questions
        • Migrate and removing the TokuDB storage engine
        • Percona TokuBackup
      • List of variables introduced in Percona Server for MySQL 8.0
      • List of features available in Percona Server for MySQL releases
      • Percona Server for MySQL feature comparison
      • Understand version numbers
      • Development of Percona Server for MySQL
      • Trademark policy
      • Index of INFORMATION_SCHEMA tables
      • Frequently asked questions
      • Copyright and licensing information
      • Glossary

    • Install the PLUGIN manually
    • Access privileges required
    • Using the ProcFS plugin
    • Tables
      • PROCFS
    • Variable
      • procfs_files_spec
    • Limitations
    • Uninstall plugin

    The ProcFS plugin¶

    This feature is a tech preview. Before using this feature in production, we recommend that you test restoring production from physical backups in your environment, and also use the alternative backup method for redundancy.

    Implemented in Percona Server for MySQL 8.0.25-15, the ProcFS plugin provides access to the Linux performance counters by running SQL queries against a Percona Server for MySQL 8.0.

    You may be unable to capture operating system metrics in certain environments, such as Cloud installations or MySQL-as-a-Service installations. These metrics are essential for complete system performance monitoring.

    The plugin does the following:

    • Reads selected files from the /proc file system and the /sys file system.

    • Populates the file names and their content as rows in the INFORMATION_SCHEMA.PROCFS view.

    The system variable procfs_files_spec provides access to the /proc and the /sys files and directories. This variable cannot be changed at run time, preventing a compromised account from giving itself greater access to those file systems.

    Install the PLUGIN manually¶

    We recommend installing the plugin as part of the package. If needed, you can install this plugin manually. Copy the procfs.so file to the mysql plugin installation directory and execute the following command:

    INSTALL PLUGIN procfs SONAME 'procfs.so';
    

    Access privileges required¶

    Only users with the ACCESS_PROCFS dynamic privilege can access the INFORMATION_SCHEMA.PROCFS view. During the plugin startup, this dynamic privilege is registered with the server.

    After the plugin installation, grant a user access to the INFORMATION_SCHEMA.PROCFS view by executing the following command:

    GRANT ACCESS_PROCFS ON *.* TO 'user'@'host';
    

    Important

    An SELinux policy or an AppArmor profile may prevent access to file locations needed by the ProcFS plugin, such as the ‘/proc/sys/fs/file-nr’ directory or any sub-directories or files under ‘/proc/irq/’. Either edit the policy or profile to ensure that the plugin has the necessary access. If the policy and profile do not allow access, the plugin may may have unexpected behavior.

    For more information, see Working with SELinux and Working with AppArmor.

    Using the ProcFS plugin¶

    Authorized users can obtain information from individual files by specifying the exact file name within a WHERE clause. Files that are not included are ignored and considered not to exist.

    All files that match the procfs_files_spec are opened, read, stored in memory, and, finally, returned to the client. It is critical to add a WHERE clause to return only specific files to limit the impact of the plugin on the server’s performance. A failure to use a WHERE clause can lead to lengthy query response times, high load, and high memory usage on the server. The WHERE clause can contain either an equality operator, the LIKE operator, or the IN operator. The LIKE operator limits file globbing. You can write file access patterns in the glob(7) style, such as /sys/block/sd[a-z]/stat;/proc/version\*

    The following example returns the proc/version:

    SELECT * FROM INFORMATION_SCHEMA.PROCFS WHERE FILE = '/proc/version';
    

    Tables¶

    PROCFS¶

    The schema definition of the INFORMATION_SCHEMA.PROCFS view is:

    CREATE TEMPORARY TABLE `PROCFS` (
    `FILE` varchar(1024) NOT NULL DEFAULT '',
    `CONTENTS` longtext NOT NULL
    ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
    

    Status variables provide the basic metrics:

    Name Description
    procfs_access_violations The number of attempted queries by users without the ACCESS_PROCFS privilege.
    procfs_queries The number of queries made against the procfs view.
    procfs_files_read The number of files read to provide content
    procfs_bytes_read The number of bytes read to provide content

    Variable¶

    procfs_files_spec¶

    Option Description
    Scope: Global
    Dynamic: Yes
    Read, Write, or Read-Only: Read-Only

    The variable has been implemented in Percona Server for MySQL 8.0.25-14. The default value for procfs_files_spec is: /proc/cpuinfo;/proc/irq//;/proc/loadavg/proc/net/dev;/proc/net/sockstat;/proc/net/sockstat_rhe4;/proc/net/tcpstat;/proc/self/net/netstat;/proc/self/stat;/proc/self/io;/proc/self/numa_maps/proc/softirqs;/proc/spl/kstat/zfs/arcstats;/proc/stat;/proc/sys/fs/file-nr;/proc/version;/proc/vmstat

    Enables access to the /proc and /sys directories and files. This variable is global, read only, and is set by using either the mysqld command line or by editing my.cnf.

    Limitations¶

    The following limitations are:

    • Only first 60k of /proc/ /sys/ files are returned

    • The file name size is limited to 1k

    • The plugin cannot read files if path does not start from /proc or /sys

    • Complex WHERE conditions may force the plugin to read all configured files.

    Uninstall plugin¶

    The following statement removes the procfs plugin.

    UNINSTALL PLUGIN procfs;
    

    Contact us

    For free technical help, visit the Percona Community Forum.

    To report bugs or submit feature requests, open a JIRA ticket.

    For paid support and managed or consulting services , contact Percona Sales.


    Last update: 2023-01-12
    Percona LLC and/or its affiliates, © 2023
    Made with Material for MkDocs

    Cookie consent

    We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better. Read more about Percona Cookie Policy.