Axibase

Selecting Series

Database Schema

Widget configuration syntax provides a way to load and display data for time series stored in a database. Series values change over time and their history is visualized with different types of graphs.

[widget]
  type = chart
  # Widget settings
  [series]
    # Series 1 settings
  [series]
    # Series 2 settings

Each series is identified by a composite key which consists of an entity, metric, and optional key-value pairs called tags.

  [series]
    metric = cpu_busy
    entity = nurswgvml007
  [series]
    metric = df.bytes.percentused
    entity = nurswgvml006
    [tags]
      mount = /
      fstype = ext4

Entity is a physical or logical object being monitored such as nurswgvml007 (computer name).
Metric represents the name of a measurable numeric attribute such as cpu_busy or temperature.
Tags are optional, and they provide additional level of detail for measurements, for example the disk’s mount point for the df.bytes.percentused metric.

An entity may be measured with a variety of metrics, just as the same metric could be collected for multiple entities.

Exploring Series

The available series can be reviewed in the database on the Metrics > metric > [Series] page or on the Entities > entity > Metrics > [Series] page.

Alternatively, if the entity is known, the metrics and series can be explored via a portal containing drop-down selectors.

Selecting Specific Series

To display values for a specific series, the [series] section should specify its exact composite key which can be looked up in the database:

  # Series without Tags
  metric = cpu_busy
  entity = nurswgvml007

metric-entity

  # Series with Tags
  metric = df.bytes.percentused
  entity = nurswgvml006
  [tags]
    mount = /
    fstype = ext4

metric-tags

Selecting Multiple Series with Tags

By default, the database will return all series matching the request, including series with extra tags not enumerated in the request.

This enables loading series using only a subset of tags that are still sufficient to uniquely identify the series:

  # Series with Tags
  metric = df.bytes.percentused
  entity = nurswgvml006
  [tags]
    mount = /

The above configuration will match all series with mount=/ tag, including series that may have other tags.

To disable partial tag match, use the 'exact-match = true | false' setting:

  # Series with Tags
  metric = df.bytes.percentused
  entity = nurswgvml006
  exact-match = true
  [tags]
    mount = /

When partial match is disabled, the database will return series with exactly the same combination of tags as specified in the request.

The partial match, while making the configuration compact, can produce undetermined results if the partial key matches multiple series where only one series is expected:

  # Series with Tags
  metric = df.bytes.percentused
  entity = nurswgvml006
  [tags]
    fstype = ext4

In the above example, the response will contain 3 different series with the same file system type ext4 but with different mount points: /, /boot/, /media/datadrive.

The resulting series is merged from 3 underlying different series and provides a meaningless result in this particular case.

To control how multiple matched series are processed, use the 'multiple-series = true | false' setting.

  # Display all series with tag fstype=ext4 without merging
  multiple-series = true
  [series]
    [tags]
      fstype = ext4

The 'multiple-series' setting can be used to display all series without specifying any tags in widget configuration at all:

  # Display all series without merging
  multiple-series = true
  [series]

The default value of the 'multiple-series' setting is set to true in one of the following cases:

Multiple entities are specified, for example entity = nur1, nur2
Multiple tag values are specified, for example [tags] mount = /, /tmp
Entity name contains wildcard, for example entity = nur*
Tag value contains wildcard, for example [tags] mount = /t*
entity-expression, entity-group, or tag-expression is present

multiple-series

# Select series using tag value wildcards. multiple-series is TRUE
  [tags]
    fstype = ext4  
    mount = *media*
 
# Select series with any value for the specified tag. multiple-series is TRUE
  [tags]
    fstype = ext4  
    mount = *
 
# Select series with any value for the specified tag. multiple-series is FALSE
  [tags]
    fstype = ext4  
 
# Select series with tag values from the specified list. multiple-series is TRUE
  [tags]
    fstype = cifs, autofs
 
# Select series with tag values matching specified wildcard patterns: multiple-series is TRUE
  [tags]
    fstype = cifs, auto*
 
# Select series with tags matching an expression: multiple-series is TRUE
  tag-expression = tags.mount NOT LIKE '/m*'

select-tags

Merging Series

Merging multiple series into one series could be a useful feature in situations where the underlying series describe the same object despite having different keys. Oftentimes, such series are recorded sequentially and therefore do not overlap.

Examples:

/media/datadrive file system re-mounted on a larger disk and the mount point remains the same.
Containers with different identifiers launched on schedule to perform a daily task.
Measurements recorded during a set of scientific experiments are tagged with experiment Id and input parameters.

multiple-series-off

Selecting Series for Multiple Entities

The widget syntax provides a number of options to select series for multiple entities and the same metric:

  # Select specific entity by name
  entity = nurswgvml006
 
  # Select multiple entities by name using ? and * wildcards
  entity = nurswgvml*
 
  # Select all entities
  entity = *
 
  # Select an array of entities by name
  entities = nurswgvml006, nurswgvml007
 
  # Select an array of entities by name or pattern
  entities = nurswgvml111, nurswgvml00*
 
  # Select entities matching an expression referencing name, label, entity tags, properties
  entity-expression = tags.app = 'ATSD'
 
  # Select entities belonging to the specified entity group
  entity-group = nur-collectors

Refer to Data API for additional information about these settings.

  # Retrieve series for entities starting with nurswgvml00
  [series]
   entity = nurswgvml00*
    [tags]
      mount = /
      fstype = ext4

select-entity

Retrieving Series from Database

As an alternative to specifying series settings manually and using wildcards, the widget syntax provides getSeries() and getTags() methods to retrieve the list of existing series from the database.

getTags():

  var tags = getTags('df.bytes.percentused', 'mount', 'nurswgvml006')
 
  for tagValue in tags
    [series]
      [tags]
        mount = @{tagValue}
  endfor

getSeries():

  var seriesList = getSeries('df.bytes.percentused', 'nurswgvml006')
 
  for sobj in seriesList
    [series]
      [tags]
      for tagName in Object.keys(sobj.tags)
        "@{tagName}" = @{sobj.tags[tagName]}
      endfor
  endfor

Controlling Displayed Series

The series-limit = int setting enables limiting the number of possible series returned by the database for wildcard queries. Since the limit is applied to an unsorted list of matched series, the results may vary between requests, which makes the setting useful when exploring the dataset to prevent the widgets from loading too many series into browser memory.

  entity = *
  series-limit = 10
  [series]    
    [tags]
      fstype = ext4

For a more flexible visibility control on the client, use the display and enabled settings.

  entity = *
  display = value == top(1) || value == bottom(1)
  [series]    
    [tags]
      fstype = ext4

series-display
In addition, the limit = int setting enables reducing the number of samples displayed for each series. It makes queries execute faster when loading data for high-frequency series from the server, in particular during design and validation stages.