forge_ops_tracker 0.17.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 304c9a15155ecdf53fe8e181dd7f43b56a08d7397e7d63555e428185ece06560
-  data.tar.gz: d4d2cb88ffec650e579c7279c590e4eaee8f288bc6ef7041d2c2f5785767fa2f
+  metadata.gz: 3d585c1acbde6c8bb06ec05505e21bf4d784974ed8e655c9398fef0c7e595d03
+  data.tar.gz: af67478c90a33dd594bbccf712e48dc817d5e99ae6b61edf0a0fca62e816e4ec
 SHA512:
-  metadata.gz: dfd3a51d60e0decd113e2a8bd50db101ebd4ec57ebb468a522413b4f9ffa0c5c15d5440939c7a6f772561ce6ffe5c7078322d2903f0d3ec87006f1dd368c1718
-  data.tar.gz: 1646c0b506c357122c513604d031974318df0086a0c2a962c99e80143624be459755fab5dfff3df7718f24bb6caebe699ba5325fafb79b35a92f76ffa0783b63
+  metadata.gz: ae806f1ba9cb14102494df6f6efca7685ce4900c281fda85c72fe9ad595f5ce3b03b7daf74762ef69de002e0c229d3155027eee4bd3c8d876646b824f4ee1ab4
+  data.tar.gz: b774e7abc22663d23f728c71ee7d358180994ccc31b23eb334d393c39da7d403561456b4b484bbe34f3f1678c7f619a40ac94c977a4086ccac66f852790cdb85

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.19.0 (2026-10-20)
+
+- Strict privacy: a raw request path now keeps only its first segment, and the rest is sent as
+  `:path` (`/patients/jane-doe/12` becomes `/patients/:path`; a first segment with a digit or over
+  40 characters becomes `:id`). Before, only segments holding a digit were replaced, so a path like
+  `/patients/janedoe` went out whole. A route template (`/patients/:id/notes`, `{id}`, `<int:id>`,
+  `[slug]`, `*path`) is kept as it is. This applies everywhere strict privacy names a request or a
+  call by its path: span names and transaction names.
+
+## 0.18.0 (2026-10-20)
+
+- New `config.strict_privacy` (off by default, or `FORGE_OPS_STRICT_PRIVACY=true`) for apps that
+  can't let personal or health data leave their servers. With it on, an error event carries no
+  message (a `message_fingerprint` computed in your process is sent instead, so errors still
+  group), no breadcrumbs, no `endpoint`, no SQL statement and no source context, and the user only
+  by `id`. Failed jobs and outbound calls keep their error class but not their message, and
+  outbound HTTP spans are named by method and host only, with no span data but `db.statement` and
+  `db.system`. A `transaction_name` that is a raw path, not a route or `Controller#action`, has its
+  ids taken out in error events, performance samples and failure events.
+- New `config.privacy_allowed_fields` (or `FORGE_OPS_PRIVACY_ALLOWED_FIELDS=error_code,feature`):
+  the context and tag keys strict privacy still sends, when their value is a string, number or
+  boolean. Empty by default.
+
 ## 0.17.0 (2026-10-13)
 
 - Fixed: a batch the server refused was re-sent at every flush for as long as the process lived,

