Документация Grafana Документация GlaberGraph Источники данных OpenTSDB Аннотации

Аннотации OpenTSDB

Аннотации позволяют накладывать информацию о событиях на графики, давая контекст изменениям метрик. Источник данных OpenTSDB поддерживает как аннотации, привязанные к конкретным метрикам, так и глобальные аннотации, хранящиеся в OpenTSDB.

Общую информацию об аннотациях в Grafana см. в разделе Аннотирование визуализаций.

Типы аннотаций

OpenTSDB поддерживает два типа аннотаций:

Как Grafana получает аннотации

Когда вы настраиваете запрос аннотации, Grafana запрашивает у OpenTSDB указанную метрику и получает все аннотации, связанные с временным рядом этой метрики. Запрос включает параметр globalAnnotations=true, который позволяет Grafana также получать глобальные аннотации, когда это включено.

Grafana отображает поле description каждой аннотации как текст аннотации.

Настройка запроса аннотации

Чтобы добавить аннотации OpenTSDB на дашборд:

1. Перейдите к дашборду, который нужно изменить, и нажмите Edit.
2. Нажмите значок Add new element (синий знак «плюс»).
3. Нажмите Annotation query.
4. Введите имя запроса аннотации.
5. Если вы не хотите использовать запрос аннотации сразу, снимите флажок Enabled.
6. Выберите цвет для маркеров событий аннотации.
7. Выберите вариант в раскрывающемся списке Show annotation controls in, чтобы задать, где на дашборде отображается элемент управления аннотацией.
8. Выберите вариант в раскрывающемся списке Show in, чтобы задать панели, в которых отображается аннотация.
9. Нажмите Open query editor, чтобы открыть диалоговое окно Annotation Query.
10. Выберите источник данных OpenTSDB в раскрывающемся списке Data source.
11. Настройте запрос аннотации и сопоставление полей.
12. (Необязательно) Нажмите Test annotation query, чтобы убедиться, что запрос работает правильно.
13. Нажмите Close, когда закончите настройку запроса.
14. Нажмите Save.
15. (Необязательно) Введите описание внесённых изменений.
16. Нажмите Save.
17. Нажмите Exit edit.

Поля запроса аннотации

Примеры запросов аннотаций

В следующих примерах показаны распространённые сценарии использования аннотаций.

Отслеживание развёртываний приложений

Отслеживайте, когда происходят развёртывания конкретного приложения:

Этот запрос получает аннотации, привязанные к метрике deploy.myapp, показывая события развёртывания для этого конкретного приложения.

Мониторинг общеинфраструктурных событий

Фиксируйте системные события, такие как изменения сети или обслуживание дата-центра:

Этот запрос получает и аннотации конкретной метрики, и глобальные аннотации, давая полную картину событий инфраструктуры.

Отслеживание инцидентов и сбоев

Отмечайте время начала и разрешения инцидентов:

Мониторинг изменений конфигурации

Отслеживайте, когда применяются изменения конфигурации:

Сопоставление нескольких типов событий

Вы можете добавить на один дашборд несколько запросов аннотаций, чтобы сопоставлять разные типы событий. Например:

1. Добавьте запрос аннотации «Deployments» для метрик deploy.*.
2. Добавьте запрос аннотации «Incidents» для events.incident.
3. Добавьте запрос аннотации «Maintenance» с включёнными глобальными аннотациями.

Это позволяет увидеть, как развёртывания, инциденты и окна обслуживания соотносятся с вашими данными метрик.

Как отображаются аннотации

Аннотации отображаются как вертикальные линии на панелях временных рядов в моменты, когда происходили события. Наведите курсор на маркер аннотации, чтобы увидеть:

• Имя аннотации (из конфигурации запроса)
• Описание события (из поля description аннотации OpenTSDB)
• Отметку времени

Разным запросам аннотаций можно назначить разные цвета в настройках аннотаций, чтобы различать типы событий.

Создание аннотаций в OpenTSDB

Чтобы отображать аннотации в Grafana, их сначала нужно создать в OpenTSDB. OpenTSDB предоставляет HTTP API для управления аннотациями.

Структура данных аннотации

Аннотации OpenTSDB имеют следующие поля:

Создание глобальной аннотации

Используйте API OpenTSDB, чтобы создать глобальную аннотацию:

sh Copy

curl -X POST http://<OPENTSDB_HOST>:4242/api/annotation \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": 1609459200,
    "description": "Production deployment v2.5.0",
    "notes": "Deployed new feature flags and performance improvements",
    "custom": {
      "version": "2.5.0",
      "environment": "production",
      "deployer": "jenkins"
    }
  }'

Создание аннотации для конкретной метрики

Чтобы привязать аннотацию к конкретному временному ряду, укажите tsuid:

sh Copy

curl -X POST http://<OPENTSDB_HOST>:4242/api/annotation \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": 1609459200,
    "endTime": 1609462800,
    "tsuid": "000001000001000001",
    "description": "Server maintenance",
    "notes": "Scheduled maintenance window for hardware upgrade"
  }'

Чтобы найти TSUID для метрики, используйте конечную точку OpenTSDB /api/uid/tsmeta.

Создание аннотаций программно

Встраивайте создание аннотаций в конвейеры развёртывания или системы мониторинга:

Пример скрипта развёртывания:

sh Copy

#!/bin/bash
VERSION=$1
TIMESTAMP=$(date +%s)

curl -X POST http://opentsdb.example.com:4242/api/annotation \
  -H "Content-Type: application/json" \
  -d "{
    \"startTime\": $TIMESTAMP,
    \"description\": \"Deployed version $VERSION\",
    \"custom\": {
      \"version\": \"$VERSION\",
      \"environment\": \"production\"
    }
  }"

Подробнее об API аннотаций см. в документации API аннотаций OpenTSDB.

Устранение неполадок с аннотациями

В этом разделе рассматриваются распространённые проблемы, которые могут возникнуть при работе с аннотациями OpenTSDB.

Аннотации не отображаются

Возможные причины и решения:

Текст аннотации пуст

Аннотация отображается, но текста описания нет.

Решение: убедитесь, что при создании аннотаций в OpenTSDB поле description заполнено. Grafana отображает поле description как текст аннотации.

Дальнейшие шаги

• Стройте запросы, чтобы визуализировать метрики вместе с аннотациями.
• Используйте переменные шаблонов, чтобы создавать динамичные дашборды.
• Настройте алертинг, чтобы получать уведомления при пересечении метриками пороговых значений.