This is the documentation for Cloudera Manager 5.1.x.
Documentation for other versions is available at Cloudera Documentation.

Charting Time-Series Data

Cloudera Manager enables you to enter a query for a time series, chart the time-series data, group (facet) individual time series if your query produced multiple time series, and save the results as a dashboard.

The following sections have more details on the terminology used, how to query for time-series data, displaying chart details, editing charts, and modifying chart properties.

Terminology

Entity
A Cloudera Manager component that has metrics associated with it, such as a service, role, or host.
Metric
A property that can be measured to quantify the state of an entity or activity, such as the number of open file descriptors or CPU utilization percentage. For a list of all the metrics supported by Cloudera Manager, see Cloudera Manager Metrics.
Time series
A list of (time, value) pairs that is associated with some (entity, metric) pair such as, (datanode-1, fd_open), (hostname, cpu_percent). In more complex cases, the time series can represent operations on other time series. For example, (datanode-1 , cpu_user + cpu_system).
Facet
A display grouping of a set of time series. By default, when a query returns multiple time series, they are displayed in individual charts. Facets allow you to display the time series in separate charts, in a single chart, or grouped by various attributes of the set of time series.

Building a Chart with Time-Series Data

  1. Select Charts > Chart Builder.
  2. Display time series in one of the following ways:
    • Select a recently used statement
      1. Click the to the right of the Build Chart button to display a list of recently run statements and select a statement. The statement text displays in the text box and the chart(s) that display that time series will display.
    • Select from the list of metrics Dashboards
      1. Click the List of Metrics link to display a list of metrics organized in categories.
      2. Type a name or description of the metric in the Filter by Metric... text box. As you type, only the list of categories containing metrics that match the letters will display.
      3. Click a category to display the metrics related to that category. Some metrics will appear in multiple categories as they may apply to more than one entity or activity (for example, the Alerts metric applies to a large number of categories).
      4. Click the metric that you want to chart. The corresponding tsquery statement will appear in the text box and the chart(s) that display that time series will display.
    • Type a new statement
      1. Press Spacebar in the text box. tsquery statement components display in a drop-down list. These suggestions are part of typeahead, which helps build valid queries. Scroll to the desired component and click Enter. Continue choosing query components by pressing Spacebar and Enter until the tsquery statement is complete.

For example, the query SELECT jvm_heap_used_mb where clusterId = 1 could return a set of charts like the following:

Configuring Time-Series Query Results

Required Role:

A time-series query returns one or more time series or scalar values. By default a maximum of 250 time series will be returned.

To change this value:
  1. Select Administration > Settings.
  2. In the Advanced category, set the Maximum Number Of Time-Series Streams Returned Per Time-Series Query or the Maximum Number of Time-Series Streams Returned Per Heatmap property.
  3. Click Save Changes.

Using Context-Sensitive Variables in Charts

When editing charts from a service, role or host status or charts page, or when adding a chart to a status page, a set of context-sensitive variables (each beginning with '$') will be displayed below the query box on the Chart Builder page. For example, you might see variables similar to those in the query below:

Notice the $HOSTNAME portion of the query string. $HOSTNAME is a variable that will be resolved to a specific value based on the page before the query is actually issued. In this case, $HOSTNAME will become tcdn5-1.ent.cloudera.com.

The chart below shows an example of the output of a similar query.

Context-sensitive variables are useful since they allow portable queries to be written. For example the query above may be on the host status page or any role status page to display the appropriate host's swap rate. Variables cannot be used in queries that are part of user-defined dashboards since those dashboards have no service, role or host context.

Chart Properties

By default, the time-series data retrieved by the tsquery is displayed on its own chart, using a Line style chart, a default size, and a default minimum and maximum for the Y-axis. You can change the chart type, facet the data, set the chart scale and size, and set X- and Y-axis ranges.

Changing the Chart Type

To change the chart type, click one of the chart types on the left:
  • Line - Displays the points in the time series as continuous line.
  • Stack Area - Displays the points in the time series as continuous line and the area under the line filled in.
  • Bar - Displays each the value of the metric averaged over a second as a bar.
  • Scatter - Displays the points in the time series as dots.
  • Heatmap - Displays a metric thermometer and grid of colored squares. The thermometer displays buckets that represent a range of metric values and a color coding for the bucket. Each square represents an entity and the color of the square represents the value of a metric within a range. The following heatmap shows the last value of the resident memory for the NodeManager, ImpalaD, DataNode, and RegionServer roles.

  • Histogram - Displays the time series values as a set of bars where each bar represents a range of metric values and the height of the bar represents the number of entities whose value falls within the range. The following histogram shows the number of roles in each range of the last value of the resident memory.

  • Table - Displays the time series values as a table with each row containing the data for a single time value.
  Note: Heatmaps and histograms render charts for a single point as opposed to time series charts that render a series of points. For queries that return time series, Cloudera Manager will generate the heatmap or histogram based on the last recorded point in the series, and will issue the warning: "Query returned more than one value per stream. Only the last value was used." To eliminate this warning, use a scalar returning function to choose a point. For example, use select last(cpu_percent) to use the last point or select max(cpu_percent) to use the maximum value (in the selected time range).

