Поддержка тегов Graphite

Начиная с версии 1.1.x, Graphite поддерживает хранение данных с использованием тегов для идентификации каждой серии. Это обеспечивает гораздо большую гибкость по сравнению с традиционной иерархической структурой. При использовании поддержки тегов каждая серия уникально идентифицируется своим именем и набором пар тег/значение.

Carbon

Для добавления сериалов с тегами в Graphite, их необходимо передать в Carbon, добавив теги к имени серии:

my.series;tag1=value1;tag2=value2

Carbon автоматически декодирует теги, нормализует порядок тегов и регистрирует серию в базе данных тегов.

Запросы

При запросе сериалов с тегами мы начинаем с функции seriesByTag:

# find all series that have tag1 set to value1
seriesByTag('tag1=value1')

Эта функция возвращает seriesList, который затем может быть использован другими функциями Graphite:

# find all series that have tag1 set to value1, sorted by total
seriesByTag('tag1=value1') | sortByTotal()

Функция seriesByTag поддерживает указание любого количества выражений тегов для уточнения списка соответствий. При указании нескольких выражений тегов будут возвращены только серии, которые соответствуют всем выражениям.

Выражения тегов являются строками и могут иметь следующие форматы:

tag=spec    tag value exactly matches spec
tag!=spec   tag value does not exactly match spec
tag=~value  tag value matches the regular expression spec
tag!=~spec  tag value does not match the regular expression spec

Любое задание тега, которое соответствует пустому значению, считается соответствующим сериям, у которых нет этого тега, и по крайней мере одно задание тега должно требовать ненулевого значения.

Условиям регулярных выражений присваивается якорь в начале значения.

Более сложный пример:

# find all series where name matches the regular expression cpu\..*, AND tag1 is not value1
seriesByTag('name=~cpu\..*', 'tag1!=value1')

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

# get a list of disk space used per datacenter for all webheads
seriesByTag('name=disk.used', 'server=~web.*') | groupByTags('sumSeries', 'datacenter')

# given series like:
# disk.used;datacenter=dc1;rack=a1;server=web01
# disk.used;datacenter=dc1;rack=b2;server=web02
# disk.used;datacenter=dc2;rack=c3;server=web01
# disk.used;datacenter=dc2;rack=d4;server=web02

# will return the following new series, each containing the sum of the values for that datacenter:
# disk.used;datacenter=dc1
# disk.used;datacenter=dc2

Наконец, функция aliasByTags используется для форматирования имён серий для отображения. Это аналог функции aliasByNode на основе тегов.

# given series like:
# disk.used;datacenter=dc1;rack=a1;server=web01
# disk.used;datacenter=dc1;rack=b2;server=web02

# format series name using datacenter tag:
seriesByTag('name=disk.used','datacenter=dc1') | aliasByTags('server', 'name')

# will return
# web01.disk.used
# web02.disk.used

Хранение в базе данных

Поскольку Whisper и другие бэкэнды для хранения данных предназначены для хранения простых временных рядов (ключ метрики, значение и метка времени), Graphite хранит информацию о тегах в отдельной базе данных тегов (TagDB). TagDB является подключаемым хранилищем; по умолчанию она использует базу данных Graphite SQLite, MySQL или PostgreSQL, но также может быть настроена для использования внешнего сервера Redis или пользовательского плагина.

Локальная база данных TagDB

Локальная база данных TagDB хранит информацию о тегах в таблицах внутри базы данных graphite-web. Она поддерживает SQLite, MySQL и Postgres и включена по умолчанию.

Redis TagDB

Redis TagDB будет хранить информацию о тегах на сервере Redis и выбирается путем установки TAGDB='graphite.tags.redis.RedisTagDB' в файле local_settings.py. Существует 3 дополнительных параметра конфигурации для Redis TagDB:

TAGDB_REDIS_HOST = 'localhost'
TAGDB_REDIS_PORT = 6379
TAGDB_REDIS_DB = 0

