Freemarker Expressions

Freemarker expressions are supported in portal creation.

Freemarker Functions

`getTags`

getTags('metric', 'entity', 'tagKey'[, hours])

Returns a string collection.

Tag values for metric, entity, and tagKey. [, hours] is an optional parameter, which specifies the time interval (in hours) for searching unique tag values. The default interval is 24 hours.

<#assign cpus = getTags("nmon.cpu.idle%", "${entity}", "id") >
<#list cpus as id>
    [series]
        label = ${id}
        entity = ${entity}
        metric = nmon.cpu.busy%
        #type = avg
        #interval = 5 minute
        [tag]
            name = id
            value = ${id}
</#list>

tag

tag('entity', 'tagKey')

Returns a string.

Entity tag value.

tag('nurswgvml007', 'location')

`groupTag`

groupTag('entity', 'tagKey')

Returns a string collection.

Returns collection of tag values for tagKey of all entity groups to which the entity belongs to.

groupTag('nurswgvml007', 'cpu_busy_avg_15_min')

`getMetrics`

getMetrics('entity')

String collection.

Returns collected metrics for a particular entity.

<#assign metrics = getMetrics("${entity}") >
<#list metrics as metric>
    [series]
        label = ${metric}
        entity = ${entity}
        metric = ${metric}
        statistic = avg
        period = 10 minute
</#list

<#assign metrics = getMetrics("${entity}") >
<#list metrics as metric>
<#if metric?index_of("cpu") gte 0>
  [widget]
      type = chart
      timespan = 1 hour
    [series]
        label = ${metric}
        entity = ${entity}
        metric = ${metric}
        statistic = avg
        period = 5 minute
</#if>
</#list>

`isMetric`

isMetric('metric')

Boolean.

Returns true if a metric exists.

<#if isMetric("nmon.processes.blocked") >
    [series]
        label = blocked
        entity = ${entity}
        metric = nmon.processes.blocked
</#if>

`isMetricCollected`

`isMetricCollected('metric', 'entity')`

Boolean.

Returns true if there is some data for metric and entity inserted in the last 24 hours.

<#if isMetricCollected("nmon.processes.blocked", "${entity}") >
    [series]
        label = blocked
        entity = ${entity}
        metric = nmon.processes.blocked
</#if>

`getProperty`

getProperty('entity', 'property_type', 'tag_name_')

Returns a string collection.

Retrieves a collection of property objects for a specified entity, property type, and tag name.

`getSeriesProperties`

getSeriesProperties("{entity}", "{property_type}")

Returns property objects for a specified entity and property type.

Retrieves a collection of property objects for a specified entity and property type. If no entity is specified, then the schema retrieves a collection of property objects for all entities with the specified property type.

<#assign ebs_volume_tags = getSeriesProperties(volume, "aws_ec2.attachmentset") >
<#list ebs_volume_tags as volume_tags>
  <#if volume_tags.entity == volume>
[series]
    label = ${volume}
    label = ${volume_tags.key.device}
    entity = ${volume}
    metric = aws_ebs.volumequeuelength.maximum
  </#if>
</#list>

`getTagMaps`

getTagMaps('metric', 'entity'[, hours])

Returns collection of maps(string, string).

Retrieves a collection of unique tag maps for metric and entity. [, hours] is an optional parameter, which specifies the time interval (in hours) for searching unique tag values. The default interval is 24 hours.

<#assign procMaps = getTagMaps("nmon.process.%cpu", "${entity}") >
<#list procMaps as procMap>
    [series]
        label = ${procMap['command']}
        entity = ${entity}
        metric = nmon.process.%cpu
        [tag]
            name = pid
            value = ${procMap['pid']}
        [tag]
            name = command
            value = ${procMap['command']}
</#list>

`atsd_last`

atsd_last("entity", "metric", "tag1=v1,tag2=v2")

Retrieves the last value (a number) for a specified entity, metric, and series tags. The value is searched for a timespan of 2 hours.

If the series has multiple tags, the last argument must include all tags.

atsd_last("nurswgvml007", "disk_size", "mount_point=/,file_system=/dev/mapper/vg_nurswgvml007-lv_root")

If the series has no tags, the last argument can be omitted or set to empty string.

atsd_last("nurswgvml007", "cpu_busy")

The returned value is formatted according to server locale. For example 13325 is formatted as 13,325. To remove formatting append ?c at the end of the function or assigned variable.

<#assign total = atsd_last("nurswgvml007", "disk_size", "mount_point=/,file_system=/dev/mapper/vg_nurswgvml007-lv_root") >
  total-value = ${total?c}

`memberOf`

