Menu

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.
Documentationbreadcrumb arrow Grafana Agentbreadcrumb arrow Flow modebreadcrumb arrow Referencebreadcrumb arrow Standard librarybreadcrumb arrow format
Open source

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.

river 
format(spec, values...)

Examples

river 
> 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.

VerbResult
%%Literal percent sign, consuming no value.
%tConvert to boolean and produce true or false.
%bConvert to integer number and produce binary representation.
%dConvert to integer and produce decimal representation.
%oConvert to integer and produce octal representation.
%xConvert to integer and produce hexadecimal representation with lowercase letters.
%XLike %x, but use uppercase letters.
%eConvert to number and produce scientific notation, like -1.234456e+78.
%ELike %e, but use an uppercase E to introduce the exponent.
%fConvert to number and produce decimal fraction notation with no exponent, like 123.456.
%gLike %e for large exponents or like %f otherwise.
%GLike %E for large exponents or like %f otherwise.
%sConvert to string and insert the string’s characters.
%qConvert to string and produce a JSON quoted string representation.