Отправка метрик Micrometer в Ключ-АСТРОМ

Micrometer — это фреймворк с открытым исходным кодом для сбора метрик приложений на базе JVM. Он используется Spring Boot для записи широкого спектра метрик. Вы можете собирать метрики Micrometer и Spring Boot и анализировать их с помощью Ключ-АСТРОМ ИИ от начала до конца в контексте ваших данных трассировки, логов и диагностики. С Ключ-АСТРОМ вы получаете интеллектуальную наблюдаемость на основе ИИ и автоматический анализ первопричин для Spring Boot, более 15 предварительно инструментированных фреймворков и серверов на базе JVM, а также пользовательские метрики.

С помощью программы Micrometer в Ключ-АСТРОМ можно:

• Получайте предварительно настроенные метрики из приложений Spring Boot.
• Получайте предварительно настроенные метрики из JVM-фреймворков, серверов и систем кэширования.
• Определяйте и используйте пользовательские метрики.

Метрики, получаемые из Micrometer, используют DDU для обработки пользовательских метрик.

Micrometer можно использовать двумя способами:

• В рамках Spring Boot
• В качестве интерфейса для сбора метрик, используемого непосредственно в вашем коде

Предварительные требования

• Micrometer версии 1.8.0+
• Необязательно Spring Boot версии 2.6.0+
• Необходимо добавить зависимость от реестра в ваш проект:

Micrometer standalone	Spring Boot
Gradle implementation 'io.micrometer:micrometer-registry-astromkey:latest.release'	Gradle implementation 'io.micrometer:micrometer-registry-astromkey'
Maven Замените {micrometer.version} на последнюю версию Micrometer или на конкретную версию, которую вы хотите использовать. Список выпущенных версий доступен на Maven Central. Мы рекомендуем использовать последнюю версию. <dependency>   <groupId>io.micrometer</groupId>   <artifactId>micrometer-registry-astromkey</artifactId>   <version>{micrometer.version}</version> </dependency>	Maven <dependency>   <groupId>io.micrometer</groupId>   <artifactId>micrometer-registry-astromkey</artifactId> </dependency>

В BOM Spring Boot указывается версия Micrometer, протестированная с соответствующей версией Spring Boot. Поэтому достаточно указать имя зависимости, не указывая версию. Это приведет к тому, что Gradle или Maven подхватят правильную, соответствующую версию.

Каналы приема

Для отправки метрик Micrometer можно использовать один из следующих каналов приема:

• API метрик ЕдиногоАгента — требуется установленный на отслеживаемом хосте ЕдиныйАгент.
• API метрик v2.

Ключ-АСТРОМ Micrometer registry

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

• Для Micrometer версии 1.8.0 и более поздних версий доступен Ключ-АСТРОМ Registry v2. Он экспортирует метрики через Metrics API v2. Все новые интеграции Micrometer и Ключ-АСТРОМ должны использовать эту версию.
• Для Micrometer версии 1.8.0 и более ранних версий доступен устаревший реестр Ключ-АСТРОМ Micrometer v1.

Получение метрик из приложений Spring Boot

Микрометр можно настроить с помощью файла .properties конфигурации .yaml, используемого для Spring Boot. Spring Boot автоматически связывает свойства с префиксом management.astromkey.metrics.export с объектом конфигурации Ключ-АСТРОМ.

Всю настройку следует производить через файлы свойств. Создание Micrometer MeterRegistry вручную нарушает автоматическую настройку.

В версии Spring Boot 3.0.0 изменились названия свойств атрибутов привязки. Если вы используете версию Spring Boot до 3.0.0, используйте management.metrics.export.astromkey вместо management.astromkey.metrics.export.

