Перейти к содержанию

Данные подстановки в Grail

  • Объяснение

Предварительный просмотр

Хранение данных подстановки в Grail позволяет обогащать данные наблюдаемости вашими пользовательскими данными. Вы можете загрузить данные подстановки и объединить их с существующими данными в Grail, такими как logs, events, spans или metrics.

Диаграмма, демонстрирующая работу данных подстановки в Grail.

Dynatrace хранит данные подстановки в виде табличных файлов в Resource Store, который является частью Grail. Вы можете загружать и управлять данными подстановки через Resource Store API. После сохранения в Grail вы можете использовать файлы подстановки для обогащения данных в запросах DQL.

Вы можете определять таблицы подстановки в Investigations Investigations, который в настоящее время предоставляет единственный пользовательский интерфейс для создания и управления таблицами подстановки без использования API. Инструкции см. в разделе Создание и использование таблиц подстановки.

Файлы подстановки

Статические данные, такие как таблицы подстановки, могут быть постоянно сохранены в Grail в виде файлов. Мы ссылаемся на файлы через путь к файлу, например /lookups/http_status_codes. К путям файлов применяются следующие соглашения, которые фактически организуют файлы, хранящиеся в Grail, в структуру, подобную папкам:

  • Должны содержать только буквенно-цифровые символы (a-zA-Z0-9), -, _, . или /.
  • Должны начинаться с /.
  • Должны заканчиваться символом a-zA-Z0-9.
  • Должны содержать не менее двух символов /.
  • Между любыми двумя последовательными символами / должен быть хотя бы один буквенно-цифровой символ (a-zA-Z0-9).

Путь к файлу должен начинаться с /lookups при хранении данных подстановки в Grail.

Организация файлов

Соглашения об именовании позволяют организовать файлы как обычную файловую систему. Использование префиксов, имитирующих папки, например в пути к файлу /lookups/my_team/allow_list, упрощает поиск и управление файлами подстановки, хранящимися в Grail.

Разрешения

Для чтения данных подстановки, хранящихся в Grail, политика, привязанная к вашей группе пользователей, должна содержать следующее разрешение:

  • storage:files:read

Для загрузки данных подстановки в Grail через REST API или их удаления политика, привязанная к вашей группе пользователей, должна содержать следующие разрешения:

  • storage:files:write
  • storage:files:delete

Все разрешения могут быть ограничены определёнными путями или префиксами, предоставляя пользователям доступ только к ограниченному набору файлов. Подробнее о настройке необходимых разрешений см. в разделе Разрешения в Grail.

При создании токена OAuth или токена платформы для выполнения вызовов API из клиента API убедитесь, что эти разрешения также настроены для токена. Пользователь, связанный с этим токеном OAuth или токеном платформы, должен иметь назначенные разрешения.

Предварительный просмотр (подключение)

Клиенты с Dynatrace Platform Subscription (DPS), модели лицензирования для всех возможностей Dynatrace.") могут присоединиться к предварительному просмотру данных подстановки в Grail. В период предварительного просмотра разрешения storage:files не включены в политики Grail по умолчанию. Вы можете подключиться к программе предварительного просмотра, вручную добавив разрешения на доступ к файлам подстановки в свои пользовательские политики.

Вы можете настроить разрешения с помощью Account Management. Чтобы предоставить полный доступ ко всем данным подстановки в /lookups/, вы можете создать политику (Identity & access management > Policy management > Create policy) со следующими определениями:

ALLOW storage:files:read WHERE storage:file-path startsWith "/lookups/";


ALLOW storage:files:write WHERE storage:file-path startsWith "/lookups/";


ALLOW storage:files:delete WHERE storage:file-path startsWith "/lookups/";

В качестве другого примера, чтобы предоставить доступ только для чтения ко всем данным подстановки в /lookups/, вы можете использовать следующее определение:

ALLOW storage:files:read WHERE storage:file-path startsWith "/lookups/";

Ограничения

К хранению данных подстановки в Grail применяются следующие ограничения:

Ограничение Значение
Максимальное количество файлов на среду 100 (во время предварительного просмотра)
Максимальный размер файла 100 МБ
Максимальное количество полей 128

По завершении предварительного просмотра и снятии ограничения на максимальное количество файлов, которые могут быть сохранены в среде, использование данных подстановки в Grail может генерировать потребление Events powered by Grail.

Управление файлами подстановки

Управление файлами подстановки через REST API

Вы можете управлять файлами подстановки в Grail через Resource Store API. Dynatrace предоставляет вызовы API для:

  • Загрузки данных подстановки в Grail
  • Удаления данных подстановки из Grail
  • Тестирования разбора данных подстановки, которые вы хотите загрузить, с помощью DPL

Чтобы обновить содержимое файла, необходимо заново загрузить весь файл, перезаписав существующий.

Resource Store API использует Dynatrace Pattern Language для разбора загруженных данных и преобразования их в табличный формат хранения. Это обеспечивает полную гибкость в отношении загружаемых данных, поддерживая различные текстовые форматы, включая CSV, JSONL или XML.

Доступ к документации API

Для доступа к документации Swagger API для Resource Store API и начала выполнения API-запросов через Swagger:

  1. Найдите и выберите Dynatrace API.
  2. В поле Select a definition выберите Grail - Resource Store.
  3. Необязательно: Аутентифицируйтесь с помощью API-токена, если вы хотите использовать Swagger для выполнения запросов. Подробности см. в разделе Аутентификация. Нажмите кнопку Try it out, чтобы взаимодействовать с API непосредственно из документации.
  4. Выполните одно из следующих действий.