memberOf('entity', 'group1', …, 'groupN')

Boolean.

Returns true if an entity belongs to any of the specified entity groups.

<#if memberOf("nurswgvml007", "aix-servers") >
    [series]
        entity = ${entity}
        metric = lpar.used_units
</#if>

`memberOfAll`

memberOfAll('entity', 'group1', …, 'groupN')

Boolean.

Returns true if an entity belongs to all of the entity groups.

<#if isMetricCollected("nmon.processes.blocked", "${entity}") >
    [series]
        label = blocked
        entity = ${entity}
        metric = nmon.processes.blocked
</#if>

`lastInsertTime` & `lastInsertDate`

lastInsertTime('entity'[, ‘metric’])

lastInsertDate('entity'[, ‘metric’])

Double.

Returns the last insert time for the entity or entity/metric combination in milliseconds (Time) or ISO format (Date). Metric is an optional parameter.

<#assign ebs_volume_tags = getSeriesProperties(volume, "aws_ec2.attachmentset") >
   <#list ebs_volume_tags as volume_tags>
      <#if volume_tags.entity == volume>
    [series]
        label = ${volume}
        label = ${volume_tags.key.device}
        entity = ${volume}
        metric = aws_ebs.volumequeuelength.maximum
      </#if>
   </#list

lastInsertDate('nurswgvml007', 'cpu_busy')

`getEntitiesForGroup`

getEntitiesForGroup('group')

getEntitiesForGroup('group', 'hours')

Returns a string collection.

Finds all entities in a particular entity group. This can be useful when building portals that compare entities from the same entity group. The method returns group member that have inserted data over the last N hours. If hours are not specified or are non-positive, all group members are returned.

<#assign servers = getEntitiesForGroup("VMware Hosts") >
<#list servers as server>
    [series]
        entity = ${server}
        metric = cpu.used
</#list>
<#list servers as server>
    [series]
        entity = ${server}
        metric = cpu.used
</#list>

`getEntitiesForTags`

getEntitiesForTags(expression)

Returns a string collection.

Finds entities by expression, based on tags.

<#assign servers = getEntitiesForTags("", "(app == '${app}' OR '${app}' == '' AND app != '') AND
                                            (dc == '${dc}' OR '${dc}' == '' AND dc != '')") >
<#list servers as server>
    [series]
        label = ${server}
        entity = ${server}
        metric = physical_cpu_units_used
</#list>
<#assign servers = getEntitiesForTags("", "application = '${entity}'") >
<#list servers as server>
    [series]
        entity = ${server}
        metric = physical_cpu_units_used
</#list>

In the first example, we are searching for entities with two tags. The required value can be specified in the browser:

http://atsd.com/portal/1.xhtml?app=> value1&dc=> value2

All entities, for which the app tag is => value1 and dc tag is => value2, are loaded into the portal.

In the second example, we are searching for entities with a specific application tag. The required value can be specified in the browser:

http://atsd.com/portal/1.xhtml?application=> value

All entities, for which the application tag is > value, are loaded into the portal.

Freemarker expressions can be used to customize the portal by searching for entity tags rather that specific entities. This gives extensive possibilities to create flexible portals.

The Freemarker search can be for any combination of tags. For example: > application > data center > function. Only entities that have all three specified tags are loaded into the portal.

In the response, the freemarker [series] are substituted with the matching entities, creating [series] for each of them.

Example output of a `freemarker` [series]

[configuration]
title = CPU Used Portal
height-units = 1
width-units = 1

[group]

[widget]
type = chart
title = CPU Used
timespan = 1 hour
max-range = 100

[series]
label = host0987
entity = host0987
metric = cpu_used

[series]
label = host1040
entity = host1040
metric = cpu_used

[series]
label = host1299
entity = host1299
metric = cpu_used

[series]
label = host1786
entity = host1786
metric = cpu_used

Advanced functions and aggregations can be added to the Freemarker portals to enhance the resulting data prior to loading it into the portal. Below are two examples:

The `freemarker` [series] is given an alias, that can then be used to sum the loaded data

<#assign servers = getEntitiesForGroup("Linux") >
 <#list servers as server>
    [series]
        entity = ${server}
        metric = cpu_busy
        alias = cpuused_${server}
 </#list>

The `freemarker` [series] data can be aggregated by ATSD prior to loading into the portal

[series]
    label = P99 CPU Used
    value = 0 <#list servers as server> + percentile(99,'cpuused_${server}','1 day')</#list>

Freemarker Expressions Summary Table

