Добавление переменной на дашборд

Добавление переменной на дашборд

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

Устарело: поля dt.entity.*

Если вы видите следующее сообщение:

Поля dt.entity.* устарели. Пожалуйста, используйте поля dt.smartscape.* вместо них.

мы рекомендуем использовать эквивалентное поле dt.smartscape.*.

Устаревшие поля dt.entity.* в конечном итоге будут удалены.

Добавление переменной

Чтобы добавить переменную на дашборд

1. В заголовке дашборда откройте меню Добавить и выберите Переменные.
   • Сочетание клавиш: Shift+V
2. Отображается панель Переменная.
3. Определите переменную.
   • Имя: имя переменной. Оно отображается на дашборде и может содержать любые символы.
     • Ключ-АСТРОМ выводит ключ из имени, заменяя любой символ, не являющийся буквой или цифрой, на _. Добавьте префикс $ к ключу, чтобы ссылаться на переменную в запросах, коде и заголовках.
     • Ключ не может начинаться с зарезервированного префикса dt_.
     • Чтобы найти ключ переменной, откройте её меню или проверьте выноску, отображаемую, пока переменная ещё не используется.
   • Тип: может быть одним из следующих:
     • DQL: значение возвращается из запроса, который вы вводите при определении переменной.
       • Выберите Запустить, чтобы протестировать ваш запрос.
     • Код: значение возвращается из кода, который вы вводите при определении переменной.
     • Список: список значений с разделителями-запятыми (CSV).
       • Чтобы определить возможные значения, введите их (через запятую) в поле под Данными.
       • Чтобы определить значение по умолчанию, выберите одно из списка Значение по умолчанию.
       • Чтобы разрешить выбор нескольких значений одновременно, включите Множественный выбор.
     • Свободный текст: произвольный текст. Вы можете ввести Значение по умолчанию. Ваши изменения сохраняются автоматически.
4. Настройте Параметры отображения.
   • Если раскрывающийся список переменной должен отображаться на дашборде, включите Отображать как фильтр на дашборде.
   • Отключите его, когда хотите скрыть его, например, когда переменная используется как статическое значение across плиток, но не должна отображаться пользователю дашборда.
   • Если пользователи вашего дашборда должны иметь возможность выбирать несколько значений одновременно в раскрывающемся списке переменной, включите Множественный выбор.
   • Отключите его, когда хотите использовать только отдельные значения раскрывающегося списка переменной.
   • Выберите Значение по умолчанию для раскрывающегося списка переменной. Если вы ничего не введёте в это поле, будет выбрано первое доступное значение.
5. Когда закончите, выберите < Переменная в верхней части, чтобы перейти на панель Переменные, или выберите соответствующую кнопку, чтобы закрыть панель Переменные.

Переменные в дашбордах могут быть определены как зависимые от других переменных.

Значение переменной пересчитывается, если её определение ссылается на другую переменную и значение другой переменной изменяется.

Например, если значение переменной A изменяется, значение любой переменной, определение которой ссылается на переменную A, пересчитывается.

Циклы не допускаются.

Например, если значение переменной A зависит от значения переменной B, значение переменной B не может зависеть от значения переменной A.

То, как вы редактируете переменную, зависит от Типа. Подробности и примеры см. в разделах:

• DQL-переменная
• Переменная-список
• Переменная-код
• Переменная свободного текста

Использование переменной

После создания переменной вы готовы использовать её в запросе.

Всегда помните о необходимости добавлять префикс $ к ключу переменной в ваших запросах.

Ключ-АСТРОМ выводит ключ из имени переменной, заменяя любой символ, не являющийся буквой или цифрой, на _. Например, переменная с именем My Total получает ключ My_Total, поэтому вы ссылаетесь на неё как $My_Total в вашем запросе.

Чтобы найти ключ переменной, откройте её меню или проверьте выноску, отображаемую, пока переменная ещё не используется.

Например:

1. Откройте меню и выберите Переменные, чтобы добавить переменную на ваш дашборд.
2. Определите следующую переменную:
   • Имя: Host
   • Тип: DQL
   • Запрос:

fetch dt.entity.host
| fields entity.name

1. Включите Множественный выбор, чтобы вы могли выбрать более одного значения за раз для отображения в ваших визуализациях.
2. Ваши изменения сохраняются автоматически.
3. Выберите соответствующую кнопку, чтобы закрыть панель Переменная.

Использование с плиткой DQL

1. Откройте меню и выберите DQL.
2. Скопируйте и вставьте следующий запрос в поле DQL и выберите Запустить.

fetch logs, scanLimitGBytes: 20
| filter in(host.name, array($Host))
| makeTimeseries count(), by:{ host.name }

1. Обратите внимание, что запрос ссылается на нашу новую переменную Host как $Host, где знак доллара указывает, что это ключ переменной.

