> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> SDK ClickStack для Ruby on Rails — стек обсервабилити ClickHouse

# Ruby on Rails

export const ClickStackIntegrates = ({signals = []}) => {
  const list = Array.isArray(signals) ? signals : String(signals).split(",");
  const supported = list.map(s => String(s).trim().toLowerCase());
  const pillStyle = {
    display: "inline-flex",
    alignItems: "center",
    padding: "0.125rem 0.625rem",
    borderRadius: "9999px",
    fontSize: "0.8125rem",
    fontWeight: 500,
    lineHeight: 1.6,
    color: "#161517",
    backgroundColor: "#faff69",
    border: "1px solid rgba(0, 0, 0, .1)",
    marginRight: "0.5rem"
  };
  return <div style={{
    margin: "0 0 1.25rem"
  }}>
      <span style={{
    marginRight: "0.5rem"
  }}>Это руководство поддерживает:</span>
      {supported.includes("logs") && <span style={pillStyle}>Журналы</span>}
      {supported.includes("metrics") && <span style={pillStyle}>Метрики</span>}
      {supported.includes("traces") && <span style={pillStyle}>Трассировки</span>}
    </div>;
};

<ClickStackIntegrates signals={['traces']} />

*Чтобы отправлять журналы в ClickStack, используйте [OpenTelemetry Collector](/ru/clickstack/ingesting-data/collector).*

<h2 id="getting-started">
  Начало работы
</h2>

<h3 id="install-otel-packages">
  Установка пакетов OpenTelemetry
</h3>

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

```shell theme={null}
bundle add opentelemetry-sdk opentelemetry-instrumentation-all opentelemetry-exporter-otlp
```

<h3 id="configure-otel-logger-formatter">
  Настройте OpenTelemetry + форматтер логгера
</h3>

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

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

```ruby theme={null}
# config/initializers/hyperdx.rb

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, но в продакшене может потребоваться 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 "Logger initialized !! 🐱"
end
```

<h3 id="configure-environment-variables">
  Настройте переменные окружения
</h3>

После этого вам нужно задать в командной оболочке следующие переменные окружения, чтобы отправлять телеметрию в ClickStack через OpenTelemetry Collector:

<Tabs>
  <Tab title="Управляемый ClickStack">
    ```shell theme={null}
    export OTEL_EXPORTER_OTLP_ENDPOINT=<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT> \
    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' \
    ```
  </Tab>

  <Tab title="ClickStack с открытым исходным кодом">
    ```shell theme={null}
    export OTEL_EXPORTER_OTLP_ENDPOINT=<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT> \
    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' \
    OTEL_EXPORTER_OTLP_HEADERS='authorization=<YOUR_INGESTION_API_KEY>'
    ```
  </Tab>
</Tabs>

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

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