Ruby OpenTelemetry

В этом пошаговом руководстве показано, как добавить возможность наблюдения в ваше приложение Ruby с помощью библиотек и инструментов OpenTelemetry Ruby.

Особенность	Поддержка
Автоматические инструменты	Да
Трассировки	Да
Метрики	Нет
Логи	Нет

Предустановка

• Ключ-АСТРОМ версии 1.222+
• Для трассировки включен контекст трассировки W3C.
  1. Перейдите в Настройки > Предпочтения > Функции ЕдиногоАгента.
  2. Включите опцию Отправлять HTTP-заголовки контекста трассировки W3C.

Получение данных для доступа к Ключ-АСТРОМ

Определение базового URL API

Подробную информацию о сборке базового URL-адреса конечной точки OTLP см. в разделе Экспорт с помощью OTLP. URL-адрес должен заканчиваться на /api/v2/otlp.

Получение токена доступа API

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

Экспорт с помощью OTLP содержит более подробную информацию о формате и необходимых областях доступа.

Выберите, как вы хотите инструментировать свое приложение

OpenTelemetry поддерживает на Ruby автоматическое и ручное инструментирование, а также их комбинацию.

Инициализация OpenTelementry

1. Добавьте следующие зависимости в ваш Gemfile.

gem 'opentelemetry-sdk' gem 'opentelemetry-exporter-otlp'

2. Добавьте следующее заявление require.

require 'opentelemetry/sdk' require 'opentelemetry/exporter/otlp'

3. Добавьте функцию init_opentelemetry в стартовый код и укажите переменные DT_API_URL и DT_API_TOKEN значения для URL-адреса Ключ-АСТРОМ и токена доступа.

DT_API_URL = ENV['DT_API_URL'] DT_API_TOKEN = ENV['DT_API_TOKEN'] def init_opentelemetry   OpenTelemetry::SDK.configure do |c|     c.service_name = 'ruby-quickstart' #TODO Replace with the name of your application     c.service_version = '1.0.1' #TODO Replace with the version of your application     # TODO: add automatic instrumentation here (step 3 - optional)     for name in ["dt_metadata_e617c525669e072eebe3d0f08212e8f2.properties", "/var/lib/astromkey/enrichment/dt_metadata.properties", "/var/lib/astromkey/enrichment/dt_host_metadata.properties"] do       begin         c.resource = OpenTelemetry::SDK::Resources::Resource.create(Hash[*File.read(name.start_with?("/var") ? name : File.read(name)).split(/[=\n]+/)])       rescue       end     end     c.add_span_processor(       OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(         OpenTelemetry::Exporter::OTLP::Exporter.new(           endpoint: DT_API_URL + "/v1/traces",           headers: {             "Authorization": "Api-Token " + DT_API_TOKEN           }         )       )     )   end end

Расширение данных Ключ-АСТРОМ

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

Экспорт в ЕдиныйАгент

Ruby SDK по умолчанию использует сжатие контента, которое пока не поддерживается ЕдинымАгентом.

При экспорте в ЕдиныйАгент добавьте compression: "none" в вызов Exporter.new(), чтобы отключить эту функцию. В противном случае экспортируйте в АктивныйШлюз .

4. Вызовите init_opentelemetry как можно раньше при запуске приложения, чтобы обеспечить инициализацию OpenTelemetry с самого начала.

Автоматически инструментируйте свое приложение (необязательно)

1. Добавьте следующую зависимость в ваш Gemfile.

gem 'opentelemetry-instrumentation-all'

2. Добавьте следующее заявление require.

require 'opentelemetry/instrumentation/all'

3. Добавьте следующую строку c.service_version после функции init_opentelemetry.

c.use_all

Инструментирование приложения вручную (необязательно)

Добавление трассировки

1. Для создания новых интервалов нам сначала нужен объект трассировки.

tracer = OpenTelemetry.tracer_provider.tracer('my-tracer')

2. С помощью tracer теперь можно start_span() создавать и запускать новые интервалы.

span = tracer.start_span("Call to /myendpoint", kind: :internal) OpenTelemetry::Trace.with_span(span) do |span, context|   span.set_attribute("http.method", "GET")   span.set_attribute("net.protocol.version", "1.1") # TODO your code goes here end rescue Exception => e   span&.record_exception(e)   span&.status = OpenTelemetry::Trace::Status.error("Unhandled exception of type: #{e.class}")   raise e ensure   span&.finish

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

• Создали новый span и назвали его «Call to /myendpoint».
• Добавили два атрибута, следуя семантическому соглашению об именовании, специфичные для действия этого span: информацию о методе HTTP и версии.
• Добавили TODO вместо конечной бизнес-логики
• Вызвали метод span finish() для завершения span (в блоке ensure, чтобы гарантировать вызов метода)

Логи процессов с помощью анализаторов технологических пакетов

Через OpenPipeline можно использовать и настраивать технологические пакеты. Технологический пакет — это библиотека парсеров (правил обработки), которые обрабатывают логи различных технологий, таких как Java, .NET, Microsoft IIS и т. д.

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

Сбор метрик

Примера пока нет, поскольку OpenTelemetry для Ruby пока не имеет стабильной поддержки метрик.

Подключение логов

Примера пока нет, поскольку OpenTelemetry для Ruby пока не имеет стабильной поддержки логов.

В зависимости от статуса OpenTelemetry SDK предварительная версия может уже разрешать прием ваших логов.

Обеспечение распространения контекста (необязательно)

Распространение контекста особенно важно, когда задействованы сетевые вызовы (например, REST).

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

Извлечение контекста при получении запроса

В следующем примере используется метод распространителя по умолчанию extract() для извлечения и воссоздания контекста из запроса в parent_context. Затем мы можем передать этот контекст вызову start_span для продолжения предыдущей трассировки с нашими интервалами.

parent_context = OpenTelemetry.propagation.extract(   env,   getter: OpenTelemetry::Common::Propagation.rack_env_getter ) span = tracer.start_span("hello world", with_parent: parent_context) OpenTelemetry::Trace.with_span(span) do |span, context|   span.set_attribute("my-key-1", "my-value-1")   # ... expansive query end ensure   span&.finish end

Внедрение контекста при отправке запросов

В следующем примере используется стандартная библиотека Ruby Net:HTTP для вызова стороннего сервиса с инструментированным кодом. Для добавления необходимых заголовков трассировки мы используем метод inject() распространителя по умолчанию.

request = Net::HTTP::Get.new(uri.request_uri) OpenTelemetry.propagation.inject(request) response = http.request(request)

Настройте сбор данных в соответствии с требованиями конфиденциальности (необязательно)

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

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

Проверка загрузки данных в Ключ-АСТРОМ

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

Чтобы сделать это для трассировок, перейдите в раздел Трассировки и выберите вкладку Распределенные трассировки. Если вы используете ЕдиныйАгент, выберите PurePaths .

Для просмотра метрик и логов перейдите в раздел Метрики или Логов или Логи и события.