Параметры по умолчанию (выше) подключатся к локальному серверу Redis на стандартном порту и будут использовать стандартную базу данных.

HTTP(S) TagDB

HTTP(S) TagDB используется для делегирования всех операций с тегами внешнему серверу, который реализует HTTP API для тегов Graphite. Она может быть использована в кластеризованных сценариях Graphite или с пользовательскими хранилищами данных. Выбирается путем установки TAGDB='graphite.tags.http.HttpTagDB' в файле local_settings.py. Существует 4 дополнительных параметра конфигурации для HTTP(S) TagDB:

TAGDB_HTTP_URL = 'https://another.server'
TAGDB_HTTP_USER = ''
TAGDB_HTTP_PASSWORD = ''
TAGDB_HTTP_AUTOCOMPLETE = False

TAGDB_HTTP_URL является обязательным. TAGDB_HTTP_USER и TAGDB_HTTP_PASSWORD являются необязательными и, если указаны, будут использоваться для отправки заголовка Basic Authorization во всех запросах.

TAGDB_HTTP_AUTOCOMPLETE также является необязательным, если он установлен на True, запросы автозаполнения будут перенаправлены в удаленную TagDB, в противном случае запросы /tags/findSeries, /tags и /tags/<tag> будут использоваться для предоставления функциональности автозаполнения.

Если REMOTE_STORE_FORWARD_HEADERS определен, эти заголовки также будут перенаправлены в удаленную TagDB.

Добавление серий в TagDB

