Просмотр кода страницы Ruby OpenTelemetry

В этом пошаговом руководстве показано, как добавить возможность наблюдения в ваше приложение '''Ruby''' с помощью библиотек и инструментов '''OpenTelemetry''' '''Ruby'''.
{| class="wikitable"
!Особенность
!Поддержка
|-
|Автоматические инструменты
|Да
|-
|Трассировки
|Да
|-
|Метрики
|Нет
|-
|Логи
|Нет
|}

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

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

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

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

=== Получение токена доступа API ===
Токен доступа для сбора трассировок, логов и метрик можно создать в разделе [[Токен доступа|Токены доступа]].

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

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

== Инициализация OpenTelementry ==
1. Добавьте следующие зависимости в ваш '''Gemfile'''.
{| class="wikitable"
|gem 'opentelemetry-sdk'

gem 'opentelemetry-exporter-otlp'
|}
2. Добавьте следующее заявление <code>require</code>.
{| class="wikitable"
|require 'opentelemetry/sdk'

require 'opentelemetry/exporter/otlp'
|}
3. Добавьте функцию <code>init_opentelemetry</code> в стартовый код и укажите переменные <code>DT_API_URL</code> и <code>DT_API_TOKEN</code> значения для URL-адреса Ключ-АСТРОМ и токена доступа.
{| class="wikitable"
|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
|}
<u>Расширение данных Ключ-АСТРОМ</u>

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

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

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

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

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

== Автоматически инструментируйте свое приложение (необязательно) ==
1. Добавьте следующую зависимость в ваш '''Gemfile'''.
{| class="wikitable"
|gem 'opentelemetry-instrumentation-all'
|}
2. Добавьте следующее заявление <code>require</code>.
{| class="wikitable"
|require 'opentelemetry/instrumentation/all'
|}
3. Добавьте следующую строку <code>c.service_version</code> после функции <code>init_opentelemetry</code>.
{| class="wikitable"
|c.use_all
|}

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

=== Добавление трассировки ===
1. Для создания новых интервалов нам сначала нужен объект трассировки.
{| class="wikitable"
|tracer = OpenTelemetry.tracer_provider.tracer('my-tracer')
|}
2. С помощью <code>tracer</code> теперь можно <code>start_span()</code> создавать и запускать новые интервалы.
{| class="wikitable"
|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")

<nowiki>#</nowiki> 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'''».
* Добавили два атрибута, следуя [https://opentelemetry.io/docs/specs/semconv/general/trace/ семантическому соглашению об именовании], специфичные для действия этого span: информацию о методе '''HTTP''' и версии.
* Добавили <code>TODO</code> вместо конечной бизнес-логики
* Вызвали метод span <code>finish()</code> для завершения span (в блоке <code>ensure</code>, чтобы гарантировать вызов метода)

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

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

[[Файл:Image4080.png|граница]]

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

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

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

=== Обеспечение распространения контекста (необязательно) ===
Распространение контекста особенно важно, когда задействованы сетевые вызовы (например, '''REST''').

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

==== Извлечение контекста при получении запроса ====
В следующем примере используется метод распространителя по умолчанию <code>extract()</code> для извлечения и воссоздания контекста из запроса в <code>parent_context</code>. Затем мы можем передать этот контекст вызову <code>start_span</code> для продолжения предыдущей трассировки с нашими интервалами.
{| class="wikitable"
|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
|}

==== Внедрение контекста при отправке запросов ====
В следующем примере используется стандартная библиотека [https://ruby-doc.org/stdlib-2.7.0/libdoc/net/http/rdoc/Net/HTTP.html Ruby Net:HTTP] для вызова стороннего сервиса с инструментированным кодом. Для добавления необходимых заголовков трассировки мы используем метод <code>inject()</code> распространителя по умолчанию.
{| class="wikitable"
|request = Net::HTTP::Get.new(uri.request_uri)

OpenTelemetry.propagation.inject(request)

response = http.request(request)
|}

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

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

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

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

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