本文へ移動
統合ガイド

Rails の Ruby 構造化イベント分析

アプリケーションの結果を変えずに、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制限されたネットワーク動作を持つ再利用可能なサーバー側配信クライアントを 1 つ準備します。
  2. 2成功、失敗、再試行、またはタイムアウトの境界に結果イベントを追加します。
  3. 3アラートを有効にする前に、制御されたフィクスチャを送信し、保存されている行を検査します。

スニペット

1 つの構造化されたイベントから始める

ワークフローが完了、失敗、または再試行される場所にこの図形を追加します。次に、実際のフィールドからダッシュボードを構築します。

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;
論理結果ごとに 1 つのターミナル行を、予想されるステータス、識別子、単位、および UTC 時刻とともに確認します。
推論されたスキーマを検査し、再試行によってフィールド タイプが変更されたり、新しい論理イベント ID が生成されたりしないことを確認します。
保存されたフィールドで認証情報、生のペイロード、プロンプト、プライベート コンテンツ、および無制限のエラー メッセージを検索します。
ダッシュボードを完了として扱う前に、プロバイダーのタイムアウト、取り込みの拒否、およびプロセスのシャットダウンを実行します。

実装の参考資料

新しい運用パスを有効にする前に、イベント契約、データ安全性に関するガイダンス、上流の主要ドキュメントを確認してください。

イベントを記録する場所

結果イベントを小さく、回復可能なものに保つ

このパターンが提供するのは、

  • 上流のワークフローの横にある、制限付きの SQL 対応の結果。
  • ダッシュボード、アラート、およびイベント間の相関関係の安定したフィールド。
  • 成功、失敗、再試行、タイムアウトの動作を検証するためのフィクスチャ駆動のパス。

このパターンでは提供されません

  • OTLP エクスポーター、自動収集パイプライン、または詳細なトレースと診断ログの代替。
  • ペイロードにイベント ID が含まれているという理由だけで、1 回だけ配信されます。
  • 生のプロバイダー ペイロード、ユーザー コンテンツ、資格情報、または規制されたデータを収集する許可。

イベントスキーマの例

クエリまたはスニペットを運用環境に適用する前に、行粒度、出力境界、必要なタイプ、プライバシー クラス、サンプル ペイロード、および検証チェックリストを確認してください。

関連製品の機能

このワークフローを続行します ダッシュボード

検証された製品または収益のクエリを、焦点を絞った意思決定の表面に変えます。

関連する SQL レシピ

その他のSQL例

このワークフローの構造化フィールドに対してクエリを実行し、結果の例を検査して、有用な回答をダッシュボードまたはアラートに変換します。

すべてのレシピを参照する

この統合と組み合わせるテンプレート

さらなる統合