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

> ClickStack 的 Ruby on Rails SDK - ClickHouse 可观测性栈

# Ruby on Rails

本指南支持：

<table>
  <tbody>
    <tr>
      <td className="pe-2">✖️ 日志</td>
      <td className="pe-2">✖️ ️️指标</td>
      <td className="pe-2">✅ 链路追踪</td>
    </tr>
  </tbody>
</table>

*如需将日志发送到 ClickStack，请通过 [OpenTelemetry collector](/zh/clickstack/ingesting-data/collector) 发送。*

<div id="getting-started">
  ## 快速开始
</div>

<div id="install-otel-packages">
  ### 安装 OpenTelemetry 软件包
</div>

使用以下命令安装 OpenTelemetry 软件包。

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

<div id="configure-otel-logger-formatter">
  ### 配置 OpenTelemetry + 日志记录器格式化器
</div>

接下来，你需要初始化 OpenTelemetry 链路追踪插桩，
并为 Rails logger 配置日志消息格式化器，以便日志能够
自动关联到 trace。如果没有这个自定义格式化器，日志将无法
在 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() # 启用所有 trace 插桩！
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
```

<div id="configure-environment-variables">
  ### 配置环境变量
</div>

接下来，你需要在 shell 中配置以下环境变量，以便通过 OpenTelemetry Collector 将遥测数据发送到 ClickStack：

<Tabs>
  <Tab title="托管 ClickStack">
    ```shell theme={null}
    export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
    ```
  </Tab>

  <Tab title="ClickStack 开源版">
    ```shell theme={null}
    export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
    OTEL_EXPORTER_OTLP_HEADERS='authorization=<YOUR_INGESTION_API_KEY>'
    ```
  </Tab>
</Tabs>

*`OTEL_SERVICE_NAME` 环境变量用于在 HyperDX 应用中标识你的服务，
你可以将它设置为任意名称。*

`OTEL_EXPORTER_OTLP_HEADERS` 环境变量包含 API Key，可在 HyperDX 应用的 `Team Settings → API Keys` 中获取。