Разбор данных подстановки

API предоставляет эндпоинт /platform/storage/resource-store/v1/files/tabular/lookup:test-pattern, который выполняет предварительный просмотр загруженных результатов без сохранения их в виде файла в Grail. Эндпоинт помогает определить шаблон DPL, который соответствует формату ваших данных.

Эндпоинт принимает входные данные в формате multipart/form-data с частью content для загруженных данных и частью request для дополнительных параметров. Единственный обязательный параметр в части запроса — параметр parsePattern, который предоставляет шаблон DPL для разбора загруженных текстовых данных. Подробнее см. в документации Swagger API.

Вы можете определить любой шаблон DPL, соответствующий вашим данным. Каждое совпадение шаблона создаёт запись. Следующий пример показывает загруженные данные CSV в следующем формате:

Code,Category,Message


100,informational,Continue


101,informational,Switching Protocols


...

Шаблон DPL INT:code ',' LD:category ',' LD:message соответствует содержимому и создаёт запись с полями code, category и message для каждой строки, кроме строки заголовка. Вы можете использовать параметр skippedRecords для исключения строк заголовка, когда шаблон совпадает также со строками заголовка.

С теми же данными в формате JSONL вы можете использовать шаблон DPL JSON:json:

{"code": 100, "category": "informational", "message": "Continue"}


{"code": 101, "category": "informational", "message": "Switching Protocols"}


...

Если указанный шаблон DPL приводит к единственному полю типа записи, вложенные поля извлекаются на корневой уровень по умолчанию. Это поведение настраивается через параметр autoFlatten.

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

Следующий пример показывает команду curl для взаимодействия с Resource Store API с использованием токена платформы для тестирования шаблона DPL:

curl -X 'POST' \


'https://<environment>.apps.dynatrace.com/platform/storage/resource-store/v1/files/tabular/lookup:test-pattern' \


-H 'accept: */*' \


-H 'Content-Type: multipart/form-data' \


-H 'Authorization: Bearer <platformtoken>' \


-F 'request={


"parsePattern":"JSON:json",


"lookupField":"code"


}' \


-F 'content=@http_status_codes.jsonl'

Ответ включает количество записей, совпавших с шаблоном, и предварительный просмотр до 100 записей.

Сохранение данных подстановки

API предоставляет эндпоинт /platform/storage/resource-store/v1/files/tabular/lookup:upload, который позволяет загружать и сохранять данные подстановки в виде табличного файла в Grail.

Эндпоинт принимает входные данные в формате multipart/form-data с частью content для загруженных данных и частью request для дополнительных параметров. В части содержимого вы можете отправить данные в текстовом формате. Подробности см. в разделе Разбор данных подстановки. Обязательные параметры в части запроса:

  • parsePattern — для предоставления шаблона DPL для разбора загруженных данных
  • lookupField — для определения извлечённого поля с идентификатором записи
  • filePath — полный путь к табличному файлу для хранения данных подстановки в Grail

Используйте параметры displayName и description для добавления дополнительной метаинформации. Подробнее см. в документации Swagger API.

Если вы хотите обновить содержимое файла, необходимо загрузить его заново. Если filePath уже существует, используйте параметр overwrite.

Следующий пример показывает команду curl для взаимодействия с Resource Store API с использованием токена платформы для сохранения данных подстановки:

curl -X 'POST' \


'https://<environment>.apps.dynatrace.com/platform/storage/resource-store/v1/files/tabular/lookup:upload' \


-H 'accept: */*' \


-H 'Content-Type: multipart/form-data' \


-H 'Authorization: Bearer <platformtoken>' \


-F 'request={


"parsePattern":"JSON:json",


"lookupField":"code",


"filePath":"/lookups/http_status_codes",


"displayName":"My lookup data",


"description":"Description of my lookup data"


}' \


-F 'content=@http_status_codes.jsonl'

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

Вы можете использовать эндпоинт /platform/storage/resource-store/v1/files:delete для удаления файлов, которые больше не нужны. Единственный обязательный параметр — filePath, указывающий на удаляемый файл. Обратите внимание, что удаление файла необратимо.

Следующий пример показывает команду curl для взаимодействия с Resource Store API с использованием токена платформы для удаления существующего файла подстановки:

curl -X 'POST' \


'https://<environment>.apps.dynatrace.com/platform/storage/resource-store/v1/files:delete' \


-H 'accept: */*' \


-H 'Content-Type: application/json' \


-H 'Authorization: Bearer <platformtoken>' \


-d '{"filePath": "/lookups/http_status_codes"}'

Управление файлами подстановки с помощью DQL

С помощью DQL вы можете получить таблицу dt.system.files, чтобы получить список всех доступных файлов, хранящихся в Grail:

fetch dt.system.files

Если вы хотите найти определённые файлы, вы можете добавить команды search или filter к приведённому выше примеру. Подсказки автозаполнения в редакторе кода DQL также помогут вам найти ваши файлы.

Используйте команду load, если хотите просмотреть содержимое файла:

load "/lookups/http_status_codes"

Обогащение данных

Вы можете использовать команду load для получения табличных данных из файлов подстановки в DQL и комбинировать её с командами, такими как lookup или join, для добавления дополнительного контекста к данным наблюдаемости:

fetch spans


| lookup [ load "/lookups/http_status_codes" ],


    sourcefield: http.response.status_code,


    lookupField: code