Ruby on Rails

В этом руководстве рассматривается интеграция:

✖️ Логи

✖️ ️️Метрики

✅ Трейсы

Чтобы отправлять логи в ClickStack, используйте OpenTelemetry Collector.

Начало работы

Установите пакеты OpenTelemetry

Выполните следующую команду, чтобы установить пакет OpenTelemetry.

bundle add opentelemetry-sdk opentelemetry-instrumentation-all opentelemetry-exporter-otlp

Настройка OpenTelemetry и форматтера логов

Далее необходимо инициализировать трассировочную инструментацию OpenTelemetry и настроить форматтер сообщений логов для логгера Rails, чтобы логи могли автоматически привязываться к трейсам. Без пользовательского форматтера логи не будут автоматически коррелироваться между собой в ClickStack.

В папке config/initializers создайте файл hyperdx.rb и добавьте в него следующее:

# config/initializers/hyperdx.rb \{#configinitializershyperdxrb}

require 'opentelemetry-exporter-otlp'
require 'opentelemetry/instrumentation/all'
require 'opentelemetry/sdk'

OpenTelemetry::SDK.configure do |c|
  c.use_all() # включает всю инструментацию трассировки
end

Rails.application.configure do
  Rails.logger = Logger.new(STDOUT)
  # Rails.logger.log_level = Logger::INFO # по умолчанию DEBUG, но в production может потребоваться INFO или выше
  Rails.logger.formatter = proc do |severity, time, progname, msg|
    span_id = OpenTelemetry::Trace.current_span.context.hex_span_id
    trace_id = OpenTelemetry::Trace.current_span.context.hex_trace_id
    if defined? OpenTelemetry::Trace.current_span.name
      operation = OpenTelemetry::Trace.current_span.name
    else
      operation = 'undefined'
    end

    { "time" => time, "level" => severity, "message" => msg, "trace_id" => trace_id, "span_id" => span_id,
      "operation" => operation }.to_json + "\n"
  end

  Rails.logger.info "Логгер инициализирован!! 🐱"
end

Настройка переменных окружения

Далее вам нужно будет настроить в вашей оболочке следующие переменные окружения для отправки телеметрии в ClickStack:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_SERVICE_NAME='<НАЗВАНИЕ_ВАШЕГО_ПРИЛОЖЕНИЯ_ИЛИ_СЕРВИСА>' \
OTEL_EXPORTER_OTLP_HEADERS='authorization=<ВАШ_API_КЛЮЧ_ПРИЁМА>'

Переменная окружения OTEL_SERVICE_NAME используется для идентификации вашего сервиса в приложении HyperDX; вы можете задать любое удобное вам имя.

Переменная окружения OTEL_EXPORTER_OTLP_HEADERS содержит ключ API, который можно получить в приложении HyperDX в разделе Team Settings → API Keys.