Grafana Enterprise Logs Grafana Loki LogQL Template functions

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 and upper shortcut, e.g {{.request_method | lower }}.

Replace string

Note: In Loki 2.1 replace (as opposed to Replace) 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 string
• old string to replace
• new string to replace with
• n 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 replace
• new string to replace with
• src 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 "-"}}`