Grouping (Faceting) Time Series

A time-series plot for a service, role, or host may actually be a composite of multiple individual time series. For example, the query SELECT jvm_heap_used_mb where clusterId = 1 returns time-series data for the JVM heap used. Each time series has hostname, role type, metric, and entity name attributes. By default each attribute is displayed all on a single chart.

Using facets, you can combine time series based their attributes. To change the organization of the chart data, click one of the facets on the left hand side of the screen. The number in parentheses indicates how many charts will be displayed for that facet. As shown in the image below if the serviceName facet is selected for the JVM heap query, the time series is grouped into four charts, one chart each for each service name. The charts for service types with multiple roles contain multiple lines (for example, HBase, HDFS) while services that have only one role (for example, ZooKeeper) contain just a single line. When a chart contains multiple lines, each entity is identified by a different color line.

Changing Scale

You can set the scale of the chart to linear, logarithmic, and power.

Changing Dimensions

You can change the size of your charts by moving the Dimension slider. It moves in 50-pixel increments. If you have multiple charts, depending on the dimensions you specify and the size of your browser window, your charts may appear in rows of multiple charts.

The following chart shows the same query as the previous chart, but with All Combined selected (which shows all time series in a single chart) and with the Dimension slider used to expand the chart.

Changing Axes

You can change the Y-axis range using the Y Range minimum and maximum fields.

The X-axis is based on clock time, and by default shows the last hour of data. You can use the Time Range Selector or a duration link () to set the time range. (See Time Line for details).

Displaying Chart Details

When you move your mouse over a chart, its background turns gray, indicating that you can act upon it.

  • Moving the mouse to a data point on a line, stack area, or bar chart shows the details about that data point in a pop-up tooltip.
  • Click a line, stack area, scatter, or bar chart to expand it into a full-page view with a legend for the individual charted entities as well more fine-grained axes divisions.
    • If there are multiple entities in the chart, you can
      • Check and uncheck the legend item to hide or show the time series for the entities on the chart.

      • If there are service, role, or host instances in the chart, click the View link to display the instance's Status page.
    • Click the Close button to return to the regular chart view.
  • Heatmap - Clicking a square in a heatmap displays a line chart of the time series for that entity.
  • Histogram -
    • Clicking a histogram opens a pop-up containing the query that generated the chart, an expanded view of the chart, a list of entity names and links to the entities whose metrics are represented by the histogram bars, and the value of the metric for each entity. For example, clicking the following histogram

      displays the following:

    • Clicking a bar in the expanded histogram displays a line chart of the time series from which the histogram was generated:

      Clicking the < Back link at the top left of the line chart returns to the expanded histogram.

Editing a Chart

You can edit a chart from the Custom dashboard and save it back into the same or another existing dashboard, or to a new custom dashboard. Editing a chart only affects the copy of the chart in the current dashboard – if you have copied the chart into other dashboards, those charts are not affected by your edits.

  1. Move the cursor over the chart, and click the blue down arrow icon at the top right.
  2. Click Open in Chart Builder. This opens the Chart Builder page with the chart you selected already displayed.
  3. Edit the chart's select statement and click Build Chart.

Saving a Chart

Required Role:

After editing a chart you can save it to a new or existing custom dashboard or to a system dashboard.

  1. Modify the chart's properties and click Build Chart.
  2. Click Save to open the Save Chart dialog, and select one of the following:
    1. Save chart to current dashboard: <name of current dashboard>
    2. Add chart to an existing custom or system dashboard
    3. Add chart to a new custom dashboard
  3. Click Save Chart.
  4. Click View Dashboard to go to the dashboard where the chart has been saved.

Saving a chart only affects the copy of the chart in the dashboard where you save it – if you have previously copied the chart into other dashboards, those charts are not affected by your edits.

Users with Read-Only, Limited Operator, or Operator user roles can edit charts and view the results, but cannot save them to a dashboard.

Obtaining Time-Series Data Using the API

Time-series data can be obtained using the Cloudera Manager API. For details about using a tsquery statement to obtain time-series data, see the /timeseries API documentation at http://cmServerHost:7180/static/apidocs/path__timeseries.html. To see the API call that returns the time-series data for an existing chart, click the blue down-arrow at the upper-right corner of the chart and click Export JSON. A new web browser window opens, displaying the time-series data in JSON format. The query string of the URL for that window displays the API call that retrieved the time-series data.