Переход с экспорта метрик Ключ-АСТРОМ OpenTelemetry на экспорт метрик OTLP
В следующих разделах описывается, как перейти с экспортера метрик Ключ-АСТРОМ OpenTelemetry (теперь устарелого) на экспортер OTLP HTTP, а также подчеркиваются их различия и способы их устранения.
Зачем переходить на HTTP-экспортер OTLP
Справка
Когда сигнал метрик OpenTelemetry был ещё нестабильным, Ключ-АСТРОМ обеспечил возможность сбора метрик OpenTelemetry, предложив собственные экспортёры метрик на нескольких языках программирования. Эти экспортёры, основанные на объединённом протоколе сбора метрик Ключ-АСТРОМ, заполнили пробел, пока компоненты OpenTelemetry стабилизировались.
С тех пор сигнал метрик OpenTelemetry был объявлен стабильным, а Ключ-АСТРОМ добавила поддержку приема собственных данных протокола OpenTelemetry (OTLP) для трассировок, метрик и логов, что сделало пользовательские экспортеры метрик Ключ-АСТРОМ более ненужными.
Преимущества перехода на официальный HTTP-экспортер OTLP:
- Вы можете отправлять метрики из всех языков программирования, поддерживаемых OpenTelemetry, что раньше было невозможно, поскольку экспортер метрик Ключ-АСТРОМ был доступен не во всех из них.
- Снижение сложности конфигурации и конвейеров OpenTelemetry Collector. Единая конфигурация HTTP-экспортера OTLP позволяет отправлять все сигналы в Ключ-АСТРОМ.
Что меняется?
Благодаря стабилизации сигнала метрик OpenTelemetry и выпуску API для сбора метрик Ключ-АСТРОМ OTLP, пользовательские экспортёры метрик Ключ-АСТРОМ устарели. Поскольку все языковые SDK предлагают экспортёр OTLP, использование экспортёра метрик Ключ-АСТРОМ OpenTelemetry больше не требуется.
Как результат:
- Экспортеры метрик Ключ-АСТРОМ OpenTelemetry устарели и больше не рекомендуются.
- Экспортеры по-прежнему доступны, но после конца 2023 года поддержка, обновления и совместимость с новыми версиями OTel осуществляться не будут.
Рекомендация
Если вы используете экспортер метрик Ключ-АСТРОМ OpenTelemetry, мы рекомендуем вам перейти на официальный экспортер OTLP HTTP, доступный в проекте OpenTelemetry.
- Если вы используете экспортер метрик Ключ-АСТРОМ OpenTelemetry в своих приложениях, инструкции см. в разделе Миграция приложений (ниже).
- Если вы используете экспортер метрик Ключ-АСТРОМ OpenTelemetry в OpenTelemetry Collector, инструкции см. в разделе Миграция конфигурации коллектора (ниже).
Получить новый URL-адрес для приема
Перед началом миграции ознакомьтесь с API сбора метрик OpenTelemetry, чтобы получить URL-адрес API сбора метрик OTLP.
Вы можете использовать тот же токен для API сбора метрик OTLP. Требуемая область действия по-прежнему — Сбор метрик (metrics.ingest).
Миграция приложений
В этом разделе описывается, как перенести приложения из экспортера метрик Ключ-АСТРОМ OpenTelemetry в экспортер HTTP OTLP.
1. Установите и настройте HTTP-экспортер OTLP
Установите пакет OTLP HTTP exporter в своё приложение. Вы можете использовать реестр OpenTelemetry для поиска пакетов.
После установки пакета экспортера ознакомьтесь с пошаговыми руководствами по интеграции OpenTelemetry, чтобы узнать, как настроить экспортер OTLP HTTP.
Теперь вы можете удалить экспортер метрик Ключ-АСТРОМ OpenTelemetry из вашего приложения.
2. Настройте конечную точку и токен
Помимо настройки конечной точки и токена непосредственно через код (как показано в примерах), экспортер OTLP также можно настроить через переменные среды.
Хотя переменные окружения одинаковы для всех языков OpenTelemetry SDK, способы их использования и настройки в SDK различаются. Чтобы узнать, как настроить экспортёр OTLP с помощью переменных окружения, обратитесь к документации SDK вашего языка программирования.
Конечная точка
- При использовании переменной среды, не зависящей от сигнала
OTEL_EXPORTER_OTLP_ENDPOINT, используйте URL-адрес API сбора метрик OTLP без суффикса/v1/metrics. - При использовании переменной среды, специфичной для метрики
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, используйте полный URL-адрес API для сбора метрик OTLP.
Токен
Токен Ключ-АСТРОМ передаётся через HTTP-заголовок Authorization. Как и конечная точка, спецификация OpenTelemetry определяет одну переменную окружения, не зависящую от сигнала OTEL_EXPORTER_OTLP_HEADERS), и одну, специфичную для метрик (OTEL_EXPORTER_OTLP_METRICS_HEADERS).
Преимущество использования переменной среды, специфичной для метрики, заключается в том, что вы изолируете токены и ограничиваете требуемую область действия конкретным сигналом.
Независимо от выбранной вами переменной окружения заголовка, вы можете задать значение, как в этом примере:
Authorization=Api-Token dt0c01.abc123.abcdefghij1234567890
Подробную информацию о настройке заголовков через переменную среды см. в документации OpenTelemetry.
Если ваш язык поддерживает настройку экспортера OTLP полностью из переменных среды (например, Java), вам также необходимо установить значение OTEL_EXPORTER_OTLP_PROTOCOL на http/protobuf, поскольку Ключ-АСТРОМ поддерживает прием данных OTLP/protobuf только через HTTP.
3. Настройте экспортер для генерации метрик delta с агрегацией временных показателей
Ключ-АСТРОМ поддерживает только прием метрик delta с агрегацией по времени.
Дополнительную информацию о темпоральности агрегации метрик и о том, как настроить экспортер OTLP для создания метрик delta, см. в разделе Темпоральность агрегации.
4. Поддержка типов атрибутов
При использовании экспортера метрик Ключ-АСТРОМ OpenTelemetry в Ключ-АСТРОМ отправляются только атрибуты типа string.
С помощью API приема метрик Ключ-АСТРОМ OTLP, помимо атрибутов string, теперь вы также можете отправлять атрибуты типа boolean и integer.
Атрибуты типа double, bytes, array, и map в настоящее время не поддерживаются Ключ-АСТРОМ и отбрасываются при приеме.
Дополнительные возможности
В следующих разделах описывается, как перенести дополнительные функции, доступные в экспортере метрик Ключ-АСТРОМ OpenTelemetry, в экспортер OTLP.
Автоматическая настройка конечной точки и токенов
При использовании экспортера метрик Ключ-АСТРОМ OpenTelemetry совместно с Ключ-АСТРОМ ЕдинымАгентом конечная точка и токен были автоматически обнаружены и настроены.
Эта функция доступна только в Ключ-АСТРОМ и недоступна в экспортере OTLP. Чтобы узнать, как настроить конечную точку и токен, см. раздел Настройка конечной точки и токена (выше).
Поддержка гистограмм
Ключ-АСТРОМ версии 1.300+
Начиная с версии Ключ-АСТРОМ 1.300, приём гистограмм поддерживается напрямую через API OTLP. Для экспоненциальной гистограммы Ключ-АСТРОМ принимает гистограммы min|max|sum|count, но не контейнеры.
Префикс метрического ключа
Автоматический префикс метрики является специфичной функцией Ключ-АСТРОМ и недоступен в экспортере OTLP.
В этом случае вам необходимо изменить определения метрик и явно добавить к ним префикс.
Если вы используете OpenTelemetry Collector, альтернативой является использование Metrics Transform Processor для добавления префикса к вашим метрикам.
Размеры по умолчанию
Хотя эта функция отсутствует в экспортере OTLP, того же результата можно добиться другими способами:
- Настройте измерения по умолчанию как атрибуты области ресурсов или инструментария. После настройки атрибутов по умолчанию для области действия ресурса и/или инструментария необходимо настроить их в Ключ-АСТРОМ, чтобы они автоматически добавлялись ко всем вашим метрикам. Подробнее см. в статье Настройка атрибутов ресурса и области действия для добавления в качестве измерений. Атрибуты области ресурсов и инструментария, которые не настроены как часть списка разрешенных в Ключ-АСТРОМ, отбрасываются при приеме.
- Настройте размеры по умолчанию с помощью переменной среды
OTEL_RESOURCE_ATTRIBUTES. - Настройте измерения по умолчанию в процессоре преобразования метрик OpenTelemetry Collector.
Автоматически обогащайте метрики с помощью метаданных ЕдиногоАгента
При использовании экспортера метрик Ключ-АСТРОМ OpenTelemetry совместно с ЕдинымАгентом метрики автоматически дополняются метаданными ЕдинымАгентом. Эта функция доступна только в Ключ-АСТРОМ и недоступна в экспортере OTLP.
Однако вы можете получить тот же результат, обратившись к метаданным ЕдиногоАгента и добавив их в качестве атрибутов ресурса.
Инструкции по обогащению поглощенных показателей с помощью специфичных для Ключ-АСТРОМ измерений см. в разделе Обогащение поглощенных данных с помощью специфичных для Ключ-АСТРОМ измерений.
Конфигурация Migrate Collector
В этом разделе описывается, как перенести конфигурацию Collector из экспортера метрик Ключ-АСТРОМ OpenTelemetry в экспортер HTTP OTLP.
1. Настройте HTTP-экспортер OTLP
Экспортер HTTP OTLP является частью основного дистрибутива OpenTelemetry Collector, поэтому нет необходимости устанавливать какие-либо дополнительные модули.
Экспортер HTTP OTLP в Collector может использоваться для отправки всех сигналов (треков, метрик и логов).
2. Настройте конечную точку и токен
Конечная точка и токен требуются при использовании HTTP-экспортера OTLP в Collector.
Конечная точка
Конечную точку можно настроить с использованием двух различных свойств:
Свойство endpoint
Свойство endpoint ссылается на базовый URL-адрес, на который будут отправлены данные. При использовании этого свойства сборщик добавит соответствующий суффикс (например, /v1/metrics) в зависимости от типа экспортируемых данных.
При использовании этого подхода используйте URL-адрес API сбора метрик OTLP без суффикса /v1/metrics.
| exporters:
otlphttp: endpoint: "https://{your-environment-id}.live.astromkey.com/api/v2/otlp" |
Свойство metrics_endpoint
Свойство metrics_endpoint относится к URL-адресу сигнала, на который будут отправляться данные. При использовании этого свойства сборщик отправляет метрики только на указанную конечную точку. Этот параметр полезен, когда конечные точки для разных сигналов различаются.
При использовании этого подхода используйте полный URL-адрес API для сбора метрик OTLP.
| exporters:
otlphttp: metrics_endpoint: "https://{your-environment-id}.live.astromkey.com/api/v2/otlp/v1/metrics" |
Если в конфигурации metrics_endpoint установлено значение endpoint, свойство игнорируется для метрик.
Токен
Токен Ключ-АСТРОМ передаётся через HTTP-заголовок Authorization. HTTP-экспортёр OTLP в коллекторе предоставляет свойство списка «ключ-значение», которое можно использовать для настройки токена Ключ-АСТРОМ:
| exporters:
otlphttp: endpoint: "https://{your-environment-id}.live.astromkey.com/api/v2/otlp" headers: Authorization: "Api-Token dt0c01.abc123.abcdefghij1234567890" |
В HTTP-экспортере OTLP в Collector можно указать только один токен API Ключ-АСТРОМ. Обязательно сгенерируйте токен со всеми необходимыми областями действия для всех экспортируемых сигналов.
Полный список доступных настроек в HTTP-экспортере OTLP см. в примере конфигурации в репозитории OpenTelemetry Collector.
3. Убедитесь, что метрики delta имеют временную агрегацию
Ключ-АСТРОМ поддерживает только прием метрик delta с агрегацией по времени.
Если ваши приложения уже создают метрики delta с временем (как описано в разделе Настройка экспортера для создания метрик delta с агрегацией времени (выше)), вам не нужно ничего делать в конфигурации вашего сборщика.
| Альтернативой является использование процессора Cumulative to Delta как части конвейера Collector.
Внимание: Для преобразования кумулятивных метрик в дельта-метрики сборщику необходимо сохранять предыдущие значения метрик. При использовании нескольких экземпляров сборщика такое преобразование может привести к несогласованности данных, если только нельзя гарантировать, что метрики из одного источника всегда обрабатываются одним и тем же экземпляром сборщика. По этой причине мы рекомендуем вам настроить экспортер OTLP в ваших приложениях для вывода метрик |
4. Поддержка типов атрибутов
При использовании экспортера метрик Ключ-АСТРОМ OpenTelemetry в Collector все атрибуты были преобразованы в string с использованием внутренней логики преобразования Collector.
Эта логика преобразовала типы атрибутов следующим образом:
boolean,integer,double: преобразованы в их строковое представлениеbytes: преобразовано в строку base64arrayиmap: преобразовано в строку JSON
Если вы записываете атрибуты типа double, bytes, array, или map при миграции в экспортер OTLP в Collector, вы должны использовать процессор атрибутов в своем конвейере, чтобы атрибуты продолжали экспортироваться в Ключ-АСТРОМ, как и раньше.
| processors:
attributes/convert: actions: - key: my.double.attribute action: convert converted_type: string - key: my.byte.attribute action: convert converted_type: string - key: my.array.attribute action: convert converted_type: string - key: my.map.attribute action: convert converted_type: string |
Атрибуты типов double, bytes, array, и map в настоящее время не поддерживаются Ключ-АСТРОМ.
Если вы записываете атрибуты этих типов и не настраиваете процессор атрибутов в конвейере Collector, эти атрибуты будут отброшены при приеме. |
Дополнительные возможности
В следующих разделах описывается, как перенести дополнительные функции, доступные в экспортере метрик Ключ-АСТРОМ OpenTelemetry, в экспортер OTLP.
Автоматическая настройка конечной точки и токена
При использовании экспортера метрик Ключ-АСТРОМ OpenTelemetry совместно с ЕдинымАгентом конечная точка и токен были автоматически обнаружены и настроены. Эта функция доступна только в Ключ-АСТРОМ и недоступна в экспортере OTLP.
См. раздел Настройка конечной точки и токена (выше), чтобы узнать, как настроить конечную точку и токен в Collector.
Поддержка гистограмм
Ключ-АСТРОМ версии 1.300+
Начиная с версии Ключ-АСТРОМ 1.300, приём гистограмм поддерживается напрямую через API OTLP. Для экспоненциальной гистограммы Ключ-АСТРОМ принимает гистограммы min|max|sum|count, но не контейнеры.
Префикс метрического ключа
Функцию префикса ключа метрики в экспортере метрик Ключ-АСТРОМ OpenTelemetry можно заменить процессором преобразования метрик в Collector с помощью функции переименовать метрику:
| # Add a prefix "myprefix" to a "system.cpu.usage" metric
include: system.cpu.usage action: update new_name: myprefix.system.cpu.usage_time |
Вы также можете переименовать несколько метрик, используя комбинацию регулярных выражений и подстановок. См. пример Переименование нескольких метрик с помощью подстановок в репозитории Collector.
Размеры по умолчанию
Функцию измерений по умолчанию в экспортере метрик Ключ-АСТРОМ OpenTelemetry можно заменить процессором преобразования метрик в Collector с помощью функции добавить метку:
| # Add a label `my.label` with value `my.value` to the 'system.cpu.usage' metric
include: system.cpu.usage action: update operations: - action: add_label new_label: my.label new_value: my.value |
Вы также можете добавить метки к нескольким метрикам, используя регулярное выражение для их выбора. См. пример Добавление метки к нескольким метрикам в репозитории Collector.
Преобразование ресурсов в телеметрию
Хотя эта функция отсутствует в экспортере OTLP, API приема метрик Ключ-АСТРОМ OTLP позволяет определить список разрешенных атрибутов области ресурсов и инструментария, которые затем автоматически добавляются в качестве измерений ко всем принимаемым метрикам.
Подробную информацию см. в разделе Настройка атрибутов ресурсов и областей для добавления в качестве измерений.
