CloudCastle Grafana Loki API

LogQLBuilder
in package
implements Stringable

FinalYes

Строитель лог-запросов LogQL.

Типобезопасная сборка выражения: селектор потоков, фильтры строк, парсеры (json/logfmt/pattern/regexp/unpack), фильтры меток, форматирование — и переход к метрик-запросу через range(). Все значения экранируются, имена меток проверяются — построенный запрос синтаксически корректен по построению.

$logql = (new LogQLBuilder())
    ->withLabel('app', 'api')
    ->withLineContains('error')
    ->withJson()
    ->withWhere('status', '>=', 500)
    ->build();
// {app="api"} |= "error" | json | status>=500

Table of Contents

Interfaces

Stringable

Methods

__construct()  : mixed
__toString()  : string
Строковое представление — собранное выражение.
build()  : string
Собирает выражение LogQL.
range()  : MetricBuilder
Переход к метрик-запросу: применяет range-функцию к потоку.
withDecolorize()  : self
Удаление ANSI-цветов из строк: `| decolorize`.
withDrop()  : self
Удаление меток из результата: `| drop a, b`.
withJson()  : self
Парсер JSON: `| json` либо `| json field="expr"` с выражениями.
withKeep()  : self
Сохранение только перечисленных меток: `| keep a, b`.
withLabel()  : self
Матчер равенства метки: `name="value"`.
withLabelFormat()  : self
Переименование/вычисление метки: `| label_format target=source`.
withLabelMatch()  : self
Матчер по регулярному выражению: `name=~"regex"`.
withLabelNot()  : self
Матчер неравенства метки: `name!="value"`.
withLabelNotMatch()  : self
Отрицающий матчер по регулярному выражению: `name!~"regex"`.
withLineContains()  : self
Фильтр строк «содержит»: `|= "needle"`.
withLineFormat()  : self
Переформатирование строки: `| line_format "template"`.
withLineMatch()  : self
Фильтр строк по регулярному выражению: `|~ "regex"`.
withLineNotContains()  : self
Фильтр строк «не содержит»: `!= "needle"`.
withLineNotMatch()  : self
Отрицающий фильтр строк по регулярному выражению: `!~ "regex"`.
withLogfmt()  : self
Парсер logfmt: `| logfmt`.
withPattern()  : self
Парсер по шаблону: `| pattern "<template>"`.
withRegexp()  : self
Парсер по регулярному выражению: `| regexp "regex"`.
withUnpack()  : self
Распаковка вложенных меток promtail: `| unpack`.
withUnwrap()  : self
Развёртывание метки в значение метрики: `| unwrap name`.
withWhere()  : self
Фильтр меток: `| name op value`.
withWhereRaw()  : self
Сырой фильтр меток без экранирования: `| duration > 200ms`.

Methods

__toString()

Строковое представление — собранное выражение.

public __toString() : string
Attributes
#[Override]
Return values
string

build()

Собирает выражение LogQL.

public build() : string
Tags
throws
ConfigException

когда селектор пуст

Return values
string

range()

Переход к метрик-запросу: применяет range-функцию к потоку.

public range(RangeFunction $function, string $range[, float|null $param = null ]) : MetricBuilder

ВНИМАНИЕ: range подставляется в запрос без экранирования. Не передавайте сюда недоверенный ввод — задавайте интервал константой.

Parameters
$function : RangeFunction

range-функция LogQL

$range : string

интервал (например, «5m»)

$param : float|null = null

параметр функции (квантиль для QuantileOverTime)

Return values
MetricBuilder

withDecolorize()

Удаление ANSI-цветов из строк: `| decolorize`.

public withDecolorize() : self
Return values
self

withDrop()

Удаление меток из результата: `| drop a, b`.

public withDrop(string ...$names) : self
Parameters
$names : string
Return values
self

withJson()

Парсер JSON: `| json` либо `| json field="expr"` с выражениями.

public withJson([array<string, string> $fields = [] ]) : self
Parameters
$fields : array<string, string> = []

