percona/percona-toolkit
1
0
Fork 0
mirror of https://github.com/percona/percona-toolkit.git synced 2025-09-14 07:06:28 +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 is a collection of advanced command-line tools used by
Percona (`http://www.percona.com/ <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 <http://www.percona.com/>`_) 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/ <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
=======================

174
docs/installation.rst
View File

@@ -2,12 +2,20 @@
Installation
=======================================
Visit `http://www.percona.com/software/percona-toolkit/ <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 <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.