data/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 ForgeOps
+Copyright (c) 2026 Luke Popwell
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -226,6 +226,44 @@ ForgeOpsTracker.configure do |config|
 end
 ```
 
+## Strict privacy
+
+For apps that can't let personal or health data (PII, PHI) leave their own servers. With strict
+privacy on, the gem sends only structured facts about an error (its class, its stack frames'
+file, line and method, the release, environment, server, the request's `transaction_name` and
+trace id, and the database tables or procedures involved), never free text that could hold a
+name, an email or a diagnosis:
+
+- No error message. A `message_fingerprint` is sent instead: a one-way hash of the message with
+  its numbers, hex ids and UUIDs taken out, computed in your process, so errors still group
+  without the message ever leaving it.
+- No breadcrumbs (they aren't recorded at all), no `endpoint`, no SQL statement even with
+  `capture_sql_statement` on, and no source context (the source file is never read).
+- The user is sent by `id` only, never `email` or `username`.
+- Context and tags only keep the top-level keys you list in `privacy_allowed_fields`, and only
+  when the value is a string, number or boolean. Nothing else from them is sent.
+- Failed jobs and outbound calls keep their error class, never their error message.
+- A `transaction_name` that is a raw path rather than a route or `Controller#action` keeps only
+  its first segment (`GET /patients/jane-doe/12` is sent as `GET /patients/:path`; a first
+  segment with a digit becomes `:id`), in error events, performance samples, failure events and
+  spans alike. A route template such as `/patients/:id/notes` is kept as it is.
+- Outbound HTTP spans are named by method and host only (`GET api.example.com`), and span data
+  keeps only the masked `db.statement` and `db.system`.
+
+```ruby
+ForgeOpsTracker.configure do |config|
+  config.strict_privacy = true                           # default false
+  config.privacy_allowed_fields = %w[error_code feature] # default []
+end
+```
+
+Both can also come from the environment: `FORGE_OPS_STRICT_PRIVACY=true` and
+`FORGE_OPS_PRIVACY_ALLOWED_FIELDS=error_code,feature` (comma separated). A value set in
+`configure` wins over the environment.
+
+ForgeOps applies the same rules again on arrival when the project's own Strict privacy setting is
+on, so an app with an older gem, or one with this option off, still can't get that text stored.
+
 ## Source context
 
 By default, each in-app backtrace frame (never a vendored gem) is captured along with the 5 lines

data/lib/forge_ops_tracker/breadcrumb_buffer.rb

@@ -23,7 +23,8 @@ module ForgeOpsTracker
       # ForgeOpsTracker.configure takes effect on whatever's added next, not just a buffer created
       # afterward.
       max_size = [ configuration.max_breadcrumbs, 0 ].max
