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.
Default interval is 24 hours.

tag
tag('entity', 'tagKey')

Returns a string.

Entity tag value.

groupTag
groupTag('entity', 'tagKey')

Returns a string collection.

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

getMetrics
getMetrics('entity')

String collection

Returns collected metrics for a particular entity.

isMetric
isMetric('metric')

Boolean

Returns true if a metric exists.

isMetricCollected
isMetricCollected('metric', 'entity')

Boolean

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

getProperty
getProperty('entity', 'property_type', 'tagKey')

Returns a string collection.

Retrieve a collection of property objects for the specified entity, property type, and tag.

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

Returns property objects for a specified entity and property type.

Retrieve a collection of property objects for 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.

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

Returns collection of maps(string, string).

Retrieve 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.
Default interval is 24 hours.

atsd_last
gatsd_last('entity', 'metric', 'tag1=v1,tag2=v2')

Returns double.

Retrieves the last value for time series or null.

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

Boolean

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

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

Boolean

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

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.

getEntitiesForGroup:
getEntitiesForGroup('group')
getEntitiesForGroup('group', 'hours')

Returns a string collection.

Find all entities in a particular entity group, which is 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 is not specified or non-positive, all group members are returned.

getEntitiesForTags:
getEntitiesForTags(expression)

Returns a string collection.

Find entities by expression, based on tags.

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

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

All entities where the app tag is equal to value1 and dc tag is equal to value2 will be loaded into the portal.

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

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

All entities where the application tag is equal to value will be loaded into the portal.

userInGroup:
/*
Returns true if the user belongs to the specified user group.
*/
userInGroup(String userGroupname)
userAllowEntity:
/*
  Returns true if the user has read permissions for the specified entity.
*/
userAllowEntity(String entityName)
userHasRole:
/*
Returns true if the user has the specified role: USER, EDITOR, etc.
*/
userHasRole(String roleName)
userAllowEntityGroup:
/*
Returns true if the user has READ permissions to the specified entity group.
*/
userAllowEntityGroup(String entityGroupName)

A single line of freemarker code can be used to easily customize the results of the portal by searching for entity tags rather than specific entities giving extensive possibilities to create flexible portals.

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

In the response, 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
time-span = 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 freemarker portals to enhance the resulting data prior to loading it into the portal. Below are two examples.

The freemarker [series] are given an alias, that can then be used to sum the loaded data as in the example below:
The freemarker [series] data can be aggregated by ATSD prior to loading into the portal:

Freemarker Expressions Summary Table

NameReturnsDescription
atsd_last('entity', 'metric', 'tag1=v1,tag2=v2')DoubleLast value for time series or null.
groupTag('entity', 'tagKey')string collectionCollection of tag values for tagKey of all entity groups an entity belongs to
tag('entity', 'tagKey')stringEntity tag value.
memberOf('entity', 'group1', ..., 'groupN')booleanReturns true if an entity belongs to any specified of the entity groups.
memberOfAll('entity', 'group1', ..., 'groupN')booleanReturns true if an entity belongs to all of the entity groups.
list('value' [, delimiter])string collectionSplits a string by a delimeter. Default delimiter is comma character.
getTags('metric', 'entity', 'tagKey'[, hours])string collectionTag 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 collectionFind entities by expression.
getEntitiesForGroup("group")string collectionFind all entities in a particular entity group. Useful when building portals that compare entities from the same entity group.
getEntitiesForGroup(groupName, hours)string collectionFind all entities in a particular entity group. 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 is not specified or non-positive, all group members are returned.
getMetrics('entity')string collectionRetrieve all collected metrics for a particular entity.
isMetric('metric')booleanReturns true if a metric exists.
isMetricCollected('metric', 'entity')booleanReturns true if there is some data for the metric and entity inserted in the last 24 hours.
hasMetric('entity', 'metric' [,hours])booleanExecutes query for Last Insert Cache table and returns true if the entity collects the specified 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.
Default interval is 24 hours.
getProperty('entity', 'property_type', 'tagKey')string collectionRetrieve a collection of property objects for specified entity, property type, and tag.
getSeriesProperties("{entity}", "{property_type}")property objects for specified entity and property typeRetrieve a collection of property objects for 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 objectSee tables below.
lastInsertTime('entity'[, ‘metric’])DoubleReturns last insert time for the entity or entity/metric combination in milliseconds. Metric is an optional parameter.
lastInsertDate('entity'[, ‘metric’])DoubleReturns last insert date for the entity or entity/metric combination in ISO format. Metric is an optional parameter.

atsd_values parameters

NameDescription
entityEntity
metricMetric
tagsTags
typeAggregation Type
intervalAggregation Interval
shiftInterval: endTime = now – shift
durationSelection interval: startTime = endTime – duration

atsd_values parameters

NameReturns
min()Double
max()Double
sumOf()Double
average()Double
countOf()Integer
asList()Double collection