diff --git a/docs/index.rst b/docs/index.rst index ac211b1f..864f7fa6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,19 +3,23 @@ Percona Toolkit Documentation =============================== -Percona Toolkit is a collection of advanced command-line tools used by -Percona (`http://www.percona.com/ `_) support staff to perform a variety of -MySQL and system tasks that are too difficult or complex to perform manually. +Percona Toolkit is a collection of advanced command-line tools +used by `Percona `_) support staff +to perform a variety of MySQL, MongoDB, and system tasks +that are too difficult or complex to perform manually. -These tools are ideal alternatives to private or "one-off" scripts because -they are professionally developed, formally tested, and fully documented. -They are also fully self-contained, so installation is quick and easy and -no libraries are installed. +These tools are ideal alternatives to private or "one-off" scripts, +because they are professionally developed, formally tested, +and fully documented. +They are also fully self-contained, +so installation is quick and easy, +and no libraries are installed. -Percona Toolkit is derived from Maatkit and Aspersa, two of the best-known -toolkits for MySQL server administration. It is developed and supported by -Percona. For more information and other free, open-source software -developed by Percona, visit `http://www.percona.com/software/ `_. +Percona Toolkit was derived from Maatkit and Aspersa, +two of the best-known toolkits for MySQL server administration. +It is developed and supported by Percona. +For more information and other free, open-source software +developed by Percona, visit http://www.percona.com/software/. Getting Percona Toolkit ======================= diff --git a/docs/installation.rst b/docs/installation.rst index a77143c2..36e52cad 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -2,12 +2,20 @@ Installation ======================================= -Visit `http://www.percona.com/software/percona-toolkit/ `_ to download the -latest release of Percona Toolkit. Or, get the latest release from the -command line: +You can either download Percona Toolkit manually from the website +or use the official Percona software repositories for your system. +.. contents:: + :local: -.. code-block:: perl +Downloading Percona Toolkit +=========================== + +Visit http://www.percona.com/software/percona-toolkit/ +to download the latest release of Percona Toolkit. +Alternatively, you can get the latest release using the command line: + +.. code-block:: bash wget percona.com/get/percona-toolkit.tar.gz @@ -17,9 +25,163 @@ command line: You can also get individual tools from the latest release: -.. code-block:: perl +.. code-block:: bash wget percona.com/get/TOOL -Replace \ ``TOOL``\ with the name of any tool. +Replace ``TOOL`` with the name of any tool, for example:: + + wget percona.com/get/pt-summary + +Installing Percona Toolkit on Debian or Ubuntu +============================================== + +1. Fetch the repository packages from Percona web: + + .. code-block:: bash + + wget https://repo.percona.com/apt/percona-release_0.1-4.$(lsb_release -sc)_all.deb + +#. Install the downloaded package with :program:`dpkg` + by running the following command as root or with :program:`sudo`: + + .. code-block:: bash + + sudo dpkg -i percona-release_0.1-4.$(lsb_release -sc)_all.deb + +#. Once you install this package, the Percona repositories should be added. + You can check the repository configuration + in the :file:`/etc/apt/sources.list.d/percona-release.list` file. + +#. Percona Toolkit 3.0.0 is in beta, + so packages are in the testing repository. + To enable it, add ``testing`` at the end + of the Percona repository definition. + For more information, see :ref:`apt-testing-repo`. + +#. Update the local cache: + + .. code-block:: bash + + sudo apt-get update + +#. Install the ``percona-toolkit`` package: + + .. code-block:: bash + + sudo apt-get install percona-toolkit + +.. _apt-testing-repo: + +Testing and Experimental Repositories +------------------------------------- + +Percona offers pre-release builds from the testing repo, +and early-stage development builds from the experimental repo. +To enable them, add either ``testing`` or ``experimental`` at the end +of the Percona repository definition in your repository file +(by default, :file:`/etc/apt/sources.list.d/percona-release.list`). + +For example, if you are running Debian 8 ("jessie") +and want to install the latest testing builds, +the definitions should look like this:: + + deb http://repo.percona.com/apt jessie main testing + deb-src http://repo.percona.com/apt jessie main testing + +If you are running Ubuntu 14.04 LTS (Trusty Tahr) +and want to install the latest experimental builds, +the definitions should look like this:: + + deb http://repo.percona.com/apt trusty main experimental + deb-src http://repo.percona.com/apt trusty main experimental + +Pinning the Packages +-------------------- + +If you want to pin your packages to avoid upgrades, +create a new file :file:`/etc/apt/preferences.d/00percona.pref` +and add the following lines to it:: + + Package: * + Pin: release o=Percona Development Team + Pin-Priority: 1001 + +For more information about pinning, +refer to the official `Debian Wiki `_. + +Installing Percona Toolkit on Red Hat or CentOS +=============================================== + +1. Install the Percona repository package: + + .. code-block:: bash + + $ sudo yum install http://www.percona.com/downloads/percona-release/redhat/0.1-4/percona-release-0.1-4.noarch.rpm + + You should see the following if successful: :: + + Installed: + percona-release.noarch 0:0.1-4 + + Complete! + +#. Percona Toolkit 3.0.0 is in beta, + so packages are in the testing repository. + To enable it, set ``enabled=1`` for the following entries + in the Percona repository configuration file + (:file:`/etc/yum.repos.d/percona-release.repo`):: + + [percona-testing-$basearch] + [percona-testing-noarch] + + For more information, see :ref:`yum-testing-repo`. + +#. Check that the packages are available: + + .. code-block:: bash + + $ yum list | grep percona-toolkit + + You should see output similar to the following: + + .. code-block:: text + + percona-toolkit.noarch 3.0.0-rc percona-release-noarch + +#. Install the |PSMDB| packages: + + .. code-block:: bash + + $ sudo yum install percona-toolkit + +.. _yum-testing-repo: + +Testing and Experimental Repositories +------------------------------------- + +Percona offers pre-release builds from the testing repo, +and early-stage development builds from the experimental repo. +You can enable either one in the Percona repository configuration file +:file:`/etc/yum.repos.d/percona-release.repo`. +There are three sections in this file, +for configuring corresponding repositories: + +* stable release +* testing +* experimental + +The latter two repositories are disabled by default. + +If you want to install the latest testing builds, +set ``enabled=1`` for the following entries: :: + + [percona-testing-$basearch] + [percona-testing-noarch] + +If you want to install the latest experimental builds, +set ``enabled=1`` for the following entries: :: + + [percona-experimental-$basearch] + [percona-experimental-noarch] diff --git a/docs/pt-mongodb-query-digest.rst b/docs/pt-mongodb-query-digest.rst new file mode 100644 index 00000000..52310d74 --- /dev/null +++ b/docs/pt-mongodb-query-digest.rst @@ -0,0 +1,90 @@ +.. _pt-mongodb-query-digest: + +======================= +pt-mongodb-query-digest +======================= + +``pt-mongodb-query-digest`` reports query usage statistics +by aggregating queries from MongoDB query profiler. + +Usage +===== + +.. code-block:: bash + + pt-mongodb-query-digest [OPTIONS] + +It runs the following command:: + + db.getSiblingDB("samples").system.profile.find({"op":{"$nin":["getmore", "delete"]}}); + +Then the results are grouped by fingerprint and namespace +(database.collection). +The fingerprint is calculated as a sorted list of keys in the document +with a maximum depth level of 10. +By default, the results are sorted by ascending query count. + +Options +------- + +-?, --help Show help and exit + +-a, --authenticationDatabase Specifies the database + used to establish credentials + and privileges with a MongoDB server. + By default, the ``admin`` database is used. + +-c, --no-version-check Don't check for updates + +-d, --database Specifies which database to profile + +-l, --log-level Specifies the log level: + ``panic``, ``fatal``, ``error``, ``warn``, + ``info``, ``debug error`` + +-n, --limit Limits the number of queries to show + +-o, --order-by Specifies the sorting order using fields: + ``count``, ``ratio``, ``query-time``, + ``docs-scanned``, ``docs-returned``. + + Adding a hypen (``-``) in front of a field + denotes reverse order. + + For example: ``--order-by="count,-ratio"`` + +-p, --password Specifies the password to use + when connecting to a server + with authentication enabled. + + Do not add a space between the option + and its value: ``-p``. + + If you specify the option without any value, + you will be prompted for the password. + +-u, --user Specifies the user name for connecting + to a server with authentication enabled. + +-v, --version Show version and exit + +Output Example +============== + +.. code-block:: none + + # Query 2: 0.00 QPS, ID 1a6443c2db9661f3aad8edb6b877e45d + # Ratio 1.00 (docs scanned/returned) + # Time range: 2017-01-11 12:58:26.519 -0300 ART to 2017-01-11 12:58:26.686 -0300 ART + # Attribute pct total min max avg 95% stddev median + # ================== === ======== ======== ======== ======== ======== ======= ======== + # Count (docs) 36 + # Exec Time ms 0 0 0 0 0 0 0 0 + # Docs Scanned 0 148.00 0.00 74.00 4.11 74.00 16.95 0.00 + # Docs Returned 2 148.00 0.00 74.00 4.11 74.00 16.95 0.00 + # Bytes recv 0 2.11M 215.00 1.05M 58.48K 1.05M 240.22K 215.00 + # String: + # Namespaces samples.col1 + # Fingerprint $gte,$lt,$meta,$sortKey,filter,find,projection,shardVersion,sort,user_id,user_id + + diff --git a/docs/pt-mongodb-summary.rst b/docs/pt-mongodb-summary.rst new file mode 100644 index 00000000..0dc3b340 --- /dev/null +++ b/docs/pt-mongodb-summary.rst @@ -0,0 +1,155 @@ +.. pt-mongodb-summary: + +================== +pt-mongodb-summary +================== + +``pt-mongodb-summary`` collects information about a MongoDB cluster. +It collects information from several sources +to provide an overview of the cluster. + +Usage +===== + +.. code-block:: bash + + pt-mongodb-summary [OPTIONS] [HOST[:PORT]] + +By default, if you run ``pt-mongodb-summary`` without any parameters, +it will try to connect to ``localhost`` on port ``27017``. +The program collects information about MongoDB instances +by running administration commands and formatting the output. + +Options +------- + +-a, --auth-db Specifies the database used to establish credentials + and privileges with a MongoDB server. + By default, the ``admin`` database is used. + +-p, --password Specifies the password to use when connecting + to a server with authentication enabled. + + Do not add a space between the option and its value: + ``-p``. + + If you specify the option without any value, + ``pt-mongodb-summary`` will ask for password interactively. + +-u, --user Specifies the user name for connecting + to a server with authentication enabled. + +Output Example +============== + +.. code-block:: none + + # Instances #################################################################################### + ID Host Type ReplSet + 0 localhost:17001 PRIMARY r1 + 1 localhost:17002 SECONDARY r1 + 2 localhost:17003 SECONDARY r1 + 0 localhost:18001 PRIMARY r2 + 1 localhost:18002 SECONDARY r2 + 2 localhost:18003 SECONDARY r2 + + # This host + # Mongo Executable ############################################################################# + Path to executable | /home/karl/tmp/MongoDB32Labs/3.0/bin/mongos + # Report On 0 ######################################## + User | karl + PID Owner | mongos + Time | 2016-10-30 00:18:49 -0300 ART + Hostname | karl-HP-ENVY + Version | 3.0.11 + Built On | Linux x86_64 + Started | 2016-10-30 00:18:49 -0300 ART + Datadir | /data/db + Process Type | mongos + + # Running Ops ################################################################################## + + Type Min Max Avg + Insert 0 0 0/5s + Query 0 0 0/5s + Update 0 0 0/5s + Delete 0 0 0/5s + GetMore 0 0 0/5s + Command 0 22 16/5s + + # Security ##################################################################################### + Users 0 + Roles 0 + Auth disabled + SSL disabled + + + # Oplog ######################################################################################## + Oplog Size 18660 Mb + Oplog Used 55 Mb + Oplog Length 0.91 hours + Last Election 2016-10-30 00:18:44 -0300 ART + + + # Cluster wide ################################################################################# + Databases: 3 + Collections: 17 + Sharded Collections: 1 + Unsharded Collections: 16 + Sharded Data Size: 68 GB + Unsharded Data Size: 0 KB + # Balancer (per day) + Success: 6 + Failed: 0 + Splits: 0 + Drops: 0 + +Sections +======== + +Output is separated into the following sections: + +* **Instances** + + This section lists all hosts connected to the current MongoDB instance. + For this, ``pt-mongodb-summary`` runs the ``listShards`` command + and then the ``replSetGetStatus`` on every instance + to collect its ID, type, and replica set. + +* **This host** + + This section provides an overview of the current MongoDB instance + and the underlying OS. + For this, ``pt-mongodb-summary`` groups information + collected from ``hostInfo``, ``getCmdLineOpts``, ``serverStatus``, + and the OS process (by process ID). + +* **Running Ops** + + This section provides minimum, maximum, and average operation counters + for ``insert``, ``query``, ``update``, ``delete``, ``getMore``, + and ``command`` operations. + For this, ``pt-mongodb-summary`` runs the ``serverStatus`` command + 5 times at regular intervals (every second). + +* **Security** + + This section provides information about the security settings. + For this, ``pt-mongodb-summary``, parses ``getCmdLineOpts`` output + and queries the ``admin.system.users`` + and ``admin.system.roles`` collections. + +* **Oplog** + + This section contains details about the MongoDB operations log (oplog). + For this, ``pt-mongodb-summary`` collects statistics + from the oplog on every host in the cluster, + and returns those with the smallest ``TimeDiffHours`` value. + +* **Cluster wide** + + This section provides information about the number of sharded and + unsharded databases, collections, and their size. + For this, ``pt-mongodb-summary`` runs the ``listDatabases`` command + and then runs ``collStats`` for every collection in every database. +