跳到主要内容
跳到主要内容

Ruby on Rails

本指南集成了：

✖️ 日志✖️ ️️指标✅ 链路追踪

要将日志发送到 ClickStack，请通过 OpenTelemetry Collector 发送日志。

快速开始​

安装 OpenTelemetry 软件包​

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

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

配置 OpenTelemetry 和日志格式化器​

接下来，需要初始化 OpenTelemetry 的 tracing instrumentation， 并为 Rails logger 配置日志消息格式化器，以便日志可以自动与 trace 关联。 如果没有自定义格式化器，日志将无法在 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，但在生产环境中可能需要 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

配置环境变量​

接下来需要在 shell 中配置以下环境变量，用于将遥测数据发送到 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 环境变量包含可通过 HyperDX 应用的 Team Settings → API Keys 获取的 API 密钥（API Key）。