LogQLBuilder
in package
implements
Stringable
Строитель лог-запросов 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
__construct()
public
__construct() : mixed
__toString()
Строковое представление — собранное выражение.
public
__toString() : string
Attributes
- #[Override]
Return values
stringbuild()
Собирает выражение LogQL.
public
build() : string
Tags
Return values
stringrange()
Переход к метрик-запросу: применяет 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
MetricBuilderwithDecolorize()
Удаление ANSI-цветов из строк: `| decolorize`.
public
withDecolorize() : self
Return values
selfwithDrop()
Удаление меток из результата: `| drop a, b`.
public
withDrop(string ...$names) : self
Parameters
- $names : string
Return values
selfwithJson()
Парсер JSON: `| json` либо `| json field="expr"` с выражениями.
public
withJson([array<string, string> $fields = [] ]) : self
Parameters
- $fields : array<string, string> = []
-
извлекаемые поля (метка → выражение)
Return values
selfwithKeep()
Сохранение только перечисленных меток: `| keep a, b`.
public
withKeep(string ...$names) : self
Parameters
- $names : string
Return values
selfwithLabel()
Матчер равенства метки: `name="value"`.
public
withLabel(string $name, string $value) : self
Parameters
- $name : string
- $value : string
Return values
selfwithLabelFormat()
Переименование/вычисление метки: `| label_format target=source`.
public
withLabelFormat(string $target, string $source) : self
ВНИМАНИЕ: source подставляется без экранирования (это может быть
имя метки или шаблон). Не передавайте сюда недоверенный ввод —
осознанная лазейка для доверенных выражений.
Parameters
- $target : string
- $source : string
Return values
selfwithLabelMatch()
Матчер по регулярному выражению: `name=~"regex"`.
public
withLabelMatch(string $name, string $regex) : self
Parameters
- $name : string
- $regex : string
Return values
selfwithLabelNot()
Матчер неравенства метки: `name!="value"`.
public
withLabelNot(string $name, string $value) : self
Parameters
- $name : string
- $value : string
Return values
selfwithLabelNotMatch()
Отрицающий матчер по регулярному выражению: `name!~"regex"`.
public
withLabelNotMatch(string $name, string $regex) : self
Parameters
- $name : string
- $regex : string
Return values
selfwithLineContains()
Фильтр строк «содержит»: `|= "needle"`.
public
withLineContains(string $needle) : self
Parameters
- $needle : string
Return values
selfwithLineFormat()
Переформатирование строки: `| line_format "template"`.
public
withLineFormat(string $template) : self
Parameters
- $template : string
Return values
selfwithLineMatch()
Фильтр строк по регулярному выражению: `|~ "regex"`.
public
withLineMatch(string $regex) : self
Parameters
- $regex : string
Return values
selfwithLineNotContains()
Фильтр строк «не содержит»: `!= "needle"`.
public
withLineNotContains(string $needle) : self
Parameters
- $needle : string
Return values
selfwithLineNotMatch()
Отрицающий фильтр строк по регулярному выражению: `!~ "regex"`.
public
withLineNotMatch(string $regex) : self
Parameters
- $regex : string
Return values
selfwithLogfmt()
Парсер logfmt: `| logfmt`.
public
withLogfmt([array<string, string> $fields = [] ]) : self
Parameters
- $fields : array<string, string> = []
-
извлекаемые поля (метка → выражение)
Return values
selfwithPattern()
Парсер по шаблону: `| pattern "<template>"`.
public
withPattern(string $template) : self
Parameters
- $template : string
Return values
selfwithRegexp()
Парсер по регулярному выражению: `| regexp "regex"`.
public
withRegexp(string $regex) : self
Parameters
- $regex : string
Return values
selfwithUnpack()
Распаковка вложенных меток promtail: `| unpack`.
public
withUnpack() : self
Return values
selfwithUnwrap()
Развёртывание метки в значение метрики: `| unwrap name`.
public
withUnwrap(string $name) : self
Parameters
- $name : string
Return values
selfwithWhere()
Фильтр меток: `| 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
Return values
selfwithWhereRaw()
Сырой фильтр меток без экранирования: `| duration > 200ms`.
public
withWhereRaw(string $expression) : self
Для типизированных сравнений LogQL (длительности, байты), которые не являются ни строкой, ни числом.
ВНИМАНИЕ: выражение подставляется в запрос как есть, без экранирования. Не передавайте сюда недоверенный пользовательский ввод — это осознанная лазейка для доверенных выражений.
Parameters
- $expression : string