Caution
Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.
This is documentation for the next version of Agent. For the latest stable release, go to the latest version.
format
The format
function produces a string by formatting a number of other values according
to a specification string. It is similar to the printf
function in C, and
other similar functions in other programming languages.
format(spec, values...)
Examples
> format("Hello, %s!", "Ander")
"Hello, Ander!"
> format("There are %d lights", 4)
"There are 4 lights"
The format
function is most useful when you use more complex format specifications.
Specification Syntax
The specification is a string that includes formatting verbs that are introduced
with the %
character. The function call must then have one additional argument
for each verb sequence in the specification. The verbs are matched with
consecutive arguments and formatted as directed, as long as each given argument
is convertible to the type required by the format verb.
By default, %
sequences consume successive arguments starting with the first.
Introducing a [n]
sequence immediately before the verb letter, where n
is a
decimal integer, explicitly chooses a particular value argument by its
one-based index. Subsequent calls without an explicit index will then proceed
with n
+1, n
+2, etc.
The function produces an error if the format string requests an impossible conversion or accesses more arguments than are given. An error is also produced for an unsupported format verb.
Verbs
The specification may contain the following verbs.