С помощью ЕдиногоАгента (рекомендуется)	С помощью Ключ-АСТРОМ Operator для Kubernetes	Без ЕдиногоАгента
Для хостов, отслеживаемых ЕдинымАгентом, доступна автоматическая настройка. Вам не нужно указывать конечную точку API для получения метрики — если параметр uri не задан в конфигурации, метрика будет получена через API метрик ЕдиногоАгента.	Ключ-АСТРОМ Operator настраивает реестр Ключ-АСТРОМ Micrometer, предоставляя URL-адрес для приема данных, учетные данные и метаданные Kubernetes. Примеры настройки см. в наших примерах для Dynakube. Эта функция доступна при использовании версий реестра Ключ-АСТРОМ Micrometer 1.9.0 и выше. Приложение, использующее реестр Ключ-АСТРОМ Micrometer и работающее в Kubernetes с Ключ-АСТРОМ Operator, не требует какой-либо явной настройки. Ключ-АСТРОМ Operator и реестр будут работать вместе и автоматически экспортировать метрики Micrometer в Ключ-АСТРОМ. Явное указание параметра management.astromkey.metrics.export.uri приведет к перезаписи автоматической конфигурации и должно быть исключено при использовании с Ключ-АСТРОМ Operator.	Для получения метрик с хостов, где ЕдиныйАгент не установлен, например, из бессерверных развертываний (например, AWS ECS) или других сред, не использующих Kubernetes, необходимо использовать конечную точку приема метрик API v2. Чтобы узнать, как использовать эту конечную точку, см. пример отправки данных методом POST. Реестр Micrometer Ключ-АСТРОМ экспортирует данные в этот API, если указаны URI и токен. Убедитесь, что URI задан явно, поскольку, если он не задан, по умолчанию будет использоваться значение localhost, а локальный прием данных ЕдиногоАгента недоступен в этих средах.
YAML management.astromkey.metrics.export:   v2:     metric-key-prefix: "service.component"     enrich-with-astromkey-metadata: true     default-dimensions:       stack: "prod"       region: "us-east-1"		YAML management.astromkey.metrics.export:   uri: "https://mySampleEnv.live.astromkey.com/api/v2/metrics/ingest"   # Read the environment variable YOUR_METRICS_INGEST_API_TOKEN and supply the value of the env var instead.   api-token: ${YOUR_METRICS_INGEST_API_TOKEN}   v2:     metric-key-prefix: "service.component"     enrich-with-astromkey-metadata: true     default-dimensions:       stack: "prod"       region: "us-east-1"
.properties management.astromkey.metrics.export.v2.metric-key-prefix=service.component management.astromkey.metrics.export.v2.enrich-with-astromkey-metadata=true management.astromkey.metrics.export.v2.default-dimensions.stack=prod management.astromkey.metrics.export.v2.default-dimensions.region=us-east-1		.properties management.astromkey.metrics.export.uri=https://mySampleEnv.live.astromkey.com/api/v2/metrics/ingest management.astromkey.metrics.export.api-token=${YOUR_METRICS_INGEST_API_TOKEN} management.astromkey.metrics.export.v2.metric-key-prefix=service.component management.astromkey.metrics.export.v2.enrich-with-astromkey-metadata=true management.astromkey.metrics.export.v2.default-dimensions.stack=prod management.astromkey.metrics.export.v2.default-dimensions.region=us-east-1

Получение метрик напрямую из Micrometer