Или, если вы не используете переменную с множественным выбором, вы можете ссылаться на неё так:

fetch logs, scanLimitGBytes: 20
| filter host.name == $Host
| makeTimeseries count(), by:{ host.name }

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

Вы, конечно, можете использовать вашу переменную в нескольких запросах.

Использование с плиткой Explore

Чтобы использовать переменную в плитке данных Explore

1. Откройте меню и выберите Логи.
2. Выберите соответствующий значок и затем выберите host.name из Доступных фильтров.
3. В добавленном поле фильтра введите $, чтобы получить предложения для всех доступных переменных, затем выберите $Host.

Примечание: добавление переменных в плитки Explore работает только для переменных с одиночным выбором в сочетании с оператором =.

Список переменных

Чтобы перечислить все переменные, выполните одно из следующих действий:

• Откройте меню и выберите Все переменные.
• Обратите внимание, что это меню доступно только после добавления хотя бы одной переменной на дашборд.

В этом примере для дашборда определены четыре переменные — LogLevels, MyFreeTextVariable, Variable1 и Variable2, и мы можем видеть их текущие значения под их именами.

Выберите значок настроек в правом верхнем углу дашборда, затем выберите Переменные.

Пример:

В приведённом выше примере:

• Для дашборда определены четыре переменные — LogLevels, MyFreeTextVariable, Variable1 и Variable2.
• Две из переменных — Variable1 и Variable2 — отображают значок предупреждения. Подробности см. в разделе «Устранение неполадок переменных».

Отсюда у вас есть следующие параметры, специфичные для переменных:

• Чтобы просмотреть или изменить определение переменной, выберите её имя.
• Чтобы добавить переменную, выберите Переменная.
• Чтобы скрыть или отобразить переменную, выберите соответствующий значок.
  • Скрытая переменная с одиночным или множественным выбором автоматически определяет своё значение из доступных параметров; она не использует сохранённое значение по умолчанию.
  • Скрытые переменные с множественным выбором определяются как * (все параметры).
  • Скрытые переменные с одиночным выбором определяются как первый доступный параметр.
  • Сохранённое значение по умолчанию сохраняется и восстанавливается, если вы снова сделаете переменную видимой. Чтобы закрепить скрытую переменную за конкретным значением, используйте вместо этого переменную свободного текста.
• Чтобы переместить переменную вверх или вниз по списку, выберите соответствующий значок и перетащите переменную на новую позицию в списке.
• Чтобы увидеть другие параметры, специфичные для переменной — Редактировать, Дублировать, Переместить вверх, Переместить вниз и Удалить — откройте меню.

Сброс переменных

Чтобы применить значения по умолчанию к переменным, откройте меню и выберите Сбросить к значениям по умолчанию.

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

Редактирование переменной

1. Откройте меню и выберите Все переменные.
2. В столбце Имя выберите имя переменной, которую хотите отредактировать.
3. Отредактируйте и проверьте переменную.
   • То, как вы редактируете переменную, зависит от Типа. Подробности и примеры см. в разделах:
     • DQL-переменная
     • Переменная-список
     • Переменная-код
     • Переменная свободного текста
4. Выберите соответствующую кнопку, чтобы закрыть панель Переменные.

Удаление переменной

Чтобы удалить переменную с дашборда

1. Откройте меню и выберите Все переменные.
2. Найдите переменную, которую хотите удалить, в столбце Имя, откройте меню для этой строки и выберите Удалить.
3. Выберите соответствующую кнопку, чтобы закрыть панель Переменные.

Изменение значений переменных

Если дашборд имеет одну или несколько переменных, они перечислены по имени в левом верхнем углу дашборда, под именем дашборда. Когда вы изменяете значения переменных, содержимое дашборда пересчитывается и отображается в соответствии с новыми значениями.

Чтобы изменить значение переменной

1. В левом верхнем углу дашборда найдите имя переменной.
2. Используйте меню или поле редактирования под именем переменной, чтобы изменить значение.
   • Если переменная допускает только один выбор (значение) за раз, выберите значение, которое хотите применить к дашборду.
   • Если переменная допускает несколько выборов (значений) за раз, установите флажок для каждого значения, которое хотите применить к дашборду. Имя меню для этой переменной показывает, сколько значений выбрано.
   • Для переменной Свободный текст вы можете редактировать текст в поле под именем переменной.

Изменение порядка переменных

Чтобы изменить порядок переменных на вашем дашборде

1. Откройте меню и выберите Все переменные.
2. Перетащите переменные в нужный порядок.

Как вариант: откройте меню для переменной, которую хотите переместить, и выберите Переместить вверх или Переместить вниз.

Типы переменных

DQL-переменная

Чтобы определить DQL-переменную

