[翻譯]mongodb日誌分析工具mtools之mplotqueries

mtools是一組很是好用的mongodb日誌分析工具，裏面最複雜的命令是mplotqueries，上網查了一下，尚未人翻譯過。英文很差，費了好大的勁翻完，翻的很差，但沒有辦法，我英文水平就這麼多~

原文地址：https://github.com/rueckstiess/mtools/wiki/mplotqueries

-----------------------------------------------------------------------------------------------------------------------

mplotqueries

Thomas Rueckstiess edited this page on 9 Oct · 31 revisions

mplotqueries is a tool to visualize operations in MongoDB logfiles. It has several different plot types and can group information in various ways.

把MongoDB操做形象化的工具。它有多種類型的圖表支持多種方式對信息分組。

Usage（使用說明）

mplotqueries [-h] [--version] logfile [logfile ...]               [--group GROUP]               [--logscale]               [--type {nscanned/n,rsstate,connchurn,histogram,range,scatter,event} ]               [--overlay [ {add,list,reset} ]]               [additional plot type parameters]

mplotqueries can also be used with shell pipe syntax, for example:

能夠在命令行管道語法中使用，例如

mlogfilter logfile [parameters] | mplotqueries --type histogram

General Parameters（全局參數）

Help（幫助）

-h, --help 

shows the help text and exits.

顯示幫助信息並退出

Version（版本）

--version 

shows the version number and exits.

顯示版本信息並退出

Logarithmic Scale （對數模式）

--logscale 
 This option enables the logarithmic scale for plots where this makes sense. This is very useful if the plot contains outliers that squash all other data points to the bottom of the graph (see below comparison on the same data between log scale disabled and enabled). It can also be enabled with the l (lowercase L) shortcut once a plot is rendered. Switching scale on an already rendered plot may take a few seconds before the new scale is shown.

這個選項容許在圖表中使用對數模式。若是圖表中的數據分化嚴重，全部的點都被壓到圖的底部時，它很是有用（參見下面的比較，相同的數據在使用對數模式和不使用時的區別）。

它能夠在渲染圖表時用l （小l）來啓用。在已經渲染好的圖表中切換顯示模式，須要花比較長的時間才能顯示出來。

Custom Title（自定義標題）

--title 
 This option lets you overwrite the default title (the file name(s)) with a custom title. If the title contains spaces, the full title needs to be quoted in strings. The title of a plot is shown above the graph. A file read in from stdin does not use a title.

這個選項容許用戶設置一個標題來替代默認標題（文件名）。若是標題中有空格，整個標題須要被放在引號裏。標題在圖上顯示。從stdin中讀入的文件沒有標題。

Operation Start Time （操做開始時間）

--optime-start 
 Events are written to the log file when they finish, and by default, mplotqueries plots the operation on the x-axis at that point in time. Sometimes, it can be useful to see when operations started instead. For operations that have a duration (queries, updates, etc.) mplotqueries can subtract the duration and plot the operation when it started instead. Turn this feature on with the --optime-start flag.

事件是在完成後寫入log的，默認狀況下，mplotqueries 在x軸上對應的時間點上。有時想看進程的啓動時間時，它比較有用。對於操做的持續時間，mplotqueries 能夠減掉持續時間，在操做開始時繪製圖像。使用  --optime-start  標記開啓這個功能。

Output to File （輸出文件）

--output-file 
 With this option, the plot can be written to a file rather than opening the interactive view window. The format is auto-recognized from the filename extension, with many supported formats, e.g. .png, .pdf, ...

使用這個選項，能夠把圖像繪製到文件裏而不是使用交互式的窗口視圖。文件格式能夠根據擴展名來自動識別，支持的格式有.png, .pdf 等。

Groupings （分組）

Group By （分組）

--group GROUP 
 The group parameter specifies what the data should be grouped on. Grouping can have different meaning for the various plots below, but generally, groups are represented by color. A scatter plot would choose one color for each group. A histogram plot would also choose a color per group, but additionally stack the histogrammed groups on top of each other. Some plots don't support grouping at all. See the plot types below for information about their grouping behavior.