С помощью ЕдиногоАгента (рекомендуется)	С помощью Ключ-АСТРОМ Operator для Kubernetes	Без ЕдиногоАгента
Для хостов, отслеживаемых ЕдинымАгентом, доступна автоматическая настройка. Вам не нужно указывать конечную точку API для получения метрики — если параметр uri не задан в конфигурации, метрика будет получена через API метрик ЕдиногоАгента.	Ключ-АСТРОМ Operator настраивает реестр Ключ-АСТРОМ Micrometer, предоставляя URL-адрес для приема данных, учетные данные и метаданные Kubernetes. Примеры настройки см. в наших примерах для Dynakube. Эта функция доступна при использовании версий реестра Ключ-АСТРОМ Micrometer 1.9.0 и выше. Приложение, использующее реестр Ключ-АСТРОМ Micrometer и работающее в Kubernetes с Ключ-АСТРОМ Operator, не требует какой-либо явной настройки. Ключ-АСТРОМ Operator и реестр будут работать вместе и автоматически экспортировать метрики Micrometer в Ключ-АСТРОМ. Явное указание параметра management.astromkey.metrics.export.uri приведет к перезаписи автоматической конфигурации и должно быть исключено при использовании с Ключ-АСТРОМ Operator.	Для получения метрик с хостов, где ЕдиныйАгент не установлен, например, из бессерверных развертываний (например, AWS ECS) или других сред, не использующих Kubernetes, необходимо использовать конечную точку приема метрик API v2. Чтобы узнать, как использовать эту конечную точку, см. пример отправки данных методом POST. Реестр Micrometer Ключ-АСТРОМ экспортирует данные в этот API, если указаны URI и токен. Убедитесь, что URI задан явно, поскольку, если он не задан, по умолчанию будет использоваться значение localhost, а локальный прием данных ЕдиногоАгента недоступен в этих средах.
View auto-configuration code astromkeyConfig astromkeyConfig = new astromkeyConfig() {     @Override     @Nullable     public String get(String k) {         // This method can be used for retrieving arbitrary config items;         // null means accepting the defaults defined in astromkeyConfig         return null;     } }; astromkeyMeterRegistry registry = astromkeyMeterRegistry.builder(config).build();		View auto-configuration code astromkeyConfig astromkeyConfig = new astromkeyConfig() {     @Override     public astromkeyApiVersion apiVersion() {         // Not strictly required, but makes the code more clear/explicit         return astromkeyApiVersion.V2;     }     @Override     public String uri() {         // The endpoint of the astromkey Metrics API v2 including path:         // "https://{your-environment-id}.live.astromkey.com/api/v2/metrics/ingest"         String endpoint = System.getenv("YOUR_METRICS_INGEST_URL");         return endpoint != null ? endpoint : astromkeyConfig.super.uri();     }     @Override     public String apiToken() {         // Should be read from a secure source         String token = System.getenv("YOUR_METRICS_INGEST_TOKEN");         return token != null ? token : "";     }     @Override     @Nullable     public String get(String k) {         // This method can be used for retrieving arbitrary config items;         // null means accepting the defaults defined in astromkeyConfig         return null;     } }; astromkeyMeterRegistry registry = astromkeyMeterRegistry.builder(astromkeyConfig).build();

Проверка метрик

После отправки метрик проверьте данные в Data Explorer.

Свойства конфигурации

Для настройки реестра Ключ-АСТРОМ Micrometer можно использовать объект конфигурации Ключ-АСТРОМ (astromkeyConfig). Этот объект содержит параметры приема метрик и используется для создания реестра Ключ-АСТРОМ (astromkeyMeterRegistry), который регистрируется в Micrometer для приема метрик в Ключ-АСТРОМ. Вы можете установить следующие параметры:

Spring Boot

При использовании Spring Boot записи application.properties в ваших файлах application.yaml будут автоматически сопоставлены с объектом astromkeyConfig.

Свойство	Описание	Необходимость
api-version	Версия API Ключ-АСТРОМ, используемая для загрузки данных в Ключ-АСТРОМ: V2 (по умолчанию): API метрик v2 V1 API временных рядов v1	Необязательно
uri	Конечная точка приема данных API.	Необязательно
metric-key-prefix	Префикс, который будет добавлен ко всем принимаемым ключам метрик (например, пространство имен).	Необязательно
enrich-with-astromkey-metadata	Обогащать (true) или не обогащать (false) полученные метрики дополнительными метаданными. Если не указано, используется true.	Необязательно
default-dimensions	Список параметров, которые будут добавлены к полученным метрикам. Измерения определяются как пары ключ-значение.	Необязательно
use-astromkey-summary-instruments	Micrometer версий 1.9.x+ Игнорируйте реализацию, специфичную для Ключ-АСТРОМ, для сводных инструментов (Timer и DistributionSummary). По умолчанию (true) используется новый Instruments. Используйте false, чтобы вернуться к поведению версии 1.8.x.	Необязательно
export-meter-metadata	Micrometer версий 1.12.x+ Включите или выключите экспорт метаданных счетчика (единица измерения и описание). Параметр по умолчанию (true) настраивает реестр на экспорт метаданных счетчика. Используйте этот параметр false, чтобы отключить экспорт метаданных.	Необязательно

Micrometer

Свойство	Описание	Необходимость
apiVersion	Версия API Ключ-АСТРОМ, используемая для загрузки данных в Ключ-АСТРОМ: V2 (по умолчанию): API метрик v2 V1 API временных рядов v1	Необязательно
uri	Конечная точка приема данных API.	Необязательно
metricKeyPrefix	Префикс, который будет добавлен ко всем принимаемым ключам метрик (например, пространство имен).	Необязательно
enrichWithastromkeyMetadata	Обогащать (true) или не обогащать (false) полученные метрики дополнительными метаданными. Если не указано, используется true.	Необязательно
defaultDimensions	Список параметров, которые будут добавлены к полученным метрикам. Измерения определяются как пары ключ-значение.	Необязательно
useastromkeySummaryInstruments	Micrometer версий 1.9.x+ Игнорируйте реализацию, специфичную для Ключ-АСТРОМ, для сводных инструментов (Timer и DistributionSummary). По умолчанию (true) используется новый Instruments. Используйте false, чтобы вернуться к поведению версии 1.8.x.	Необязательно
exportMeterMetadata	Micrometer версий 1.12.x+ Включите или выключите экспорт метаданных счетчика (единица измерения и описание). Параметр по умолчанию (true) настраивает реестр на экспорт метаданных счетчика. Используйте этот параметр false, чтобы отключить экспорт метаданных.	Необязательно

Фрагмент кода для установки свойств

astromkeyConfig astromkeyConfig = new astromkeyConfig() {     @Override     public astromkeyApiVersion apiVersion() {         // Defaults to V2 if not set explicitly.         return astromkeyApiVersion.V2;     }     @Override     public String uri() {         // The endpoint of the astromkey Metrics API v2 including path. For example:         // "https://{your-environment-id}.live.astromkey.com/api/v2/metrics/ingest".         String endpoint = System.getenv("YOUR_METRICS_INGEST_URL");         return endpoint != null ? endpoint : astromkeyConfig.super.uri();     }     @Override     public String apiToken() {         // Should be read from a secure source         String token = System.getenv("YOUR_METRICS_INGEST_API_TOKEN");         return token != null ? token : "";     }     @Override     public String metricKeyPrefix() {         // Will be prepended to all metric keys         return "service.component";     }     @Override     public boolean enrichWithastromkeyMetadata() {         // On by default, but can be turned off explicitly.         return true;     }     @Override     public Map<String, String> defaultDimensions() {         // Create and return a map containing the desired key-value pairs.         Map<String, String> dims = new HashMap<>();         dims.put("dimensionKey", "dimensionValue");         return dims;     }     // Only available in Micrometer 1.9.0 and above.     @Override     public boolean useastromkeySummaryInstruments() {         return false;     }     // Only available in Micrometer 1.12.0 and above.     @Override     public boolean exportMeterMetadata() {         return false;     }     @Override     @Nullable     public String get(String k) {         return null; // Accept the rest of the defaults     } };

Дополнительная информация

Типы метрик

Все метрики преобразуются в соответствии с протоколами приема метрик, используемыми Ключ-АСТРОМ.

Инструменты Micrometer	Тип метрик Ключ-АСТРОМ
Gauge	gauge,X
Counter	count,delta=X
Timer	gauge,min=X,max=Y,sum=Z,count=N
DistributionSummary	gauge,min=X,max=Y,sum=Z,count=N
LongTaskTimer	gauge,min=X,max=Y,sum=Z,count=N
TimeGauge	gauge,X
FunctionCounter	count,delta=X
FunctionTimer	gauge,min=X,max=Y,sum=Z,count=N

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

Meter методанные

Начиная с версии 1.12.0 реестра Micrometer Ключ-АСТРОМ, метаданные Meter (единица измерения и описание) автоматически экспортируются в Ключ-АСТРОМ. Для начала экспорта метаданных не требуется никаких изменений в коде. Чтобы отключить экспорт метаданных, используйте следующую конфигурацию:

Spring Boot	Micrometer
YAML management:   metrics:     export:       astromkey:         v2:           export-meter-metadata: false  # default: true	Фрагмент кода для установки свойств astromkeyConfig astromkeyConfig = new astromkeyConfig() {     // Only available in Micrometer 1.12.0 and above.     @Override     public boolean exportMeterMetadata() {         return false;     }     @Override     @Nullable     public String get(String k) {         return null; // Accept the rest of the defaults     } };
.properties management.astromkey.metrics.export.v2.export-meter-metadata=false

Для предыдущих версий Micrometer метаданные необходимо указывать вручную с помощью API Ключ-АСТРОМ или веб-интерфейса. Дополнительную информацию см. в разделе Настройка метаданных метрик.

Отправка метрик из Kubernetes

ЕдиныйАгент нельзя использовать для приема метрик Micrometer на узлах Kubernetes. Вы можете настроить Micrometer таким образом, чтобы он напрямую отправлял метрики в Ключ-АСТРОМ с помощью API метрик.

Сбор метрик JVM в Micrometer

По умолчанию метрики JVM отключены при запуске Micrometer без Spring Boot. Чтобы узнать, как их включить, см. документацию Micrometer. После включения и регистрации в реестре Ключ-АСТРОМ (astromkeyMeterRegistry), метрики JVM записываются и автоматически отправляются в Ключ-АСТРОМ.

На хостах, отслеживаемых ЕдинымАгентом, эти метрики могут уже собираться ЕдинымАгентом.

Ограничение сбора определенных метрик

Spring Boot

При запуске Micrometer в Spring Boot автоматически создается и отправляется в Ключ-АСТРОМ множество метрик, включая метрики JVM, процессов и дисков.

Чтобы просмотреть все метрики, созданные вашим приложением Spring Boot, перейдите к конечной точке Actuator в вашем приложении Spring Boot (/actuator/metrics). Некоторые из этих метрик могут уже собираться ЕдинымАгентом.

Отключение метрик с помощью свойств Spring

Метрики можно отключить на основе их префикса в конфигурации Spring Boot. Чтобы узнать, какие метрики можно исключить, проверьте конечную точку Actuator вашего приложения Spring Boot. Обязательно исключите префикс ключа вашей пользовательской метрики (если таковой имеется, см. metric-key-prefix) при использовании этой функции.

YAML management.metrics.enable:   # disable jvm.memory metrics   jvm.memory: false   # disable all jvm metrics:   jvm: false

.properties # disable jvm.memory metrics management.metrics.enable.jvm.memory=false # disable all jvm metrics management.metrics.enable.jvm=false

Также можно сначала отключить все метрики, а затем включить только нужные:

YAML management.metrics.enable:   # disable all metrics   all: false   # re-enable only jvm.* metrics   jvm: true

.properties # disable all metrics management.metrics.enable.all=false # re-enable jvm.* metrics management.metrics.enable.jvm=true

Отключение метрик в коде

Micrometer предоставляет фильтры для отключения метрик на основе различных условий. Фильтры также можно настроить через Spring Boot с помощью аннотации @Configuration.

@Configuration(proxyBeanMethods = false) public class MyMeterRegistryConfiguration {     @Bean     public MeterRegistryCustomizer<MeterRegistry> metricsCommonTags() {         return registry -> registry.config()             .meterFilter(MeterFilter.denyNameStartsWith("jvm.gc"));     } }

После фильтрации будет применен префикс метрик, настроенный для реестра Ключ-АСТРОМ, поэтому для включения или отключения метрик необходимо указывать исходный ключ метрики без этого префикса.

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

Micrometer

Вы можете настроить реестр для фильтрации определенных метрик по имени и/или тегам (например, метрик, которые уже собираются ЕдинымАгентом). Для этого используйте фильтры Meter Micrometer. Необходимо добавить фильтры meter до включения сбора метрик JVM, иначе фильтры будут переопределены.

Префикс метрики, настроенный для реестра Ключ-АСТРОМ, будет применяться после фильтрации, поэтому meterFilters необходимо указать, используя исходный ключ метрики без этого префикса.

Отключение метрик в коде // Disable all metrics with metric names starting with jvm.gc registry.config()     .meterFilter(MeterFilter.denyNameStartsWith("jvm.gc"));

Поиск и устранение неисправностей с помощью логов событий

Spring Boot

При использовании Micrometer в контексте Spring Boot управление логированием осуществляется Spring. Уровень логирования для реестра Micrometer Ключ-АСТРОМ можно установить с помощью параметров конфигурации.

YAML logging.level.io.micrometer.astromkey: DEBUG

.properties logging.level.io.micrometer.astromkey=DEBUG

Micrometer

Micrometer и реестр Ключ-АСТРОМ Micrometer используют slf4j для внутренней регистрации событий, таких как строки, отправляемые в Ключ-АСТРОМ. Если вы хотите получить эту информацию, настройте свой проект с использованием выбранной вами системы логирования (например, logback) и установите уровень логирования на debug.

Отладочное логирование с использованием logback При использовании стандартной реализации Logback отладочная информация в консоль включена по умолчанию. Чтобы добавить Logback в ваш проект и записывать отладочную информацию, добавьте следующую зависимость: implementation 'ch.qos.logback:logback-classic:latest.release'

Сводные данные по инструментам Ключ-АСТРОМ

Начиная с версии Micrometer 1.9.x, в реестре метрик Ключ-АСТРОМ используются специализированные инструменты для некоторых сводных инструментов (astromkeyTimer и astromkeyDistributionSummary). Их цель — обойти особенность в способе записи метрик в Micrometer, которая в некоторых случаях приводила к отклонению метрик Ключ-АСТРОМ из-за недопустимого формата. Специализированные инструменты, адаптированные для приема метрик Ключ-АСТРОМ, предотвращают создание недопустимых метрик.

• Они доступны начиная с версии 1.9.0 и по умолчанию используются в качестве полной замены. Пользователям, обновляющим версию до 1.9.0, никаких действий не требуется.
• Если наблюдается расхождение в показателях, можно вернуться к предыдущему поведению, установив флаг useastromkeySummaryInstruments в положение false.