Elixir OpenTelemetry

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

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

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

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

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

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

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

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

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

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

Настройка OpenTelemetry

1. Добавьте текущие версии следующих зависимостей в mix.exs.

defp deps do   [     # Add any additional dependancies here     {:httpoison, version: :latest},     {:plug_cowboy, version: :latest},     {:jason, version: :latest},     {:plug, version: :latest},     {:opentelemetry_exporter, version: :latest},     {:opentelemetry_api, version: :latest},     {:opentelemetry, version: :latest}   ] end

2. Добавьте раздел release в определение приложения в mix.exs.

releases: [   <project_name>: [     version: "<project_version>",     applications: [opentelemetry_exporter: :permanent, opentelemetry: :temporary]   ] ]

3. Включите зависимости распространения контекста с помощью следующей строки в runtime.exs.

text_map_propagators: [:baggage, :trace_context],

4. Добавьте следующую конфигурацию config/runtime.exs и замените [URL] и [TOKEN] соответствующими значениями для URL-адреса Ключ-АСТРОМ и токена доступа.

import Config config :opentelemetry,   resource: [service: %{name: "elixir-quickstart", version: "1.0.1"}], #TODO Replace with the name and version of your application   span_processor: :batch,   traces_exporter: :otlp,   # Add your text map propagator from previous step here   resource_detectors: [     :otel_resource_app_env,     :otel_resource_env_var,     ExtraMetadata   ] config :opentelemetry_exporter,   otlp_protocol: :http_protobuf,   otlp_traces_endpoint: "[URL]", #TODO Replace [URL] to your SaaS/Managed URL as mentioned in the next step   otlp_traces_headers: [{"Authorization", "Api-Token [TOKEN]"}] #TODO Replace [TOKEN] with your API Token as mentioned in the next step

5. Сохраните следующий код в lib/extra_metadata.ex.

defmodule ExtraMetadata do   @behaviour :otel_resource_detector   def get_resource(_) do     metadata = read_file("/var/lib/astromkey/enrichment/dt_metadata.properties") |> unwrap_lines     file_path = read_file("dt_metadata_e617c525669e072eebe3d0f08212e8f2.properties") |> unwrap_lines     metadata2 = read_file(file_path) |> unwrap_lines     attributes = get_attributes(Enum.concat(metadata, metadata2))     metadata3 = read_file("/var/lib/astromkey/enrichment/dt_host_metadata.properties") |> unwrap_lines     attributes = get_attributes(Enum.concat(metadata, metadata2) ++ metadata3)     :otel_resource.create(attributes)   end   defp unwrap_lines({:ok, metadata}), do: metadata   defp unwrap_lines({:error, _}), do: []   defp read_file(file_name) do     try do       {:ok, String.split(File.read!(file_name), "\n")}     rescue       File.Error ->         {:error, "File does not exist, safe to continue"}     end   end   defp get_attributes(metadata) do     Enum.map(metadata, fn(line) ->       if String.length(line) > 0 do         [key, value] = String.split(line, "=")         {key, value}       else         {:error, "EOF"}       end     end)   end end

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

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

Инструментирование своего приложения

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

Спектры запускаются с помощью макроса и принимают необязательный список атрибутов, а также блок кода для этого span. Спектр автоматически завершается после возврата управления из блока кода with_span.

require OpenTelemetry.Tracer, as: Tracer def hello do   Tracer.with_span "my-span", %{attributes: [{<<"my-key-1">>, <<"my-value-1">>}]} do #TODO add attributes at span creation     Tracer.set_attributes([{"another-key-1", "another-value-1"}]) #TODO add attributes after span creation     # Your code goes here   end end

Сбор метрики

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

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

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

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

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

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

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

Чтобы извлечь информацию о существующем контексте, мы передаем заголовки функции otel_propagator_text_map.extract, которая анализирует предоставленную заголовками контекстную информацию и устанавливает текущий контекст на ее основе.

# Extract headers :otel_propagator_text_map.extract(conn.req_headers) span_ctx = OpenTelemetry.Tracer.start_span(<<"span-name">>) ctx = OpenTelemetry.Ctx.get_current() task = Task.async(fn ->     OpenTelemetry.Ctx.attach(ctx)     OpenTelemetry.Tracer.set_current_span(span_ctx)     # Do work here     OpenTelemetry.Tracer.end_span(span_ctx) end)

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

В следующем примере HTTP-заголовки otel_propagator_text_map:inject (необходимые для распространения контекста) предоставляются в merged_headers. Затем заголовки передаются в HTTPoison.get, что позволяет принимающей конечной точке продолжить трассировку с предоставленной информацией.

OpenTelemetry.Tracer.with_span "span-name" do     # ...     # do work here     # ...     headers = [{"content-type", "application/json"}, {"X-Custom-Header", "some-value"}]     merged_headers = :otel_propagator_text_map.inject(headers)     case HTTPoison.get(URL, merged_headers, []) do         {:ok, res} -> IO.puts("Response: #{inspect(res)}")         {:error, _} -> raise "request failed"     end end

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

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

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

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

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

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

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