PerfTop dashboards

You can view metrics derived from Performance Analyzer in a PerfTop dashboard. A PerfTop dashboard is a command line interface (CLI) for displaying the metrics. A PerfTop dashboard consists of three main elements: tables, line graphs, and bar graphs. Using JSON, you define a grid of rows and columns and then place elements within that grid, with each element spanning as many rows and columns as you specify.

The best way to get started with building custom dashboards is to duplicate and modify one of the existing JSON files in the dashboards directory.

An example dashboard is shown in the following image. PerfTop dashboard



Summary of elements

  • Tables show metrics per dimension. For example, if your metric is CPU_Utilization and your dimension ShardID, a PerfTop table shows a row for each shard on each node.
  • Bar graphs are aggregated for the cluster, unless you add nodeName to the dashboard. See the options for all elements.
  • Line graphs are aggregated for each node. Each line represents a node.

Position elements

PerfTop positions elements within a grid. For example, consider this 12 * 12 grid.

Dashboard grid

The upper-left of the grid represents row 0, column 0, so the starting positions for the three boxes are:

  • Orange: row 0, column 0
  • Purple: row 2, column 2
  • Green: row 1, column 6

These boxes span a number of rows and columns. In this case:

  • Orange: 2 rows, 4 columns
  • Purple: 1 row, 4 columns
  • Green: 3 rows, 2 columns

In JSON form, we have the following:

  1. {
  2. "gridOptions": {
  3. "rows": 12,
  4. "cols": 12
  5. },
  6. "graphs": {
  7. "tables": [{
  8. "options": {
  9. "gridPosition": {
  10. "row": 0,
  11. "col": 0,
  12. "rowSpan": 2,
  13. "colSpan": 4
  14. }
  15. }
  16. },
  17. {
  18. "options": {
  19. "gridPosition": {
  20. "row": 2,
  21. "col": 2,
  22. "rowSpan": 1,
  23. "colSpan": 4
  24. }
  25. }
  26. },
  27. {
  28. "options": {
  29. "gridPosition": {
  30. "row": 1,
  31. "col": 6,
  32. "rowSpan": 3,
  33. "colSpan": 2
  34. }
  35. }
  36. }
  37. ]
  38. }
  39. }

At this point, however, all the JSON does is define the size and position of three tables. To fill elements with data, you specify a query.

Add queries

Queries use the same elements as the REST API, just in JSON form:

  1. {
  2. "queryParams": {
  3. "metrics": "estimated,limitConfigured",
  4. "aggregates": "avg,avg",
  5. "dimensions": "type",
  6. "sortBy": "estimated"
  7. }
  8. }

For details on available metrics, see Metrics reference.

Add options

Options include labels, colors, and a refresh interval. Different elements types have different options.

Dashboards support the 16 ANSI colors: black, red, green, yellow, blue, magenta, cyan, and white. For the “bright” variants of these colors, use the numbers 8–15. If your terminal supports 256 colors, you can also use hex codes (e.g. #6D40ED).

All elements

OptionTypeDescription
labelString or integerThe text in the upper-left corner of the box.
labelColorString or integerThe color of the label.
refreshIntervalIntegerThe number of milliseconds between calls to the Performance Analyzer API for new data. Minimum value is 5000.
dimensionFiltersString arrayThe dimension value to display for the graph. For example, if you query for metric=Net_Throughput&agg=sum&dim=Direction and the possible dimension values are in and out, you can define dimensionFilters: [“in”] to only display the metric data for in dimension
nodeNameStringIf non-null, lets you restrict elements to individual nodes. You can specify the node name directly in the dashboard file, but the better approach is to use “nodeName”: “#nodeName” in the dashboard and include the —nodename <node_name> argument when starting PerfTop.

Tables

OptionTypeDescription
bgString or integerThe background color.
fgString or integerThe text color.
selectedFgString or integerThe text color for focused text.
selectedBgString or integerThe background color for focused text.
columnSpacingIntegerThe amount of space (measured in characters) between columns.
keysBooleanHas no impact at this time.

Bars

OptionTypeDescription
barWidthIntegerThe width of each bar (measured in characters) in the graph.
xOffsetIntegerThe amount of space (measured in characters) between the y-axis and the first bar in the graph.
maxHeightIntegerThe maximum height of each bar (measured in characters) in the graph.

Lines

OptionTypeDescription
showNthLabelIntegerWhich of the xAxis labels to show. For example, “showNthLabel”: 2 shows every other label.
showLegendBooleanWhether or not to display a legend for the line graph.
legend.widthIntegerThe width of the legend (measured in characters) in the graph.
xAxisString arrayArray of labels for the x-axis. For example, [“0:00”, “0:10”, “0:20”, “0:30”, “0:40”, “0:50”].
colorsString arrayArray of line colors to choose from. For example, [“magenta”, “cyan”]. If you don’t provide this value, PerfTop chooses random colors for each line.