Special Template Entity Querying Language - absalon-james/grafanizer GitHub Wiki

Templates will query an entity to determine if the entity is a fit for the dashboard. The entity will have a tree of information where the root node is the entity, children of the entity are checks, and children of the checks are metrics.

An example of how to get a cpu usage average metric:

entity().check(label:startswith(cpu)).metric(name:full(usage_average))

The above query will match entities that have a check starting with cpu that have metric named usage average.

The query must contain three parts separated by dots.

  • Entity section
  • Check section
  • Metric section

Each section will have a comma delimited list of attribute expressions. Attribute expressions express the attribute to match, how to match it, and the value to match with.

# A single attribute expression that
# matches the label attribute
# using the startswith function
# with a value of cpu
label:startswith(cpu)

# Multiple attribute expressions delimited by a comma
# Matches the label attributes starting with cpu
# AND id attributes containing the character sequence 123
label:startswith(cpu), id:contains(123)

Attributes can be matched with the following functions:

  • startswith - Attribute must start with a value
  • endswith - Attribute must end with a value
  • contains - Attribute must contain the value
  • full - Attribute must equal the value
  • regex - Attribute must match the regular expression that is the value

Entity Section

The attributes available to entities:

  • id - Usually in the form of enxxxxxxxx
  • label - Usually a human readable thing

The entity section is the only section permitted to not have an attribute expression.

# Example entity sections
# Match all entities. We do not care about the id or label
entity()

# Match all entities with labels starting with foo
entity(label:startswith(foo))

# Match all entities with labels starting with foo and ending with bar
entity(label:startswith(foo), label:endswith(bar))
#Alternatively
entity(label:startswith(foo)).entity(label:endswith(bar))

If an entity does not meet the attribute expression requirements, the query fails and returns nothing.

The check section

The check section must have at least one attribute expression. The attributes available to checks:

  • id - Usually in the form chyyyyyyyy
  • label - Usually a human readable value

If no checks are found satisfying the attribute expressions, the query fails and returns nothing.

# Example check sections
# Match the first check with a label starting with foo
check(label:startswith(foo))

# Match the first check with a label starting with foo and containing bar
check(label:startswith(foo), label:contains(bar))
#Alternatively
check(label:startswith(foo)).check(label:contains(bar))

Metric section

Attributes available to metrics:

  • name - Usually human readable.

If no matching metrics are found, the query dies and returns nothing.

# Example metric sections
# Match the first metric with a name starting with foo
metric(name:startswith(foo))

# Match the first metric with a name starting with foo and containing bar
metric(label:startswith(foo), metric:contains(bar))
#Alternatively
metric(label:startswith(foo)).metric(label:contains(bar))

Putting it all together

A successful query will return a list of (entity, check, metric) tuples. This information can then be iterated over to generate parts of dashboards.

# I want to entities with checks containing cpu in the label and max_cpu_usage in the metric name
entity().check(label:contains(cpu)).metric(name:contains(max_cpu_usage))
# I want the same as above but only for entities with bob in the entity label
entity(label:contains(bob)).check(label:contains(cpu)).metric(name:contains(max_cpu_usage))