Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
Template functions
The text template format used in | line_format
and | label_format
support the usage of functions.
All labels are added as variables in the template engine. They can be referenced using they label name prefixed by a .
(e.g .label_name
). For example the following template will output the value of the path label:
{{ .path }}
Additionally you can also access the log line using the __line__
function.
You can take advantage of pipeline to join together multiple functions. In a chained pipeline, the result of each command is passed as the last argument of the following command.
Example:
{{ .path | replace " " "_" | trunc 5 | upper }}
line
This function returns the current log line.
Signature:
line() string
Examples:
"{{ __line__ | lower }}"
`{{ __line__ }}`
ToLower and ToUpper
This function converts the entire string to lowercase or uppercase.
Signatures:
ToLower(string) string
ToUpper(string) string
Examples:
"{{.request_method | ToLower}}"
"{{.request_method | ToUpper}}"
`{{ToUpper "This is a string" | ToLower}}`
Note: In Grafana Loki 2.1 you can also use respectively
lower
andupper
shortcut, e.g{{.request_method | lower }}
.
Replace string
Note: In Loki 2.1
replace
(as opposed toReplace
) is available with a different signature but easier to chain within pipeline.
Use this function to perform a simple string replacement.
Signature:
Replace(s, old, new string, n int) string
It takes four arguments:
s
source stringold
string to replacenew
string to replace withn
the maximun amount of replacement (-1 for all)
Example:
`{{ Replace "This is a string" " " "-" -1 }}`
The results in This-is-a-string
.
Trim, TrimLeft, TrimRight, and TrimSpace
Note: In Loki 2.1 trim, trimAll, trimSuffix and trimPrefix have been added with a different signature for better pipeline chaining.
Trim
returns a slice of the string s with all leading and
trailing Unicode code points contained in cutset removed.
Signature: Trim(value, cutset string) string
TrimLeft
and TrimRight
are the same as Trim
except that it trims only leading and trailing characters respectively.
`{{ Trim .query ",. " }}`
`{{ TrimLeft .uri ":" }}`
`{{ TrimRight .path "/" }}`
TrimSpace
TrimSpace returns string s with all leading
and trailing white space removed, as defined by Unicode.
Signature: TrimSpace(value string) string
{{ TrimSpace .latency }}
TrimPrefix
and TrimSuffix
will trim respectively the prefix or suffix supplied.
Signature:
TrimPrefix(value string, prefix string) string
TrimSuffix(value string, suffix string) string
{{ TrimPrefix .path "/" }}
regexReplaceAll and regexReplaceAllLiteral
regexReplaceAll
returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement. Inside string replacement, $ signs are interpreted as in Expand, so for instance $1 represents the text of the first sub-match. See the golang Regexp.replaceAll documentation for more examples.
`{{ regexReplaceAll "(a*)bc" .some_label "${1}a" }}`
regexReplaceAllLiteral
function returns a copy of the input string and replaces matches of the Regexp with the replacement string replacement. The replacement string is substituted directly, without using Expand.
`{{ regexReplaceAllLiteral "(ts=)" .timestamp "timestamp=" }}`
You can combine multiple functions using pipe. For example, to strip out spaces and make the request method in capital, you would write the following template: {{ .request_method | TrimSpace | ToUpper }}
.
lower
Added in Loki 2.1
Use this function to convert to lower case.
Signature:
lower(string) string
Examples:
"{{ .request_method | lower }}"
`{{ lower "HELLO"}}`
The last example will return hello
.
upper
Added in Loki 2.1
Use this function to convert to upper case.
Signature:
upper(string) string
Examples:
"{{ .request_method | upper }}"
`{{ upper "hello"}}`
This results in HELLO
.
title
Note: Added in Loki 2.1.
Convert to title case.
Signature:
title(string) string
Examples:
"{{.request_method | title}}"
`{{ title "hello world"}}`
The last example will return Hello World
.
trunc
Note: Added in Loki 2.1.
Truncate a string and add no suffix.
Signature:
trunc(count int,value string) string
Examples:
"{{ .path | trunc 2 }}"
`{{ trunc 5 "hello world"}}` // output: hello
`{{ trunc -5 "hello world"}}` // output: world
substr
Note: Added in Loki 2.1.
Get a substring from a string.
Signature:
substr(start int,end int,value string) string
If start is < 0, this calls value[:end]. If start is >= 0 and end < 0 or end bigger than s length, this calls value[start:] Otherwise, this calls value[start, end].
Examples:
"{{ .path | substr 2 5 }}"
`{{ substr 0 5 "hello world"}}` // output: hello
`{{ substr 6 11 "hello world"}}` // output: world
replace
Note: Added in Loki 2.1.
This function performs simple string replacement.
Signature: replace(old string, new string, src string) string
It takes three arguments:
old
string to replacenew
string to replace withsrc
source string
Examples:
{{ .cluster | replace "-cluster" "" }}
{{ replace "hello" "world" "hello world" }}
The last example will return world world
.
trim
Note: Added in Loki 2.1.
The trim function removes space from either side of a string.
Signature: trim(string) string
Examples:
{{ .ip | trim }}
{{ trim " hello " }} // output: hello
trimAll
Note: Added in Loki 2.1.
Use this function to remove given characters from the front or back of a string.
Signature: trimAll(chars string,src string) string
Examples:
{{ .path | trimAll "/" }}
{{ trimAll "$" "$5.00" }} // output: 5.00
trimSuffix
Note: Added in Loki 2.1.
Use this function to trim just the suffix from a string.
Signature: trimSuffix(suffix string, src string) string
Examples:
{{ .path | trimSuffix "/" }}
{{ trimSuffix "-" "hello-" }} // output: hello
trimPrefix
Note: Added in Loki 2.1.
Use this function to trim just the prefix from a string.
Signature: trimPrefix(suffix string, src string) string
Examples:
{{ .path | trimPrefix "/" }}
{{ trimPrefix "-" "-hello" }} // output: hello
indent
Note: Added in Loki 2.1.
The indent function indents every line in a given string to the specified indent width. This is useful when aligning multi-line strings.
Signature: indent(spaces int,src string) string
{{ indent 4 .query }}
This indents each line contained in the .query
by four (4) spaces.
nindent
Note: Added in Loki 2.1.
The nindent function is the same as the indent function, but prepends a new line to the beginning of the string.
Signature: nindent(spaces int,src string) string
{{ nindent 4 .query }}
This will indent every line of text by 4 space characters and add a new line to the beginning.
repeat
Note: Added in Loki 2.1.
Use this function to repeat a string multiple times.
Signature: repeat(c int,value string) string
{{ repeat 3 "hello" }} // output: hellohellohello
contains
Note: Added in Loki 2.1.
Use this function to test to see if one string is contained inside of another.
Signature: contains(s string, src string) bool
Examples:
{{ if .err contains "ErrTimeout" }} timeout {{end}}
{{ if contains "he" "hello" }} yes {{end}}
hasPrefix and hasSuffix
Note: Added in Loki 2.1.
The hasPrefix
and hasSuffix
functions test whether a string has a given prefix or suffix.
Signatures:
hasPrefix(prefix string, src string) bool
hasSuffix(suffix string, src string) bool
Examples:
{{ if .err hasSuffix "Timeout" }} timeout {{end}}
{{ if hasPrefix "he" "hello" }} yes {{end}}
add
Note: Added in Loki 2.3.
Sum numbers. Supports multiple numbers
Signature: func(i ...interface{}) int64
{{ add 3 2 5 }} // output: 10
sub
Note: Added in Loki 2.3.
Subtract numbers.
Signature: func(a, b interface{}) int64
{{ sub 5 2 }} // output: 3
mul
Note: Added in Loki 2.3.
Mulitply numbers. Supports multiple numbers.
Signature: func(a interface{}, v ...interface{}) int64
{{ mul 5 2 3}} // output: 30
div
Note: Added in Loki 2.3.
Integer divide numbers.
Signature: func(a, b interface{}) int64
{{ div 10 2}} // output: 5
addf
Note: Added in Loki 2.3.
Sum numbers. Supports multiple numbers.
Signature: func(i ...interface{}) float64
{{ addf 3.5 2 5 }} // output: 10.5
subf
Note: Added in Loki 2.3.
Subtract numbers. Supports multiple numbers.
Signature: func(a interface{}, v ...interface{}) float64
{{ subf 5.5 2 1.5 }} // output: 2
mulf
Note: Added in Loki 2.3.
Mulitply numbers. Supports multiple numbers
Signature: func(a interface{}, v ...interface{}) float64
{{ mulf 5.5 2 2.5 }} // output: 27.5
divf
Note: Added in Loki 2.3.
Divide numbers. Supports multiple numbers.
Signature: func(a interface{}, v ...interface{}) float64
{{ divf 10 2 4}} // output: 1.25
mod
Note: Added in Loki 2.3.
Modulo wit mod.
Signature: func(a, b interface{}) int64
{{ mod 10 3}} // output: 1
max
Note: Added in Loki 2.3.
Return the largest of a series of integers:
Signature: max(a interface{}, i ...interface{}) int64
{{ max 1 2 3 }} //output 3
min
Note: Added in Loki 2.3.
Return the smallest of a series of integers.
Signature: min(a interface{}, i ...interface{}) int64
{{ max 1 2 3 }} //output 1
maxf
Note: Added in Loki 2.3.
Return the largest of a series of floats:
Signature: maxf(a interface{}, i ...interface{}) float64
{{ maxf 1 2.5 3 }} //output 3
minf
Note: Added in Loki 2.3.
Return the smallest of a series of floats.
Signature: minf(a interface{}, i ...interface{}) float64
{{ minf 1 2.5 3 }} //output 1.5
ceil
Note: Added in Loki 2.3.
Returns the greatest float value greater than or equal to input value
Signature: ceil(a interface{}) float64
{{ ceil 123.001 }} //output 124.0
floor
Note: Added in Loki 2.3.
Returns the greatest float value less than or equal to input value
Signature: floor(a interface{}) float64
{{ floor 123.9999 }} //output 123.0
round
Note: Added in Loki 2.3.
Returns a float value with the remainder rounded to the given number of digits after the decimal point.
Signature: round(a interface{}, p int, rOpt ...float64) float64
{{ round 123.555555 3 }} //output 123.556
We can also provide a roundOn
number as third parameter
{{ round 123.88571428571 5 .2 }} //output 123.88572
With default roundOn
of .5
the above value would be 123.88571
int
Note: Added in Loki 2.3.
Convert value to an int.
Signature: toInt(v interface{}) int
{{ "3" | int }} //output 3
float64
Note: Added in Loki 2.3.
Convert to a float64.
Signature: toFloat64(v interface{}) float64
{{ "3.5" | float64 }} //output 3.5
fromJson
Note: Added in Loki 2.3.
fromJson decodes a JSON document into a structure. If the input cannot be decoded as JSON the function will return an empty string.
fromJson "{\"foo\": 55}"
Example of a query to print a newline per queries stored as a json array in the log line:
{job="loki/querier"} |= "finish in prometheus" | logfmt | line_format "{{ range $q := fromJson .queries }} {{ $q.query }} {{ end }}"
now
now
returns the current local time.
{{ now }}
toDate
toDate
parses a formatted string and returns the time value it represents.
{{ toDate "2006-01-02" "2021-11-02" }}
date
date
returns a textual representation of the time value formatted according to the provided golang datetime layout.
{ date "2006-01-02" now }}
unixEpoch
unixEpoch
returns the number of seconds elapsed since January 1, 1970 UTC.
{ unixEpoch now }}
Example of a query to filter Loki querier jobs which create time is 1 day before:
{job="loki/querier"} | label_format nowEpoch=`{{(unixEpoch now)}}`,createDateEpoch=`{{unixEpoch (toDate "2006-01-02" .createDate)}}` | label_format dateTimeDiff="{{sub .nowEpoch .createDateEpoch}}" | dateTimeDiff > 86400
default
default
checks whether the string(src
) is set, and returns default(d
) if not set.
Signature: default(d string, src string) string
Examples:
{{ default "-" "" }} // output: -
{{ default "-" "foo" }} // output: foo
Example of a query to print a -
if the http_request_headers_x_forwarded_for
label is empty:
{job="access_log"} | json | line_format `{{.http_request_headers_x_forwarded_for | default "-"}}`