Обычно carbon позаботится об этом; он отправляет все новые серии в TagDB и периодически повторно отправляет все серии, чтобы убедиться, что TagDB поддерживается в актуальном состоянии. Есть 2 параметра конфигурации carbon, связанные с тегами; параметр GRAPHITE_URL указывает URL-адрес вашей установки graphite-web (по умолчанию http://127.0.0.1:8000), а параметр TAG_UPDATE_INTERVAL указывает, как часто каждая серия должна повторно отправляться в TagDB (по умолчанию каждые 100 обновлений).

Серии могут быть отправлены по HTTP POST с помощью инструментов командной строки, таких как curl, или с помощью различных библиотек программирования HTTP.

$ curl -X POST "http://graphite/tags/tagSeries" \
  --data-urlencode 'path=disk.used;rack=a1;datacenter=dc1;server=web01'

"disk.used;datacenter=dc1;rack=a1;server=web01"

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

Для добавления нескольких серий в один HTTP-запрос используйте конечный пункт /tags/tagMultiSeries, который поддерживает несколько параметров path:

$ curl -X POST "http://graphite/tags/tagMultiSeries" \
  --data-urlencode 'path=disk.used;rack=a1;datacenter=dc1;server=web01' \
  --data-urlencode 'path=disk.used;rack=a1;datacenter=dc1;server=web02' \
  --data-urlencode 'pretty=1'

[
  "disk.used;datacenter=dc1;rack=a1;server=web01",
  "disk.used;datacenter=dc1;rack=a1;server=web02"
]

Этот конечный пункт возвращает список канонизированных путей в том же порядке, в котором они указаны.

Обзор тегов

Вы можете использовать HTTP API для получения списков определенных тегов, значений для каждого тега и поиска серий, используя ту же логику, что и функция seriesByTag.

Для получения списка определенных тегов:

$ curl -s "http://graphite/tags?pretty=1"

[
  {
    "tag": "datacenter"
  },
  {
    "tag": "name"
  },
  {
    "tag": "rack"
  },
  {
    "tag": "server"
  }
]

Вы можете отфильтровать возвращаемый список, предоставив регулярное выражение в параметре filter:

$ curl -s "http://graphite/tags?pretty=1&filter=data"

[
  {
    "tag": "datacenter"
  }
]

Для получения списка значений для конкретного тега:

$ curl -s "http://graphite/tags/datacenter?pretty=1"

{
  "tag": "datacenter",
  "values": [
    {
      "count": 2,
      "value": "dc1"
    },
    {
      "count": 2,
      "value": "dc2"
    }
  ]
}

Вы можете отфильтровать возвращаемый список значений, используя параметр filter:

$ curl -s "http://graphite/tags/datacenter?pretty=1&filter=dc1"

{
  "tag": "datacenter",
  "values": [
    {
      "count": 2,
      "value": "dc1"
    }
  ]
}

Наконец, для поиска серий, соответствующих набору выражений тегов:

$ curl -s "http://graphite/tags/findSeries?pretty=1&expr=datacenter=dc1&expr=server=web01"

[
  "disk.used;datacenter=dc1;rack=a1;server=web01"
]

Поддержка автозаполнения

HTTP API предоставляет 2 конечных пункта для поддержки автозаполнения тегов и значений на основе серий, которые соответствуют заданному набору выражений тегов.

Каждый из этих конечных пунктов принимает необязательный список выражений тегов, используя тот же синтаксис, что и конечный пункт /tags/findSeries.

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

Результаты ограничены 100 по умолчанию, это можно изменить, передав limit=X в параметрах запроса. Возвращаемый JSON по умолчанию представляет собой компактное представление; если pretty=1 передаётся в параметрах запроса, возвращаемый JSON будет отформатирован с новой строкой и отступами.

Для получения списка автозаполнения тегов:

$ curl -s "http://graphite/tags/autoComplete/tags?pretty=1&limit=100"

[
  "datacenter",
  "name",
  "rack",
  "server"
]

Для фильтрации по префиксу:

$ curl -s "http://graphite/tags/autoComplete/tags?pretty=1&tagPrefix=d"

[
  "datacenter"
]

Если вы предоставляете список выражений тегов, указанные теги исключаются, и результат фильтруется только до тех тегов, которые встречаются в сериях, соответствующих этим выражениям:

$ curl -s "http://graphite/tags/autoComplete/tags?pretty=1&expr=datacenter=dc1&expr=server=web01"

[
  "name",
  "rack"
]

Для получения списка автозаполнения значений для заданного тега:

$ curl -s "http://graphite/tags/autoComplete/values?pretty=1&tag=rack"

[
  "a1",
  "a2",
  "b1",
  "b2"
]

Для фильтрации по префиксу:

$ curl -s "http://graphite/tags/autoComplete/values?pretty=1&tag=rack&valuePrefix=a"

[
  "a1",
  "a2"
]

Если вы предоставляете список выражений тегов, результат фильтруется только до тех значений, которые встречаются для указанного тега в сериях, соответствующих этим выражениям:

$ curl -s "http://graphite/tags/autoComplete/values?pretty=1&tag=rack&expr=datacenter=dc1&expr=server=web01"

[
  "a1"
]

Удаление серий из TagDB

При удалении серии из хранилища данных (например, путём удаления файлов .wsp из папок хранения whisper), она должна быть также удалена из базы данных тегов. Наличие серий в базе данных тегов, которые не существуют в хранилище данных, не вызовет проблем с графиками, но заставит систему выполнять ненужную работу во время рендеринга графиков, поэтому рекомендуется очищать базу данных тегов при удалении серий из хранилища данных.

Серии могут быть удалены путём отправки HTTP POST на конечный пункт /tags/delSeries:

$ curl -X POST "http://graphite/tags/delSeries" \
  --data-urlencode 'path=disk.used;datacenter=dc1;rack=a1;server=web01'

true

Чтобы удалить несколько серий за один раз, передайте несколько параметров path:

$ curl -X POST "http://graphite/tags/delSeries" \
  --data-urlencode 'path=disk.used;datacenter=dc1;rack=a1;server=web01' \
  --data-urlencode 'path=disk.used;datacenter=dc1;rack=a1;server=web02'

true