分組參數指定用哪一個數據來分組。分組在多種圖表中能夠有多種意義，可是一般，分組用不一樣顏色表示。一個散點圖能夠爲每個分組選擇一個顏色。一個柱狀圖也能夠爲每一個組分一個顏色，而不是把每一個組堆起來。有些圖徹底不支持分組。參見下面的 plot types  中的關於分組行爲的信息

The following values are possible for GROUP for most plots (some plots may not support all groups)

下面的值在大多數圖中容許分組（有些圖不支持任何分組）

• namespace (default for single file) ( 單文件時的默認選項 )

• filename (default for multiple files) ( 多文件時的默認選項 )

• operation (queries, inserts, updates, ...) （操做）

• thread （ 進程號 ）

• log2code (not supported by every plot type) （不支持圖表）

• pattern (query pattern, e.g. {foo: 1, bar: 1}, no sub-documents) （查詢表達式，不包含子文檔）

• custom grouping with regular expressions (see Python's regex syntax) （正則表達式格式的自定義分組）

Example （示例）

mplotqueries mongod.log --group operation

This command creates a scatter plot on duration (by default) and colors the operations (queries, inserts, updates, deletes, commands, getmores) in individual colors. 

這個命令使用持續時間數據建立一個散點圖，並組每一個操做定義一個單獨的顏色。

Example （示例）

mlogfilter mongod.log --operation update --namespace test.users |    mplotqueries --type histogram --group "_id: ObjectId\('([^']+)'\)"

This command combination creates a histogram plot on duration of all the update operations on the test.users collection and groups the updates based on the _idObjectId (extracted by the regular expression). If parentheses are present in the regular expression, then only the first matched group is being used as the group string (in this case, the 24 hex characters in the ObjectId). If parentheses are not present, the full regex match is being used as group string. Parentheses (and other reserved symbols) that need to be matched literally (like the parentheses inObjectId('...') above) need to be escaped with a \.

這個命令聯合建立一個圖表，使用全部 test.users 集合更新操做的持續時間並用_idObjectId （正則過濾到的） 分組。若是正則使用了圓括號，只有第一個匹配到的分組會被當成分組字符串（本例中是ObjectId中的24位哈希串）來使用。若是提取不到括號中的內容，會使用整個正則匹配到的數據來做分組串。括號（和其餘保留符號）須要被直接匹配（如括號中的  inObjectId('...')  ）的，須要用反斜線 （\）轉義。

If the number of groups is large, like in this example, it can be reduced with the --group-limit option below. 

若是分組數特別多，以下例，能夠用 --group-limit 選項限制它的數量。

Group Limits （分組限制）

--group-limit N 

This parameter will limit the number of groups to the top N, based on the number of matching lines per group (descending). The remaining groups are then grouped together in a single bucket called other. This option is useful if the number of groups is very large, as repetitions in color (there are only 14 distinct colors) could otherwise make it hard to distinguish all the groups for some plot types.

此參數限制只顯示前N個分組，基於每個分組的匹配行數。其他的分組會合併成一個塊取名爲other。當分組特別多的時候，這就特別有用了，若是重複的顏色（最多支持14種顏色）太多，在一些圖表中區分分組會比較困難。

Example （例如）

mplotqueries mongod.log --type range --group log2code --group-limit 10

This command creates a range plot, grouped on log2code, but only displays the 10 most frequently occurring log messages as separate groups. All others are plotted as one additional group others. 

這個命令會建立一個圖，用 log2code 分組，可是隻有前10個最頻繁的事件信息會被分開顯示。其餘的都合併在一個組裏。

Plot Types（圖像類別）

Scatter Plot（散點圖，默認的）

--type scatter (default) 
 A scatter plot prints a marker on a two-dimensional axis, where the x-axis represents date and time, and the y-axis represents a certain numeric value. The numeric value for the y-axis can be chosen with an additional parameter (--yaxis, see below). By default, scatter plots show the duration of operations (queries, updates, inserts, deletes, ...) on the y-axis.

散點圖會把點繪製在一個二維區域裏。x軸表明日期和時間，y軸表明某一個值。y軸上的數值能夠在附加參數（--yaxis，參見下方）中被添加。默認的，散點圖在y軸上顯示操做的持續時間。

Available Groupings （有效分組）

Scatter plots use colors and additionally different marker shapes (circles, squares, diamonds, ...) to display different groups. The supported groupings for scatter plots are:namespace, operation, thread, filename (for multiple files), and regular expressions.

散點圖使用顏色和不一樣的標記形狀（圓，正方，菱形）來顯示不一樣的分組。散點圖支持的分組有namespace, operation, thread, filename (for multiple files) 和正則表達式。

Additional Parameters （可選參數）

Y-Axis Value （y軸值）

--yaxis FIELD

This parameter determines what value should be considered for the location on the y-axis. By default, the y-axis plots duration. Other possibilities are nscanned, nupdated,ninserted, ntoreturn, nreturned, numYields, r (read lock), w (write lock).

此參數肯定y軸遵循的數據。默認狀況，y軸繪製操做的持續時間。其餘可用的有nscanned, nupdated,ninserted, ntoreturn, nreturned, numYields, r (讀鎖), w (寫鎖).

Example （例如）

mplotqueries mongod.log --type scatter --yaxis w

This command plots the time (x-axis) vs. the write lock values of all operations (y-axis). Only lines that have a write lock value present are considered for the plot. Note that the unit for read/write lock is in microseconds.

此命令在x軸上繪製時間。在y軸上繪製全部操做的寫入鎖花費的時間。每一條橫行表示一個抽取出來的特定的寫入鎖的值。注意讀寫鎖的單位是微秒。

 

Scan Ratio Plot （掃描比例圖）

--type nscanned/n 
 The scan ratio plot is a special type of scatter plot. Instead of plotting a single field as the standard scatter plot, it will calculate the ratio between the nscanned value and the nreturned value, and uses that result as the value for the y-axis. This plot is very useful to quickly find inefficient queries.

掃描比例圖是一種特殊的散點圖。替代只有一個列的散點圖，它會計算nscanned 和nreturned 之間的比率，並把它做爲y軸上參照的值。這個圖很是有用，用它能夠快速找出無效的查詢。

Example （例如）

mplotqueries mongod.log --type nscanned/n

Duration Line Plot （持續時間圖）

--type durline 
 The Duration Line plot shows operations that have a duration (like queries, updates, inserts, commands, etc). It draws a diagnonal line from when the operation started (touching the x-axis) to when the operation stopped. This plot is especially useful to see when operations started and what impact they had on other queries during that time. It has the nice side-effect that all operations that started at the same time lie on the same diagonal line. Duration Line plots also make good plots to overlay with others.

持續時間圖顯示操做的持續時間。它會在操做的開始時間和結束時間中間畫一條斜線。這個圖在查看操開始後在執行期間受到其餘哪些操做的影響時特別有用。它很好的顯示了反作用，全部在同一個時間開始的操做都顯示在同一條斜線上。

Example （例如）

  grep "oplog.rs" mongod.log | mplotqueries --type durline --overlay    mplotqueries mongod.log --group operation

This command plots long-running oplog.rs operations as duration lines, and overlays them with a scatter plot of all operations. 

此命令把全部時間長的oplog.rs操做繪成斜線，並在上面覆蓋全部操做的散點圖。

Histogram Plot （柱狀圖）

--type histogram
 Histogram plots don't consider a particular value in the log line (like for example scatter plots do), but rather bin the occurrence of log lines together in time buckets and present the result as a bar chart. The more occurrences of a certain log line (per group) in a given time frame, the higher the bar for that bucket. The size of a bucket is 60 seconds by default, but can be configured to another value (--bucketsize, see below). Unless one wants to know the total number of log lines per time bucket (which is not very useful information), this command should always be preceeded with a filter, for examplemlogfilter or grep.

柱狀圖不考慮日誌中的特定值（像散點圖那樣），而是把日誌中的時間加在一塊兒，把結果顯示成一個條塊。發生的事件越多，顯示的條塊也越長。默認狀況下一個條塊表示60秒，但能夠設置成其餘值（--bucketsize，參見下方）。除非只想知道一個單位時間內的總數（不是很是有用的信息），不然這個命令老是和過濾器一塊兒使用，如logfilter或grep。

Available Groupings （有效的分組）

Histogram plots use colors to display different groups. Each group gets its own bar, the bars are stacked on top of each other to also give an indication of the total number of matched lines per bucket. The supported groupings for histogram plots are: namespace,operation, thread, filename (for multiple files), log2code and regular expressions.

柱狀圖使用不一樣的顏色表示不一樣的分組。每個分組一個條塊，條塊互相疊加，顯示了每個塊匹配到的記錄數。柱塊圖支持的分組有namespace,operation, thread, filename (for multiple files), log2code and 正則表達式.

Additional Parameters （附加參數）

Bucket Size 

--bucketsize SIZE, -b SIZE (alias)

This parameter sets the bucket size for an individual bucket (bar). The unit is measured in seconds and the default value is 60 seconds. This needs to be adjusted if the total time span of a log file is rather large. More than 1000 buckets are slow to render, andmplotqueries will output a warning to consider increasing the bucket size.

此參數設置條塊的尺寸。單位是秒默認是60秒。若是log日誌文件很是大的話，有必要調整這個參數，若是條塊大於1000個，渲染會很是慢，mplotqueries 會輸出一個警告信息，提示條塊尺寸須要調整。

Example （示例）

mlogfilter mongod.log --operation insert |     mplotqueries --type histogram --bucketsize 3600

This command plots the inserts per hour (3600 seconds) as a histogram plot. By default, the grouping is on namespace. 

此命令繪製每小時的插入量柱狀圖。默認狀況下，按 namespace. 分組。

See this plot for another histogram plot example.

參見此圖中的其餘柱狀圖示例。

Connection Churn Plot （鏈接產生圖）

--type connchurn 
 A connection churn plot is a special plot that only considers lines about opening and closing connections. It will then create an opened (green bars) vs. closed (red bars) plot over time, and additionally show the number of currently open connections (black line, only for MongoDB log files >= 2.2).

鏈接產生圖是一個特殊的圖表它只關心鏈接打開和關閉。它會建立一個圖來顯示隨時間打開和關閉的鏈接數，並附加顯示當前打開的鏈接數。

Available Groupings （有效分組）

No groupings are supported by this type of plot.

此類圖不支持分組。

Additional Parameters （附加參數）

Bucket Size （塊大小）

--bucketsize SIZE, -b SIZE (alias)

As with histogram plots, this parameter sets the bucket size for an individual bucket (bar). The unit is measured in seconds and the default value is 60 seconds. This needs to be adjusted if the total time span of a log file is rather large. More than 1000 buckets are slow to render, and mplotqueries will output a warning to consider increasing the bucket size.

就像柱狀圖，此參數設置條塊的尺寸。單位是時間，默認值是60秒。當日志文件特別大的時候須要調整這個參數。超過1000個條塊渲染會很慢，mplotqueries會輸出建議增長條塊尺寸的警告。

Example （示例）

mplotqueries mongod.log --type connchurn --bucketsize 600

This command plots connection churn per 10 minutes (600 seconds) as a bi-directional histogram plot, as well as the total number of open connections at each time (black line). 

此命令用每10分鐘內的鏈接數據生成雙向柱狀圖，並顯示每一個時段內的鏈接數（黑線）。

Range Plot （區間圖）

--type range 

Range plots are good in displaying when certain events occurred and how long they lasted. For example, you can grep for a certain error message and use the range plot to see when these errors mostly occurred. For each group, a range plot shows one or several (if the --gap option is used) horizontal bars, that go from beginning to end of a certain event. If no --gap value is provided, the default is to not have any gaps at all, and the bar goes from the time of the first to the time of the last line of that group. If --gap is used, then the bar is interrupted whenever two consecutive log lines are further apart than the gap threshold.

區間圖擅長表現事件的發生和持續時間。例如，能夠把異常事件信息過濾出來而後用區間圖看它在什麼時候發生的最多。每個分組中，顯示一條或多條橫向條塊，表示一個事件從開始到結束。若是沒指定 --gap 值，默認狀況下是沒有空隙的，條塊從分組中的第一個時間一直到最後一個時間。若是使用了 --gap ，在兩個連續的日誌間隔時間大於指定的時間時，條塊中會顯示空隙 。

Available Groupings （可用分組）

Range plots use colors to display different groups. Each group gets its own horizontal bar(s). The supported groupings for range plots are: namespace, operation, thread,filename (for multiple files), log2code and regular expressions.

區間圖中有不一樣的顏色來區分分組。每一個分組有本身的條塊。區間圖支持的分組有 namespace, operation, thread,filename (多文件中使用), log2code 和正則表達式。

Example （示例）

mplotqueries primary.log seconary1.log secondary2.log --type range

This plot shows for multiple files when they start and finish. By default, the grouping for multiple files is on filename, and as there is no gap threshold given, the bars range from the first two the last log line per file. This is useful to find out if and where several log files have an overlap. 

此圖用多文件中的開始和結束時間繪製。默認狀況下多文件的分組是filename ，而且沒使用間隔區間，條塊中顯示的是每一個文件從開始真到結束的全部行。這在顯示多個日誌的重複區域時特別有有。

Additional Parameters （附加參數）

Gap Threshold （間隔空隙）

--gap LEN

If a gap threshold is provided, then the horizontal bars are interrupted when two consecutive events of the same group are further apart than LEN seconds.

若是指定了間隔空隙，在兩個連續事件相隔超過 LEN  秒時，條塊中會顯示空隙。

Example （示例）

mplotqueries mongod.log --type range --group operation --gap 600

This plot shows ranges of contiguous blocks of updates where the gap threshold is 600 seconds (only gaps between two operations that are larger than 10 minutes are displayed as separate bars). 

此圖顯示連續的更新塊，間隔時間爲600秒（只有兩個連續的操做間隔時間大於10分鐘時，才顯示分隔塊）。

Event Plot （事件圖）

--type event 

Event plots show the occurrence of certain events in a log file. They make sense mostly in combination with a preceeding filter, either mlogfilter or a grep. For each matching event, a vertical line will be plotted at the time the event occurred. If the number of events is very large, you may want to consider using a range plot instead.

事件圖顯示日誌中的事件發生。它一般和一個過濾器一塊兒使用，能夠是mlogfilter或grep。在每一個匹配到的事件的發生時間上畫一條豎線。若是事件的數量很是多，能夠考慮用區間圖來替代它。

Example（示例）

grep "getlasterror" mongod.log | mplotqueries --type event

This plot shows the occurrences of all "getlasterror" events in the log file. 

此圖顯示日誌中的全部 getlasterror 事件。

Available Groupings （有效分組）

Event plots use colors and to display different groups. The supported groupings for event plots are: namespace, operation, thread, filename (for multiple files), and regular expressions.

事件圖用不一樣的顏色來區分分組。事件圖支持的分組有namespace, operation, thread, filename (多文件), 和正則表達式.

Additional Parameters （附加參數）

No additional parameters are supported by this type of plot.

此圖不支持附加參數。

Replica Set State Plot （副本集圖）

--type rsstate 

Replica set state plots are specialized event plots, that only consider lines about replica set state changes in a log file. They will display all changes of all replica set members (not just the node itself) with colored vertical lines, indicating different states. The most common states are PRIMARY, SECONDARY, ARBITER, STARTUP2, DOWN and RECOVERING, but other state changes are also displayed if found. This plot type helps to quickly determine any state changes at a given time. It is also useful to overlay this plot with a different plot, for example a scatter plot.

副本集狀態圖是種特殊的事件圖，只給日誌中的副本集狀態改變畫線。它會顯示副本集中全部成員的全部狀態改變，並用不一樣顏色的豎線顯示不用的狀態。最通用的狀態有 are PRIMARY, SECONDARY, ARBITER, STARTUP2, DOWN 和 RECOVERING，可是若是找到其餘的狀態改變，也會顯示出來。此圖用於快速查看指定時間內的全部狀態變化。它和其餘圖覆蓋使用時也很是有用，例如和散點圖覆蓋使用。

Example （示例）

mplotqueries mongod.log --type rsstate

This plot shows the state changes of all replica set members found in the log file. 

此圖顯示日誌中能找到的成員的全部狀態變化。

Available Groupings （有效分組）

No groupings are supported by this type of plot.

此圖不支持分組。

Additional Parameters （附加參數）

No additional parameters are supported by this type of plot.

此圖不支持附加參數。

Overlays （組合）

The overlay mechanism allows you to overlay several plot types in one graphic. This is useful to see correlations, match information from different plot types and create graphs that show events from different angles.

組合機制容許把多個圖合併成一個圖。這在查看統計的時候頗有用，從多個圖中匹配信息並在多個角度顯示信息。

Each of the plot types can in theory be used as an overlay, however some of them make more sense then others.

理論上每種圖均可以用於組合，不管哪一個圖表顯得更加突出。

Overlays are created just as normal plots, except they are stored on disk and do not render immediately. The first call to mplotqueries that does not add another overlay then will load all existing overlays added previously and render them on top of each other, matching the time axis.

組合只能建立標準圖像，除非它們已經被儲存而且非直接渲染。第一次調用mplotqueries不會添加其餘圖像的組合，還須要加載全部已經存在的圖並一層層地渲染，用時間軸來匹配。

Overlays are stored globally and are persistent, independent of your current working directory. Therefore, if you no longer need to store added overlays, make sure that you remove them again or they will be added to your next call of mplotqueries.

組合對當前目錄來講是全局存儲的，而且穩定的，不依賴的。所以，所以若是再也不須要存儲組合圖，請確認它們已經被刪除了，不然它會在下次運行mplotqueries時被添加進去。

Plot types that are often used for overlays are: event, range, rsstate, and scatter.

經常使用於組合的圖有：事件圖，區域圖，副本集狀態圖，散點圖。

Creating Overlays （建立組合圖）

--overlay [add] 

To create an overlay, run mplotqueries as you would normally, with all the command line arguments. In addition, specify the --overlay add argument. As add is the default for overlays, it can be omitted.

建立一個組合圖，除正常使用 mplotqueries 命令和全部參數外，須要特別指定 --overlay add 參數。add 是組合的默認參數，能夠省略。 

Example （示例）

mplotqueries mongod.log --type scatter --overlay    Created overlay: 18124963

This will add an overlay plot. The plot is not shown but saved on disk instead, and rendered with the next call without --overlay.

此命令會添加一個組合圖。這個圖不會被顯示出來而是被存儲在磁盤上，而且在下次不帶 --overlay 參數時被渲染。

List Existing Overlays （已存在的組合列表）

--overlay list 

To see if overlays are currently existing, you can use this command. A list of existing overlay identifiers will be returned. Currently, the indentifiers are not all that useful by themselves, but the command will show you how many different overlays exist.

查看組合是否是已經存在，可使用這個命令。它會返回一個已經存在的組合的id列表。這時，這些標識並非所有被使用，這個命令只是顯示有多少不一樣的組合存在。

Remove Overlays （刪除組合）

--overlay reset 

To remove all overlays, you can use this command. It will delete all existing overlays, and the next (or current, if a log file is specified as well) call to mplotqueries will not show additional overlays anymore.

使用這個命令刪除全部的組合。它會刪除全部已經存在的組合，而後（或如今，若是日誌文件已經被指定好了）調用mplotqueries 命令就不會顯示添加過的組合了。