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

> Ruby on Rails SDK for ClickStack - The ClickHouse Observability Stack

# Ruby on Rails

This guide integrates:

<table>
  <tbody>
    <tr>
      <td className="pe-2">✖️ Logs</td>
      <td className="pe-2">✖️ ️️Metrics</td>
      <td className="pe-2">✅ Traces</td>
    </tr>
  </tbody>
</table>

*To send logs to ClickStack, please send logs via the [OpenTelemetry collector](/clickstack/ingesting-data/collector).*

<h2 id="getting-started">
  Getting started
</h2>

<h3 id="install-otel-packages">
  Install OpenTelemetry packages
</h3>

Use the following command to install the OpenTelemetry package.

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

<h3 id="configure-otel-logger-formatter">
  Configure OpenTelemetry + logger formatter
</h3>

Next, you'll need to initialize the OpenTelemetry tracing instrumentation
and configure the log message formatter for Rails logger so that logs can be
tied back to traces automatically. Without the custom formatter, logs won't
be automatically correlated together in ClickStack.

In `config/initializers` folder, create a file called `hyperdx.rb` and add the
following to it:

```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() # enables all trace instrumentation!
end

Rails.application.configure do
  Rails.logger = Logger.new(STDOUT)
  # Rails.logger.log_level = Logger::INFO # default is DEBUG, but you might want INFO or above in production
  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">
  Configure environment variables
</h3>

Afterwards you'll need to configure the following environment variables in your shell to ship telemetry to ClickStack via the OpenTelemetry collector:

<Tabs>
  <Tab title="Managed 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 Open Source">
    ```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>

*The `OTEL_SERVICE_NAME` environment variable is used to identify your service
in the HyperDX app, it can be any name you want.*

The `OTEL_EXPORTER_OTLP_HEADERS` environment variable contains the API Key available via HyperDX app in `Team Settings → API Keys`.