Name	Returns	Description
`atsd_last('entity', 'metric', 'tag1=v1,tag2=v2')`	Double	Last value for time series or `null`.
`groupTag('entity', 'tagKey')`	string collection	Collection of tag values for `tagKey` of all entity groups an entity belongs to.
`tag('entity', 'tagKey')`	string	Entity tag value.
`memberOf('entity', 'group1', ..., 'groupN')`	boolean	Returns `true` if an entity belongs to any of specified entity groups.
`memberOfAll('entity', 'group1', ..., 'groupN')`	boolean	Returns `true` if an entity belongs to all of the entity groups.
`list('value' [, delimiter])`	string collection	Splits a string by a delimiter. Default delimiter is comma.
`getTags('metric', 'entity', 'tagKey'[, hours])`	string collection	Tag values for metric, entity, and `tagKey`. [, hours] is an optional parameter, which specifies the time interval (in hours) for searching unique tag values. Default interval is 24 hours.
`getEntitiesForTags(expression)`	string collection	Finds entities by expression.
`getEntitiesForGroup(group)`	string collection	Finds all entities in a particular entity group. This is useful when building portals that compare entities from the same entity group.
`getEntitiesForGroup(groupName, hours)`	string collection	Finds all entities in a particular entity group. This is useful when building portals that compare entities from the same entity group. The method returns group members that have inserted data over the last `N` hours. If hours are not specified or non-positive, all group members are returned.
`getMetrics('entity')`	string collection	Retrieves all collected metrics for a particular entity.
`isMetric('metric')`	boolean	Returns `true` if a metric exists.
`isMetricCollected('metric', 'entity')`	boolean	Returns `true` if there is some data for metric and entity inserted in last 24 hours.
`hasMetric('entity', 'metric' [,hours])`	boolean	Executes query for Last Insert Cache table. Returns `true` if the entity collects specified the metric, regardless of tags. If the optional hours argument is specified, only rows inserted for the last `N` hours are evaluated.
`getTagMaps('metric', 'entity'[, hours])`	collection of maps(string, string)	Collection of unique tag maps for metric and entity. `[, hours]` is an optional parameter, which specifies the time interval (in hours) for searching unique tag values. The default interval is 24 hours.
`getProperty('entity', 'property_type', 'tagKey')`	string collection	Retrieves a collection of property objects for specified entity, property type, and tag.
`getSeriesProperties("{entity}", "{property_type}")`	property objects for specified entity and property type	Retrieves a collection of property objects for a specified entity and property type. If no entity is specified, then a collection of property objects for all entities with the specified property type is retrieved.
`atsd_values(entity, metric, tags, type, interval, shift, duration)`	Aggregator object	See tables below.
`lastInsertTime('entity'[, 'metric'])`	Double	Returns last insert time for the entity or entity/metric combination in milliseconds. Metric is an optional parameter.
`lastInsertDate('entity'[, 'metric'])`	Double	Returns last insert date for the entity or entity/metric combination in ISO format. Metric is an optional parameter.

`atsd_values` parameters

Name	Description
`entity`	Entity
`metric`	Metric
`tags`	Tags
`type`	Aggregation Type
`interval`	Aggregation Interval
`shift`	Interval: `endTime = now – shift`
`duration`	Selection interval: `startTime = endTime – duration`

`atsd_values` parameters

Name	Returns
`min()`	Double
`max()`	Double
`sumOf()`	Double
`average()`	Double
`countOf()`	Integer
`asList()`	Double collection

# Freemarker Expressions

# Freemarker Functions

# getTags

# tag

# groupTag

# getMetrics

# isMetric

# isMetricCollected

# getProperty

# getSeriesProperties

# getTagMaps

# atsd_last

# memberOf

# memberOfAll

# lastInsertTime & lastInsertDate

# getEntitiesForGroup

# getEntitiesForTags

# Example output of a freemarker [series]

# The freemarker [series] is given an alias, that can then be used to sum the loaded data

# The freemarker [series] data can be aggregated by ATSD prior to loading into the portal

# Freemarker Expressions Summary Table

# atsd_values parameters

# atsd_values parameters

Freemarker Expressions

Freemarker Functions

`getTags`

tag

`groupTag`

`getMetrics`

`isMetric`

`isMetricCollected`

`getProperty`

`getSeriesProperties`

`getTagMaps`

`atsd_last`

`memberOf`

`memberOfAll`

`lastInsertTime` & `lastInsertDate`

`getEntitiesForGroup`

`getEntitiesForTags`

Example output of a `freemarker` [series]

The `freemarker` [series] is given an alias, that can then be used to sum the loaded data

The `freemarker` [series] data can be aggregated by ATSD prior to loading into the portal

Freemarker Expressions Summary Table

`atsd_values` parameters

`atsd_values` parameters