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 "-"}}`