percona/percona-toolkit
1
0
Fork 0
mirror of https://github.com/percona/percona-toolkit.git synced 2025-09-14 15:33:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Doc updates for 3.0.0 RC

Browse Source
This commit is contained in:
azhebel
2017-02-06 18:43:58 +03:00
parent 33e2928e7d
commit 003dfacaa8
4 changed files with 428 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/index.rst
View File

@@ -3,19 +3,23 @@
Percona Toolkit Documentation Percona Toolkit Documentation
=============================== ===============================
Percona Toolkit is a collection of advanced command-line tools used by Percona Toolkit is a collection of advanced command-line tools
Percona (`http://www.percona.com/ <http://www.percona.com/>`_) support staff to perform a variety of used by `Percona <http://www.percona.com/>`_) support staff
MySQL and system tasks that are too difficult or complex to perform manually. 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 These tools are ideal alternatives to private or "one-off" scripts,
they are professionally developed, formally tested, and fully documented. because they are professionally developed, formally tested,
They are also fully self-contained, so installation is quick and easy and and fully documented.
no libraries are installed. 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 Percona Toolkit was derived from Maatkit and Aspersa,
toolkits for MySQL server administration. It is developed and supported by two of the best-known toolkits for MySQL server administration.
Percona. For more information and other free, open-source software It is developed and supported by Percona.
developed by Percona, visit `http://www.percona.com/software/ <http://www.percona.com/software/>`_. For more information and other free, open-source software
developed by Percona, visit http://www.percona.com/software/.
Getting Percona Toolkit Getting Percona Toolkit
======================= =======================

174
docs/installation.rst
View File

@@ -2,12 +2,20 @@
Installation Installation
======================================= =======================================
Visit `http://www.percona.com/software/percona-toolkit/ <http://www.percona.com/software/percona-toolkit/>`_ to download the You can either download Percona Toolkit manually from the website
latest release of Percona Toolkit. Or, get the latest release from the or use the official Percona software repositories for your system.
command line:
.. 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 wget percona.com/get/percona-toolkit.tar.gz
@@ -17,9 +25,163 @@ command line:
You can also get individual tools from the latest release: You can also get individual tools from the latest release:
.. code-block:: perl .. code-block:: bash
wget percona.com/get/TOOL 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 <http://wiki.debian.org/AptPreferences>`_.
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]

90
docs/pt-mongodb-query-digest.rst Normal file
View File

@@ -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<password>``.
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

155
docs/pt-mongodb-summary.rst Normal file
View File

@@ -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<password>``.
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.