Описание синтаксиса TraceQL в Grafana

TraceQL — это язык запросов, используемый в Grafana Tempo для фильтрации и анализа трассировок. Он позволяет выбирать трейсы и их части (спаны) на основе заданных условий. Ниже приводится описание синтаксиса TraceQL, ключевых элементов языка и примеры использования.

---

Основы синтаксиса TraceQL

1. Структура запроса
   • Запрос состоит из выражения фильтрации и опциональной команды обработки:
     
     Default

     <фильтр> [| <обработка>]

     1 2	<фильтр> [| <обработка>]

1. Фильтр
   Фильтрует трейсы или спаны на основе атрибутов, временных интервалов, названий или значений.
2. Обработка
   Выполняет дополнительные операции, такие как ограничение количества результатов (limit), агрегация, группировка.

---

Фильтрация (Filter Expressions)

Фильтр задаётся в фигурных скобках {} и может включать условия по атрибутам, времени, статусу и т.д.

Базовый фильтр

• {}:
  Возвращает все трейсы.
• {attribute_name="value"}:
  Возвращает трейсы, у которых атрибут attribute_name равен "value".
• {duration_ms > 1000}:
  Возвращает трейсы с длительностью больше 1 секунды.

Операторы сравнения

=

Равно

!=

Не равно

< >	Меньше / Больше

<= >=

Меньше или равно / Больше или равно

=~	Регулярное выражение

!~	Регулярное выражение (не соответствует)

Примеры:

Логические операторы

AND

И

OR

Или

NOT

Не

Атрибуты трассировки

Вы можете фильтровать по стандартным и пользовательским атрибутам:

• Стандартные атрибуты:
  • service.name: Название сервиса.
  • span.name: Название спана.
  • duration_ms: Длительность в миллисекундах.
  • status.code: Код статуса трейса.
• Пользовательские атрибуты: Атрибуты, добавленные вами в процессе трассировки, например:
  
  Default

  {user.id="12345"}

  1 2	{user.id="12345"}

   

Команды обработки (Pipeline Commands)

Команды обработки применяются после фильтрации с использованием оператора |.

Ограничение количества результатов

• limit <число>:
  Ограничивает количество возвращаемых трейсов.
  
  Default

  {} | limit 10

  1 2	{} | limit 10

   

Агрегация

• count():
  Возвращает количество трейсов.
  
  Default

  {service.name="frontend"} | count()

  1 2	{service.name="frontend"} | count()

   

Выбор полей

• fields():
  Возвращает только указанные атрибуты.
  
  Default

  {service.name="frontend"} | fields(service.name, duration_ms)

  1 2	{service.name="frontend"} | fields(service.name, duration_ms)

   

Сортировка

• sort <поле> [asc|desc]:
  Сортирует трейсы по указанному полю.
  
  Default

  {} | sort duration_ms desc

  1 2	{} | sort duration_ms desc

Примеры запросов TraceQL

1. Получить все трейсы:
   
   Default

   {}

   1 2

   {}

    
2. Фильтровать трейсы по имени сервиса:
   
   Default

   {service.name="backend"}

   1 2	{service.name="backend"}

    
3. Выбрать трейсы с длительностью более 2 секунд:
   
   Default

   {duration_ms > 2000}

   1 2	{duration_ms > 2000}

    
4. Найти трейсы с ошибками (status.code=2 — означает ошибки):
   
   Default

   {status.code=2}

   1 2	{status.code=2}

    
5. Сортировать трейсы по длительности:
   
   Default

   {service.name="frontend"} | sort duration_ms desc

   1 2	{service.name="frontend"} | sort duration_ms desc

    
6. Посчитать количество трейсов:
   
   Default

   {service.name="backend"} | count()

   1 2	{service.name="backend"} | count()

    
7. Комбинировать фильтры:
   
   Default

   {service.name="backend" AND duration_ms > 5000}

   1 2	{service.name="backend" AND duration_ms > 5000}

    
8. Найти трейсы с конкретным методом HTTP:
   
   Default

   {http.method="GET"}

   1 2	{http.method="GET"}

    
9. Ограничить результаты до 5 трейсов:
   
   Default

   {service.name="backend"} | limit 5

   1 2	{service.name="backend"} | limit 5

    

Полезные советы

1. Тестируйте фильтры последовательно. Начинайте с простых запросов {} и постепенно добавляйте фильтры.
2. Используйте логические операторы. Упрощайте сложные запросы, комбинируя условия через AND, OR, NOT.
3. Фокусируйтесь на атрибутах. Заранее продумывайте, какие атрибуты полезны для фильтрации и анализа, и добавляйте их в трассировке.
4. Анализируйте ошибки. Используйте status.code или пользовательские теги для быстрого выявления проблемных трейсов.

---

TraceQL — мощный инструмент для анализа трассировок в Grafana Tempo. Он позволяет глубоко исследовать данные, определять проблемы и оптимизировать ваши сервисы.