-      return if max_size.zero?
+      # Strict privacy never sends breadcrumbs, so they're never recorded either.
+      return if max_size.zero? || configuration.strict_privacy
 
       entries << {
         category: category.to_s,

data/lib/forge_ops_tracker/configuration.rb

@@ -20,6 +20,8 @@ module ForgeOpsTracker
     attr_accessor :explain_slow_queries, :explain_threshold_ms
     attr_accessor :propagate_traces, :trace_propagation_targets
     attr_accessor :detect_changes, :track_env_var_names
+    attr_accessor :strict_privacy
+    attr_reader :privacy_allowed_fields
 
     def initialize
       @dsn = ENV["FORGE_OPS_DSN"]
@@ -156,6 +158,24 @@ module ForgeOpsTracker
       # but even names can describe more about an app than some teams want to share. See
       # ChangeSnapshot::ENV_VAR_DENYLIST for the host-specific names that are always left out.
       @track_env_var_names = false
+      # Off by default. On, nothing this gem sends carries free text that could hold personal or
+      # health data: no error message (a message_fingerprint is sent instead, so errors still
+      # group), no breadcrumbs, no request path, no SQL statement, no source context, no user email
+      # or username, no job failure message, and outbound HTTP spans named by method and host only.
+      # See StrictPrivacy for every rule. FORGE_OPS_STRICT_PRIVACY=true turns it on from the
+      # environment; setting it here wins over that.
+      @strict_privacy = self.class.env_flag(ENV["FORGE_OPS_STRICT_PRIVACY"])
+      # Context and tag keys strict privacy still sends (only plain string, number or boolean
+      # values under exactly these top-level keys), e.g. %w[error_code feature]. Empty by default,
+      # so nothing from context or tags goes out. FORGE_OPS_PRIVACY_ALLOWED_FIELDS=error_code,feature
+      # sets it from the environment.
+      self.privacy_allowed_fields = ENV["FORGE_OPS_PRIVACY_ALLOWED_FIELDS"].to_s.split(",")
+    end
+
+    # Accepts an Array of names or one comma-separated String; always kept as stripped Strings.
+    def privacy_allowed_fields=(fields)
+      fields = fields.split(",") if fields.is_a?(String)
+      @privacy_allowed_fields = Array(fields).map { |field| field.to_s.strip }.reject(&:empty?)
     end
 
     # Whether an outbound request to host should carry a traceparent header; see
@@ -290,6 +310,11 @@ module ForgeOpsTracker
       [ env["FORGE_OPS_ENVIRONMENT"], env["RAILS_ENV"], env["RACK_ENV"] ].find { |value| value && !value.strip.empty? } || "production"
     end
 
+    # "true", "1", "yes" or "on" (any case) is on; anything else, or unset, is off.
+    def self.env_flag(value)
+      %w[true 1 yes on].include?(value.to_s.strip.downcase)
+    end
+
     private
       def environment_enabled?
         enabled_environments.map(&:to_s).include?(environment.to_s)

data/lib/forge_ops_tracker/event_builder.rb

@@ -35,6 +35,12 @@ module ForgeOpsTracker
     # request (a background job, a console session) and each key is left out of the payload
     # entirely when nil, the same "omit rather than send an empty value" treatment user and
     # breadcrumbs already get.
+    #
+    # With configuration.strict_privacy on, the finished payload goes through StrictPrivacy.event:
+    # the message is replaced by its message_fingerprint (computed from the message as it would
+    # otherwise have been sent, so after scrub_pii, which is also what the server fingerprints from
+    # a gem without strict privacy, and keeps a message holding an email grouping together), and breadcrumbs, endpoint, the SQL statement, source context, the user's
+    # email/username and every context/tag key not in privacy_allowed_fields are left out.
     def build(error, context: {}, user: nil, breadcrumbs: [], transaction_name: nil, endpoint: nil, trace_id: nil)
       payload = {
         exception_class: error.class.name,
@@ -54,7 +60,10 @@ module ForgeOpsTracker
       payload[:endpoint] = endpoint if endpoint
       payload[:trace_id] = trace_id if trace_id
       attach_sql(payload, error)
-      scrub(payload)
+      payload = scrub(payload)
+      return payload unless configuration.strict_privacy
+
+      StrictPrivacy.event(payload, allowed_fields: configuration.privacy_allowed_fields)
     end
 
     private
@@ -96,7 +105,7 @@ module ForgeOpsTracker
 
         objects = SqlStatement.objects(masked)
         payload[:sql_objects] = objects if objects && configuration.capture_sql_objects
-        payload[:sql_statement] = masked if configuration.capture_sql_statement
+        payload[:sql_statement] = masked if configuration.capture_sql_statement && !configuration.strict_privacy
       end
 
       def backtrace_frames(error)
@@ -135,9 +144,10 @@ module ForgeOpsTracker
       # to turn it off). Best-effort: any file that can't be read (deleted,
       # permission denied, a path that only ever existed inside a build
       # step and isn't present in this deployment) just means this one
-      # frame gets no source context, not a raised error of its own.
+      # frame gets no source context, not a raised error of its own. Never read at all under
+      # strict privacy, which never sends it.
       def attach_source_context(frame)
-        return frame unless configuration.capture_source_context && frame[:in_app]
+        return frame unless configuration.capture_source_context && frame[:in_app] && !configuration.strict_privacy
 
         lines = File.readlines(frame[:file])
         index = frame[:line] - 1

data/lib/forge_ops_tracker/failure_event_buffer.rb

@@ -31,11 +31,13 @@ module ForgeOpsTracker
       @mutex.synchronize do
         return false if @entries.size >= MAX_ENTRIES
 
-        @entries << {
+        entry = {
           kind: kind, transaction_name: transaction_name, error_class: error_class, error_message: error_message,
           environment: configuration.environment.to_s, release: configuration.release,
           occurred_at: Time.now.utc.iso8601
         }
+        # Strict privacy keeps the error's class, never its message.
+        @entries << (configuration.strict_privacy ? StrictPrivacy.failure_event(entry) : entry)
       end
     end
 

data/lib/forge_ops_tracker/middleware/span_tracing.rb

@@ -41,7 +41,7 @@ module ForgeOpsTracker
         app.call(env)
       ensure
         if buffer && send_trace?(buffer, state)
-          Railtie.span_queue.push(trace_id: buffer.trace_id, spans: buffer.spans)
+          Railtie.span_queue.push(trace_id: buffer.trace_id, spans: outgoing_spans(buffer))
         end
         Thread.current[:forge_ops_tracker_spans] = nil
       end
@@ -54,6 +54,14 @@ module ForgeOpsTracker
 
           state.errored? && buffer.root_recorded?
         end
+
+        # Under strict privacy, every span goes through StrictPrivacy.span: an outbound call named
+        # by its method and host only, and no span data but the masked statement and db.system.
+        def outgoing_spans(buffer)
+          return buffer.spans unless configuration.strict_privacy
+
+          buffer.spans.map { |span| StrictPrivacy.span(span) }
+        end
     end
   end
 end

data/lib/forge_ops_tracker/performance_flusher.rb

@@ -31,6 +31,9 @@ module ForgeOpsTracker
     # without colliding into the same bucket.
     def record(transaction_name:, duration_ms:, kind: "controller")
       ensure_worker_started
+      # Under strict privacy a raw-path name keeps only its first segment; a route or
+      # Controller#action is kept.
+      transaction_name = StrictPrivacy.transaction_name(transaction_name) if configuration.strict_privacy
 
       @mutex.synchronize do
         bucket = (@buckets[[ transaction_name, kind ]] ||= { count: 0, duration_sum_ms: 0.0, max_duration_ms: 0.0, histogram: Hash.new(0) })

data/lib/forge_ops_tracker/strict_privacy.rb

@@ -0,0 +1,171 @@
+require "digest"
+
+module ForgeOpsTracker
+  # What Configuration#strict_privacy changes in everything this gem sends, for apps that can't let
+  # personal or health data leave their own servers. With it on, only structured facts go out (the
+  # error's class, its stack frames, release, environment, server, which request it happened in,
+  # timings and counts); free text, which is where a name, an email or a diagnosis hides, never
+  # leaves this process: no error message, no breadcrumbs, no raw request path, no SQL statement,
+  # no source context, no user email or username, and only the context/tag keys listed in
+  # Configuration#privacy_allowed_fields.
+  #
+  # The same rules as the server's own StrictPrivacy (app/services/strict_privacy.rb), which
+  # applies them again on arrival when the project's Strict privacy setting is on;
+  # sdks/strict_privacy_vectors.json pins the results both have to agree on, byte for byte.
+  module StrictPrivacy
+    FINGERPRINT_LENGTH = 32
+
+    # ASCII "word" characters; boundaries are defined against these, the same in every SDK, so
+    # Ruby's own idea of a word never changes the result.
+    WORD = "A-Za-z0-9_".freeze
+    HEX_OBJECT_ID = /0x[0-9a-fA-F]{4,}/
+    UUID = /(?<![#{WORD}])[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(?![#{WORD}])/
+    NUMBER = /(?<![#{WORD}])[0-9]+(?![#{WORD}])/
+
+    # Span data that's structure, not content: the masked statement and which database it ran on.
+    SPAN_DATA_KEYS = %w[db.statement db.system].freeze
+    HTTP_METHOD = /\A(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(\S+)/i
+    SCHEME = %r{\A[a-z][a-z0-9+.-]*://}i
+    ROUTE_PARAMETER = /\A(?::.+|\{.+\}|<.+>|\[.+\]|\*.*)\z/
+
+    # Error event fields that are never sent, and the per-frame source context.
+    EVENT_FIELDS_DROPPED = %i[message breadcrumbs endpoint sql_statement].freeze
+    SOURCE_CONTEXT_FIELDS = %i[context_line pre_context post_context].freeze
+
+    module_function
+
+    # The message with hex object ids, UUIDs and standalone numbers replaced, in that order.
+    def normalize_message(message)
+      message.to_s.gsub(HEX_OBJECT_ID, "0x").gsub(UUID, "<uuid>").gsub(NUMBER, "<n>")
+    end
+
+    # Lets ForgeOps group errors without ever seeing their message: the first 32 hex characters of
+    # the SHA-256 of the normalized message's UTF-8 bytes, so two messages that differ only in ids
+    # hash the same, and nothing about the text can be read back from it.
+    #
+    # A message labelled binary (some C extensions raise with one) is read as the UTF-8 it almost
+    # always is, rather than converted byte by byte, which would turn every non-ASCII character into
+    # replacement characters and hash differently from the same text arriving as UTF-8.
+    def message_fingerprint(message)
+      normalized = normalize_message(message)
+      normalized = normalized.dup.force_encoding(Encoding::UTF_8) if normalized.encoding == Encoding::BINARY
+      normalized = normalized.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) unless normalized.encoding == Encoding::UTF_8
+      Digest::SHA256.hexdigest(normalized.scrub)[0, FINGERPRINT_LENGTH]
+    end
+
+    # An error event payload (EventBuilder#build's shape, symbol keys) reduced to what strict
+    # privacy sends. message is sent as "" alongside message_fingerprint, exactly what the server
+    # stores for a strict project.
+    def event(payload, allowed_fields: [])
+      payload.reject { |key, _value| EVENT_FIELDS_DROPPED.include?(key) }.merge(
+        message: "",
+        message_fingerprint: message_fingerprint(payload[:message]),
+        transaction_name: transaction_name(payload[:transaction_name]),
+        context: allowed(payload[:context], allowed_fields),
+        tags: allowed(payload[:tags], allowed_fields),
+        user: user(payload[:user]),
+        backtrace: Array(payload[:backtrace]).map { |frame| frame.reject { |key, _value| SOURCE_CONTEXT_FIELDS.include?(key) } }
+      ).compact
+    end
+
+    # A background job or dependency failure: its class is kept, its message never is, and its
+    # transaction_name goes through transaction_name above.
+    def failure_event(entry)
+      entry.reject { |key, _value| key == :error_message }.merge(transaction_name: transaction_name(entry[:transaction_name]))
+    end
+
+    # A trace's span: an outbound call's name keeps its method and host, never its path or query,
+    # and its data keeps only the masked statement and database system. data is left out entirely
+    # when nothing is left of it, the same as the server does.
+    def span(span)
+      data = (span[:data] || {}).select { |key, _value| SPAN_DATA_KEYS.include?(key.to_s) }
+      span.merge(name: span_name(span[:name]), data: (data unless data.empty?)).compact
+    end
+
+    # "GET https://api.example.com/patients/42?x=1" or "GET api.example.com/patients/42" becomes
+    # "GET api.example.com". A bare path ("/patients/42"), or a method and a path
+    # ("PUT /orders/17/items"), goes through the path rule, like a page path. A name that's neither
+    # ("OrdersController#create", "patients#show") is kept.
+    def span_name(name)
+      return strict_path(name) if name.to_s.start_with?("/")
+
+      match = name.to_s.match(HTTP_METHOD)
+      return name unless match
+
+      method = match[1].upcase
+      target = match[2]
+      return "#{method} #{strict_path(target)}" if target.start_with?("/")
+
+      "#{method} #{host(target) || strict_path(target)}"
+    end
+
+    # Which request something happened in: a route or a controller action is kept, but a raw path
+    # (what a request no route matched falls back to) keeps only its first segment, by the span name
+    # rule.
+    def transaction_name(name)
+      name.nil? || name.to_s.empty? ? name : span_name(name)
+    end
+
+    # An outbound call's host, read by hand rather than with URI.parse (an address a parser rejects
+    # must never be sent whole): what comes before the first "/", "?" or "#", without a scheme,
+    # credentials (up to the last "@", since a password can hold one) or port. Only a host when the
+    # address had a scheme or a port, or the name has a dot or is "localhost"; nil otherwise (a
+    # relative path).
+    def host(target)
+      scheme = target.match?(SCHEME)
+      authority = target.sub(SCHEME, "").split(%r{[/?#]}, 2).first.to_s.sub(/\A.*@/m, "")
+      port = authority.match?(/:\d+\z/)
+      host = authority.sub(/:\d+\z/, "")
+      return nil if host.empty?
+
+      host if scheme || port || host.include?(".") || host.casecmp?("localhost")
+    end
+
+    # A request or page path under strict privacy, with no query or fragment. A route template
+    # ("/patients/:id/notes", "/patients/{id}", "users/<int:id>/", "/files/*path", "/posts/[slug]")
+    # is kept as it is: its words are a developer's, and its parameters are already placeholders. A
+    # raw path keeps only its first segment, and the rest becomes ":path": "/patients/jane-doe/12"
+    # is "/patients/:path". Anything after the first segment of a raw path could name a person, and
+    # no rule can tell a name from a word ("/patients/janedoe"). A first segment that holds a digit
+    # or is over 40 characters is ":id" itself.
+    def strict_path(path)
+      path = path.to_s.split(/[?#]/, 2).first.to_s
+      return path if route_template?(path)
+
+      leading = path.start_with?("/") ? "/" : ""
+      segments = path.split("/").reject(&:empty?)
+      return "/" if segments.empty?
+
+      first = segments.first.match?(/[0-9]/) || segments.first.length > 40 ? ":id" : segments.first
+      "#{leading}#{first}#{"/:path" if segments.size > 1}"
+    end
+
+    # Whether any segment is a route parameter: ":id", "{id}", "<int:id>", "[slug]" or "*path".
+    def route_template?(path)
+      path.split("/").any? { |segment| segment.match?(ROUTE_PARAMETER) }
+    end
+
+    # Only top-level keys named in allowed_fields, and only plain values under them; nil (left out
+    # of the payload) when nothing is left.
+    def allowed(fields, allowed_fields)
+      allowed_fields = Array(allowed_fields).map(&:to_s)
+      return nil if allowed_fields.empty? || !fields.is_a?(Hash)
+
+      kept = fields.each_with_object({}) do |(key, value), result|
+        next unless allowed_fields.include?(key.to_s)
+        next unless value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false
+
+        result[key.to_s] = value
+      end
+      kept unless kept.empty?
+    end
+
+    # The user's id, as a string, and nothing else; nil when there's no id.
+    def user(user)
+      return nil unless user.is_a?(Hash)
+
+      id = user[:id] || user["id"]
+      { id: id.to_s } unless id.nil? || id.to_s.strip.empty?
+    end
+  end
+end

data/lib/forge_ops_tracker/version.rb

@@ -1,3 +1,3 @@
 module ForgeOpsTracker
-  VERSION = "0.17.0"
+  VERSION = "0.19.0"
 end

data/lib/forge_ops_tracker.rb

@@ -3,6 +3,7 @@ require "forge_ops_tracker/version"
 require "forge_ops_tracker/configuration"
 require "forge_ops_tracker/pii_scrubber"
 require "forge_ops_tracker/sql_statement"
+require "forge_ops_tracker/strict_privacy"
 require "forge_ops_tracker/event_builder"
 require "forge_ops_tracker/delivery_status"
 require "forge_ops_tracker/client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forge_ops_tracker
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.19.0
 platform: ruby
 authors:
 - ForgeOps
@@ -138,6 +138,7 @@ files:
 - lib/forge_ops_tracker/span_buffer.rb
 - lib/forge_ops_tracker/span_queue.rb
 - lib/forge_ops_tracker/sql_statement.rb
+- lib/forge_ops_tracker/strict_privacy.rb
 - lib/forge_ops_tracker/trace_parent.rb
 - lib/forge_ops_tracker/version.rb
 homepage: https://getforgeops.net