извлекаемые поля (метка → выражение)

Return values
self

withKeep()

Сохранение только перечисленных меток: `| keep a, b`.

public withKeep(string ...$names) : self
Parameters
$names : string
Return values
self

withLabel()

Матчер равенства метки: `name="value"`.

public withLabel(string $name, string $value) : self
Parameters
$name : string
$value : string
Return values
self

withLabelFormat()

Переименование/вычисление метки: `| label_format target=source`.

public withLabelFormat(string $target, string $source) : self

ВНИМАНИЕ: source подставляется без экранирования (это может быть имя метки или шаблон). Не передавайте сюда недоверенный ввод — осознанная лазейка для доверенных выражений.

Parameters
$target : string
$source : string
Return values
self

withLabelMatch()

Матчер по регулярному выражению: `name=~"regex"`.

public withLabelMatch(string $name, string $regex) : self
Parameters
$name : string
$regex : string
Return values
self

withLabelNot()

Матчер неравенства метки: `name!="value"`.

public withLabelNot(string $name, string $value) : self
Parameters
$name : string
$value : string
Return values
self

withLabelNotMatch()

Отрицающий матчер по регулярному выражению: `name!~"regex"`.

public withLabelNotMatch(string $name, string $regex) : self
Parameters
$name : string
$regex : string
Return values
self

withLineContains()

Фильтр строк «содержит»: `|= "needle"`.

public withLineContains(string $needle) : self
Parameters
$needle : string
Return values
self

withLineFormat()

Переформатирование строки: `| line_format "template"`.

public withLineFormat(string $template) : self
Parameters
$template : string
Return values
self

withLineMatch()

Фильтр строк по регулярному выражению: `|~ "regex"`.

public withLineMatch(string $regex) : self
Parameters
$regex : string
Return values
self

withLineNotContains()

Фильтр строк «не содержит»: `!= "needle"`.

public withLineNotContains(string $needle) : self
Parameters
$needle : string
Return values
self

withLineNotMatch()

Отрицающий фильтр строк по регулярному выражению: `!~ "regex"`.

public withLineNotMatch(string $regex) : self
Parameters
$regex : string
Return values
self

withLogfmt()

Парсер logfmt: `| logfmt`.

public withLogfmt([array<string, string> $fields = [] ]) : self
Parameters
$fields : array<string, string> = []

извлекаемые поля (метка → выражение)

Return values
self

withPattern()

Парсер по шаблону: `| pattern "<template>"`.

public withPattern(string $template) : self
Parameters
$template : string
Return values
self

withRegexp()

Парсер по регулярному выражению: `| regexp "regex"`.

public withRegexp(string $regex) : self
Parameters
$regex : string
Return values
self

withUnpack()

Распаковка вложенных меток promtail: `| unpack`.

public withUnpack() : self
Return values
self

withUnwrap()

Развёртывание метки в значение метрики: `| unwrap name`.

public withUnwrap(string $name) : self
Parameters
$name : string
Return values
self

withWhere()

Фильтр меток: `| name op value`.

public withWhere(string $name, string $operator, string|int|float $value) : self

Строковые значения экранируются, числовые подставляются как есть — это позволяет сравнивать длительности (duration > 200ms передаётся строкой без кавычек не получится, используйте withWhereRaw).

Parameters
$name : string

имя метки

$operator : string

оператор: =, ==, !=, >, >=, <, <=, =~, !~

$value : string|int|float

значение сравнения

Tags
throws
ConfigException

при неизвестном операторе

Return values
self

withWhereRaw()

Сырой фильтр меток без экранирования: `| duration > 200ms`.

public withWhereRaw(string $expression) : self

Для типизированных сравнений LogQL (длительности, байты), которые не являются ни строкой, ни числом.

ВНИМАНИЕ: выражение подставляется в запрос как есть, без экранирования. Не передавайте сюда недоверенный пользовательский ввод — это осознанная лазейка для доверенных выражений.

Parameters
$expression : string
Return values
self
On this page

Search results