跳转到内容
集成指南

Ruby on Rails 结构化事件分析

通过 Telemetry HTTP API 记录 Rails 控制器请求的观测值,不改变应用结果。

审阅者 Telemetry产品团队 上 . 我们检查了要发送的事件、要排除的数据和代码添加方法. 谁负责审核此页面

有用于
  • Rails 请求监控
实施证据

使用 Ruby on Rails structured event analytics 发送并验证事件

在受控应用程序边界使用 Ruby on Rails structured event analytics,保持事件契约较小,并在构建聚合视图之前验证已知结果。

  1. 1

    选择结果

    Rails 请求监控

  2. 2

    定义合同

    controller_action、method 和观测到的 status_code

  3. 3

    在结果处发出

    此订阅者观测 process_action.action_controller,不会为 Active Job、静态文件、仅经中间件处理的响应或整个 Rack 请求插桩。

  4. 4

    核实证据

    Exercise a known fixture, then inspect api_request_completed for one correctly typed terminal row.

开始之前

开始之前

  • 具有写入权限的服务端 TELEMETRY_API_KEY
  • 将此示例放入 config/initializers/telemetry_requests.rb,每个进程注册一次
  • 提供 ActiveSupport::Notifications.monotonic_subscribe 的 Rails

交货设置

安装并初始化服务器端

使用带有服务器端密钥以及显式打开和读取超时的小型 Net::HTTP 包装器。 将摄取凭据保留在浏览器包、客户端可见的环境变量、源代码控制、日志和异常消息之外。

  1. 1准备一个具有有限网络行为的可重用服务器端交付客户端。
  2. 2在成功、失败、重试或超时边界处添加结果事件。
  3. 3在启用警报之前发送受控装置并检查存储的行。

片段

从一个结构化事件开始

在工作流程完成、失败或重试的位置添加此形状。然后从真实的字段构建仪表板。

ruby-rails

Ruby on Rails structured event analytics事件

ruby
# config/initializers/telemetry_requests.rb
require "json"
require "net/http"
require "uri"

module TelemetryRailsRequests
  def self.delivery_failed
    warn "Telemetry request event delivery failed."
  rescue StandardError
    # Diagnostics must not change the application result either.
  end

  def self.log(fields)
    key = ENV["TELEMETRY_API_KEY"]
    return if key.nil? || key.empty?

    uri = URI("https://api.telemetry.sh/log")
    request = Net::HTTP::Post.new(uri)
    request["Authorization"] = key
    request["Content-Type"] = "application/json"
    request.body = { table: "api_request_completed", data: fields }.to_json

    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.open_timeout = 1
    http.read_timeout = 1
    http.write_timeout = 1
    http.max_retries = 0
    response = http.start { |client| client.request(request) }
    delivery_failed unless response.is_a?(Net::HTTPSuccess)
  rescue StandardError
    delivery_failed
  end
end

ActiveSupport::Notifications.monotonic_subscribe(
  "process_action.action_controller"
) do |_name, started, finished, _id, payload|
  status = payload[:status]
  status = nil unless status.is_a?(Integer) && (100..599).cover?(status)

  TelemetryRailsRequests.log({
    controller_action: "#{payload[:controller]}##{payload[:action]}",
    method: payload[:method],
    status_code: status,
    status: status ? "http_#{status / 100}xx" : "unknown",
    exception_observed: !!payload[:exception],
    latency_ms: ((finished - started) * 1000).round(2)
  })
rescue StandardError
  TelemetryRailsRequests.delivery_failed
end

事件结构

controller_action、method 和观测到的 status_code

HTTP 状态类别、exception_observed 和控制器 latency_ms

不包含请求参数、原始路径、请求头、用户标识符或异常消息

检查配置

检查站 1

此订阅者观测 process_action.action_controller,不会为 Active Job、静态文件、仅经中间件处理的响应或整个 Rack 请求插桩。

检查站 2

HTTP 状态类别描述观测到的控制器响应,不代表业务成功或已送达用户。缺失的状态保留为未知。

检查站 3

延迟采用控制器通知的单调时钟间隔,不包含此订阅者的 HTTP 导出时间。

检查站 4

导出同步执行且尽力而为,连接、读取和写入超时均为一秒。这些套接字超时并非严格的总时限;发送会增加请求延迟。

检查站 5

传输、非 2xx 响应、编码和诊断失败均被隔离,不替换控制器结果或原始异常。缺少密钥时跳过导出。

检查站 6

此示例没有队列、持久投递、导出重试或关闭时排空机制。若不能接受事件丢失,请使用应用自行管理的发件箱。

验证

证明事件已到达

在演练已知的成功和失败案例后运行此命令。如果您的最终事件契约与代码片段不同,请替换后备表名称。

ruby-rails-验证

Ruby on Rails structured event analytics 验证查询

sql
SELECT *
FROM api_request_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
确认每个逻辑结果的一个终端行,以及预期状态、标识符、单位和 UTC 时间。
检查推断的架构并验证重试不会更改字段类型或生成新的逻辑事件 ID。
在存储的字段中搜索凭据、原始有效负载、提示、私有内容和无限制的错误消息。
在将仪表板视为完整之前,请执行提供程序超时、摄取拒绝和进程关闭。

实施参考

在启用新的生产路径之前,请检查事件合同、数据安全指南和上游主要文档。

在哪里记录事件

保持结果事件小且可恢复

该模式提供了

  • 除了上游工作流程之外,还有一个有界的、SQL 就绪的结果。
  • 用于仪表板、警报和跨事件关联的稳定字段。
  • 用于验证成功、失败、重试和超时行为的夹具驱动路径。

该模式不提供

  • OTLP 导出器、自动收集管道或详细跟踪和诊断日志的替代品。
  • 仅因为有效负载包含事件 ID,所以仅传送一次。
  • 收集原始提供商有效负载、用户内容、凭证或受监管数据的权限。

事件模式示例

在将查询或代码片段适应生产之前,请检查行粒度、发出边界、所需类型、隐私类、示例有效负载和验证清单。

相关产品功能

继续此工作流程 仪表板

将经过验证的产品或收入查询转变为集中的决策界面。

相关 SQL 查询示例

更多 SQL 示例

针对此工作流程中的结构化字段运行查询,检查示例结果,并将有用的答案转换为仪表板或警报。

浏览所有查询示例

与此集成配对的模板

更多集成