1. Установите Имя — имя, которое хотите дать вашей переменной.
   • Оно отображается в верхней части дашборда и указано на панели Переменные. Оно может содержать любые символы, например: status, myHosts, Variable01 или My Total.
   • Ключ-АСТРОМ выводит ключ из имени, заменяя любой символ, не являющийся буквой или цифрой, на _. Например, имя My Total становится ключом My_Total. Используйте ключ с префиксом $, чтобы ссылаться на переменную в запросах, коде и заголовках.
   • Ключ не может начинаться с зарезервированного префикса dt_.
   • Чтобы найти ключ переменной, откройте её меню или проверьте выноску, отображаемую, пока переменная ещё не используется.
2. Установите Тип в DQL.
3. В разделе Данные введите запрос. Обязательно используйте summarize и collectDistinct для получения уникальных значений из источников данных, таких как логи.
4. Выберите Запустить и проверьте результаты в разделе Предварительный просмотр, чтобы убедиться, что всё работает как ожидалось.
5. Если вы хотите иметь возможность выбирать более одного значения за раз, включите Множественный выбор.

Если вы добавите оба примера ниже на ваш дашборд, вы сможете фильтровать дашборд по хосту и уровню серьёзности логов. Обязательно включите Множественный выбор, если хотите выбирать более одного за раз.

Пример DQL-переменной

• Имя: Hosts
• Тип: DQL
• Определение:

fetch dt.entity.host
  | fields id

Если вы хотите использовать человекочитаемое имя, используйте | fields entity.name вместо | fields id.

Замена переменных

В плитках DQL у вас есть четыре варианта обёртывания значения переменной и того, как заполнитель переменной заменяется перед выполнением запроса. Эти параметры применяются только к плиткам DQL и игнорируются для плиток Код и Markdown.

$varName (по умолчанию)**:

• Если вы не указываете стратегию (например, $varName), значение переменной оборачивается в двойные кавычки ("). Это полезно для строк, таких как имена сущностей или категории.
• Любые кавычки внутри переменных экранируются и игнорируются.
• Чтобы экранировать символ двойной кавычки, используйте двойную обратную косую черту: \\".
• Например, для сервиса с именем PaymentBackend в запросе DQL, где мы фильтруем по этому сервису, со стратегией по умолчанию мы заменим заполнитель переменной после = в правой части фильтра так:

| filter dt.entity.service = "PaymentBackend"

$varName:noquote:

• Если вы следуете за именем переменной с :noquote (например, $varName:noquote), значение переменной не оборачивается в кавычки. Это полезно для чисел, единиц измерения или имён функций.
• Разрешены только алфавитно-цифровые символы, точка (.), подчёркивание (_) и дефис (-).
• Запрос завершится ошибкой, если значения содержат любые другие символы.
• Например, для сервиса с именем PaymentBackend в запросе DQL, где мы фильтруем по этому сервису, со стратегией no-quote мы заменим заполнитель переменной после = в правой части фильтра так:

| filter dt.entity.service = PaymentBackend

$varName:backtick:

• Если вы следуете за именем переменной с :backtick (например, $varName:backtick), значение переменной оборачивается в символы обратной кавычки.
• Чтобы экранировать обратную кавычку, используйте двойную обратную косую черту: \\`.
• Любые обратные кавычки внутри переменных экранируются и игнорируются.
• Пример использования: идентификаторы полей.
• Например, для сервиса с именем PaymentBackend в запросе DQL, где мы фильтруем по этому сервису, со стратегией backtick мы заменим заполнитель переменной после = в правой части фильтра так:

| filter dt.entity.service = `PaymentBackend`

$varName:triplequote:

• Если вы следуете за именем переменной с :triplequote (например, $varName:triplequote), значение переменной оборачивается в символы """. Это полезно для необработанного содержимого, такого как JSON, без экранирования.
• Ничего не экранируется внутри значения.
• Запрос завершится ошибкой, если значение содержит """.
• Например, для сервиса с именем PaymentBackend в запросе DQL, где мы фильтруем по этому сервису, со стратегией triple quote мы заменим заполнитель переменной после = в правой части фильтра так:

| filter dt.entity.service = """PaymentBackend"""

Переменная-список

Чтобы определить переменную-список

1. Установите Имя — имя, которое хотите дать вашей переменной.
   • Оно отображается в верхней части дашборда и указано на панели Переменные. Оно может содержать любые символы, например: status, myHosts, Variable01 или My Total.
   • Ключ-АСТРОМ выводит ключ из имени, заменяя любой символ, не являющийся буквой или цифрой, на _. Например, имя My Total становится ключом My_Total. Используйте ключ с префиксом $, чтобы ссылаться на переменную в запросах, коде и заголовках.
   • Ключ не может начинаться с зарезервированного префикса dt_.
   • Чтобы найти ключ переменной, откройте её меню или проверьте выноску, отображаемую, пока переменная ещё не используется.
2. Установите Тип в Список.
3. В разделе Данные введите список возможных значений через запятую, например: dog,cat,horse. Обязательно удалите лишние пробелы из вашего списка.
4. Проверьте результаты в разделе Предварительный просмотр, чтобы убедиться, что всё работает как ожидалось.
5. Если вы хотите иметь возможность выбирать более одного значения за раз, включите Множественный выбор.
6. Ваши изменения сохраняются автоматически.
7. Закройте панель Переменная.

Пример переменной-списка

Этот пример добавит переменную $Status на ваш дашборд с возможностью выбора более одного статуса за раз и с четырьмя возможными значениями: WARN, ERROR, INFO, NONE.

• Имя: Status
• Тип: Список
• Определение: WARN,ERROR,INFO,NONE
• Множественный выбор: включён

Переменная-код

Чтобы определить переменную-код

1. Установите Имя — имя, которое хотите дать вашей переменной.
   • Оно отображается в верхней части дашборда и указано на панели Переменные. Оно может содержать любые символы, например: status, myHosts, Variable01 или My Total.
   • Ключ-АСТРОМ выводит ключ из имени, заменяя любой символ, не являющийся буквой или цифрой, на _. Например, имя My Total становится ключом My_Total. Используйте ключ с префиксом $, чтобы ссылаться на переменную в запросах, коде и заголовках.
   • Ключ не может начинаться с зарезервированного префикса dt_.
   • Чтобы найти ключ переменной, откройте её меню или проверьте выноску, отображаемую, пока переменная ещё не используется.
2. Установите Тип в Код.
3. В разделе Данные введите код JavaScript.
   • По соображениям безопасности при использовании переменных в плитках кода вы можете получить к ним доступ только внутри функции по умолчанию.
4. Выберите Запустить и проверьте результаты в разделе Предварительный просмотр, чтобы убедиться, что всё работает как ожидалось.
5. Если вы хотите иметь возможность выбирать более одного значения за раз, включите Множественный выбор.
6. Ваши изменения сохраняются автоматически.
7. Закройте панель Переменная.

Пример переменной-кода

• Имя: CodeVariable
• Тип: Код
• Определение:

/*
* This will run JavaScript in the DYNATRACE
* serverless environment.
* To generate variable options return string array.
*/
export default async function () {
return ["val1", "val2", "val3"]
}

Переменная свободного текста

Чтобы определить переменную свободного текста

1. Установите Имя — имя, которое хотите дать вашей переменной.
   • Оно отображается в верхней части дашборда и указано на панели Переменные. Оно может содержать любые символы, например: status, myHosts, Variable01 или My Total.
   • Ключ-АСТРОМ выводит ключ из имени, заменяя любой символ, не являющийся буквой или цифрой, на _. Например, имя My Total становится ключом My_Total. Используйте ключ с префиксом $, чтобы ссылаться на переменную в запросах, коде и заголовках.
   • Ключ не может начинаться с зарезервированного префикса dt_.
   • Чтобы найти ключ переменной, откройте её меню или проверьте выноску, отображаемую, пока переменная ещё не используется.
2. Установите Тип в Свободный текст.
3. Вы можете ввести Значение по умолчанию.

Ограничения при использовании переменных в плитках

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

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

Разрешение в команде DQL

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

fetch logs
    | ...
    | summarize count(), by: {loglevel, bin(timestamp, $resolution)}

В качестве обходного пути вы можете использовать функцию duration вместе с функцией преобразования DQL. Это обеспечивает требуемый вывод на основе вашего значения $resolution.

fetch logs

   | ...
   | summarize count(), by: {loglevel, bin(timestamp, duration(toLong($resolution), unit:"m"))}

Преобразование значений переменных в другие типы данных

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

fetch logs
    | filter amount = toString($amount)
    | ...

Максимальный общий размер переменных в URL дашборда

Если значения переменных превышают 30 КБ, они не могут быть сохранены в URL дашборда.

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

Устранение неполадок переменных

Дашборд с одной или несколькими определёнными переменными отображает переменные в строке под именем дашборда. В этом примере вы можете видеть:

• Меню переменных.
• Четыре переменные: LogLevels, MyFreeTextVariable, Variable1 и Variable2.
• Значок предупреждения.

Чтобы исследовать предупреждение, выберите значок предупреждения (или выберите > Все переменные), чтобы перечислить все переменные.

• Там снова четыре переменные: LogLevels, MyFreeTextVariable, Variable1 и Variable2.
• Две из этих переменных — Variable1 и Variable2 — отображают значок предупреждения, указывающий на возможные проблемы с каждой из них. Чтобы увидеть, почему есть предупреждение для конкретной переменной, выберите её.

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