forge_ops_tracker 0.21.0 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: c51ad9b51fd30d2f2524c60fabb955dbd2840a756138a4cf4b9cda47dbd56b49
4
- data.tar.gz: 8a4b895fa3ba817ea0d352cfaaedfd5dc083e4abf69fb25020a523b890ded319
3
+ metadata.gz: da567677dfaa2cb992609ba73ca33ed0885db4e4dad2da51b225292d9aeb3fab
4
+ data.tar.gz: c26b7679f97b332c6d61864bdcbe9fdcfde34b5aa821aefb6ee05f078e90ffc5
5
5
  SHA512:
6
- metadata.gz: 22e8833e29f4de32284cb8203d135dff386a50845de5235c52ab3a39a5574448a2e14e4e85cada210f1b2a44f0367193d1d6d96e97764f0cb3650b1d31a600af
7
- data.tar.gz: 31f1973e9840e5b7396ce7a96fc757288468cb50f65b7ba6de5f8bef6625a7211eb340e0fe6043f644602532a708cfb2d6c2c3453c879c9306e40e2fd7eecfe5
6
+ metadata.gz: 73d3a3b887d600e528ed3f54ecf8c388f6a4c6059974a44a784e3c56aae3836a16495c3b775af2dfa1fb9c94649637b8cab3c50a84d5062518136594a9df1061
7
+ data.tar.gz: 25e99c026b1711ad5f3f63336d49073b5c8b97207941353a47dba436b35516d75fa6ecf7ec2179dfb4523e2fc145cd1fac68bbce53ade121590aa37520a11e78
data/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.23.0 (2026-11-11)
4
+
5
+ - Strict privacy no longer sends the user's raw `id`, which could be a record number that identifies a
6
+ person. Set `config.privacy_user_key` (or `FORGE_OPS_PRIVACY_USER_KEY`) and the id is sent as a keyed
7
+ hash (HMAC-SHA256 with your key, which never leaves your app), so affected customers are still counted.
8
+ Without a key, no user is sent at all.
9
+
10
+ ## 0.22.0 (2026-10-28)
11
+
12
+ - `config.trace_ignore_paths`: requests whose path starts with one of these prefixes are never traced, however
13
+ slow, for health checks or anything else not worth a trace.
14
+
3
15
  ## 0.21.0 (2026-10-23)
4
16
 
5
17
  - PII scrubbing catches card numbers however they're grouped (bare, 4-4-4-4, Amex's 4-6-5, or next to a
data/README.md CHANGED
@@ -237,11 +237,15 @@ trace id, and the database tables or procedures involved), never free text that
237
237
  name, an email or a diagnosis:
238
238
 
239
239
  - No error message. A `message_fingerprint` is sent instead: a one-way hash of the message with
240
- its numbers, hex ids and UUIDs taken out, computed in your process, so errors still group
240
+ its emails, quoted values, numbers, hex ids and UUIDs taken out, computed in your process, so errors still group
241
241
  without the message ever leaving it.
242
242
  - No breadcrumbs (they aren't recorded at all), no `endpoint`, no SQL statement even with
243
243
  `capture_sql_statement` on, and no source context (the source file is never read).
244
- - The user is sent by `id` only, never `email` or `username`.
244
+ - The user's `email` and `username` are never sent, and neither is the raw `id`. With
245
+ `privacy_user_key` set, the id is sent as a keyed hash (HMAC-SHA256 with your key, which never
246
+ leaves your app), so ForgeOps can still count affected customers but can't read the id. Without
247
+ a key, no user is sent at all. Keep the key the same across servers and deploys, or one customer
248
+ counts as two.
245
249
  - Context and tags only keep the top-level keys you list in `privacy_allowed_fields`, and only
246
250
  when the value is a string, number or boolean. Nothing else from them is sent.
247
251
  - Failed jobs and outbound calls keep their error class, never their error message.
@@ -256,11 +260,13 @@ name, an email or a diagnosis:
256
260
  ForgeOpsTracker.configure do |config|
257
261
  config.strict_privacy = true # default false
258
262
  config.privacy_allowed_fields = %w[error_code feature] # default []
263
+ config.privacy_user_key = ENV["MY_FORGE_OPS_USER_KEY"] # default nil: no user sent
259
264
  end
260
265
  ```
261
266
 
262
- Both can also come from the environment: `FORGE_OPS_STRICT_PRIVACY=true` and
263
- `FORGE_OPS_PRIVACY_ALLOWED_FIELDS=error_code,feature` (comma separated). A value set in
267
+ All three can also come from the environment: `FORGE_OPS_STRICT_PRIVACY=true`,
268
+ `FORGE_OPS_PRIVACY_ALLOWED_FIELDS=error_code,feature` (comma separated) and
269
+ `FORGE_OPS_PRIVACY_USER_KEY=...`. A value set in
264
270
  `configure` wins over the environment.
265
271
 
266
272
  ForgeOps applies the same rules again on arrival when the project's own Strict privacy setting is
@@ -446,6 +452,7 @@ A fast, successful request never sends anything.
446
452
  ForgeOpsTracker.configure do |config|
447
453
  config.track_tracing = false # opt out of recording spans entirely
448
454
  config.trace_capture_threshold_ms = 500 # default 1000
455
+ config.trace_ignore_paths = [ "/health" ] # never trace requests under these path prefixes
449
456
  end
450
457
  ```
451
458
 
@@ -16,12 +16,13 @@ module ForgeOpsTracker
16
16
  attr_accessor :track_failures, :failure_event_flush_interval
17
17
  attr_accessor :metric_flush_interval, :infrastructure_metric_flush_interval
18
18
  attr_accessor :gauge_poll_interval
19
- attr_accessor :track_tracing, :trace_capture_threshold_ms
19
+ attr_accessor :track_tracing, :trace_capture_threshold_ms, :trace_ignore_paths
20
20
  attr_accessor :explain_slow_queries, :explain_threshold_ms
21
21
  attr_accessor :propagate_traces, :trace_propagation_targets
22
22
  attr_accessor :detect_changes, :track_env_var_names
23
23
  attr_accessor :strict_privacy
24
24
  attr_reader :privacy_allowed_fields
25
+ attr_accessor :privacy_user_key
25
26
 
26
27
  def initialize
27
28
  @dsn = ENV["FORGE_OPS_DSN"]
@@ -129,6 +130,10 @@ module ForgeOpsTracker
129
130
  # PerformanceSample-derived threshold elsewhere in this gem: those describe a trend across
130
131
  # many requests, this describes a single one being outright slow.
131
132
  @trace_capture_threshold_ms = 1_000
133
+ # Requests whose path starts with one of these are never traced at all. For an app that
134
+ # reports to itself (ForgeOps on ForgeOps), its own ingestion endpoints: storing a slow trace
135
+ # is a slow request, whose trace would be sent back to be stored, and so on.
136
+ @trace_ignore_paths = []
132
137
  # Opt-in: for a SELECT on PostgreSQL that took at least explain_threshold_ms, ask Postgres for
133
138
  # its plan (plain EXPLAIN, never EXPLAIN ANALYZE, so the query is never run again) and send
134
139
  # it, masked, so ForgeOps can show why the query was slow. Off by default because it runs one
@@ -161,7 +166,7 @@ module ForgeOpsTracker
161
166
  # Off by default. On, nothing this gem sends carries free text that could hold personal or
162
167
  # health data: no error message (a message_fingerprint is sent instead, so errors still
163
168
  # group), no breadcrumbs, no request path, no SQL statement, no source context, no user email
164
- # or username, no job failure message, and outbound HTTP spans named by method and host only.
169
+ # or username, the user's id only as a keyed hash (privacy_user_key), no job failure message, and outbound HTTP spans named by method and host only.
165
170
  # See StrictPrivacy for every rule. FORGE_OPS_STRICT_PRIVACY=true turns it on from the
166
171
  # environment; setting it here wins over that.
167
172
  @strict_privacy = self.class.env_flag(ENV["FORGE_OPS_STRICT_PRIVACY"])
@@ -170,6 +175,11 @@ module ForgeOpsTracker
170
175
  # so nothing from context or tags goes out. FORGE_OPS_PRIVACY_ALLOWED_FIELDS=error_code,feature
171
176
  # sets it from the environment.
172
177
  self.privacy_allowed_fields = ENV["FORGE_OPS_PRIVACY_ALLOWED_FIELDS"].to_s.split(",")
178
+ # Strict privacy sends the user's id only as a keyed hash (StrictPrivacy.hashed_user_id) with
179
+ # this secret, which stays in your app; unset, no user is sent at all. Keep it the same
180
+ # across deploys and servers, or the same customer counts as two. FORGE_OPS_PRIVACY_USER_KEY
181
+ # sets it from the environment.
182
+ @privacy_user_key = ENV["FORGE_OPS_PRIVACY_USER_KEY"].to_s.empty? ? nil : ENV["FORGE_OPS_PRIVACY_USER_KEY"]
173
183
  end
174
184
 
175
185
  # Accepts an Array of names or one comma-separated String; always kept as stripped Strings.
@@ -63,7 +63,7 @@ module ForgeOpsTracker
63
63
  payload = scrub(payload)
64
64
  return payload unless configuration.strict_privacy
65
65
 
66
- StrictPrivacy.event(payload, allowed_fields: configuration.privacy_allowed_fields)
66
+ StrictPrivacy.event(payload, allowed_fields: configuration.privacy_allowed_fields, user_key: configuration.privacy_user_key)
67
67
  end
68
68
 
69
69
  private
@@ -34,6 +34,7 @@ module ForgeOpsTracker
34
34
 
35
35
  def call(env)
36
36
  return app.call(env) unless configuration.track_tracing && configuration.enabled?
37
+ return app.call(env) if ignored_path?(env)
37
38
 
38
39
  state = RequestState.for(env)
39
40
  buffer = SpanBuffer.new(trace_id: state.trace_id, parent_span_id: state.parent_span_id)
@@ -49,6 +50,11 @@ module ForgeOpsTracker
49
50
  private
50
51
  attr_reader :app, :configuration
51
52
 
53
+ def ignored_path?(env)
54
+ path = env["PATH_INFO"].to_s
55
+ Array(configuration.trace_ignore_paths).any? { |prefix| path.start_with?(prefix) }
56
+ end
57
+
52
58
  def send_trace?(buffer, state)
53
59
  return true if buffer.slow?(configuration.trace_capture_threshold_ms)
54
60
 
@@ -1,4 +1,5 @@
1
1
  require "digest"
2
+ require "openssl"
2
3
 
3
4
  module ForgeOpsTracker
4
5
  # What Configuration#strict_privacy changes in everything this gem sends, for apps that can't let
@@ -54,23 +55,28 @@ module ForgeOpsTracker
54
55
  # always is, rather than converted byte by byte, which would turn every non-ASCII character into
55
56
  # replacement characters and hash differently from the same text arriving as UTF-8.
56
57
  def message_fingerprint(message)
57
- normalized = normalize_message(message)
58
- normalized = normalized.dup.force_encoding(Encoding::UTF_8) if normalized.encoding == Encoding::BINARY
59
- normalized = normalized.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) unless normalized.encoding == Encoding::UTF_8
60
- Digest::SHA256.hexdigest(normalized.scrub)[0, FINGERPRINT_LENGTH]
58
+ Digest::SHA256.hexdigest(utf8(normalize_message(message)))[0, FINGERPRINT_LENGTH]
59
+ end
60
+
61
+ # The text's UTF-8 bytes, which is what every SDK hashes: plain bytes are relabelled as UTF-8
62
+ # (converting would replace each non-ASCII byte), anything else is converted.
63
+ def utf8(text)
64
+ text = text.dup.force_encoding(Encoding::UTF_8) if text.encoding == Encoding::BINARY
65
+ text = text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) unless text.encoding == Encoding::UTF_8
66
+ text.scrub
61
67
  end
62
68
 
63
69
  # An error event payload (EventBuilder#build's shape, symbol keys) reduced to what strict
64
70
  # privacy sends. message is sent as "" alongside message_fingerprint, exactly what the server
65
71
  # stores for a strict project.
66
- def event(payload, allowed_fields: [])
72
+ def event(payload, allowed_fields: [], user_key: nil)
67
73
  payload.reject { |key, _value| EVENT_FIELDS_DROPPED.include?(key) }.merge(
68
74
  message: "",
69
75
  message_fingerprint: message_fingerprint(payload[:message]),
70
76
  transaction_name: transaction_name(payload[:transaction_name]),
71
77
  context: allowed(payload[:context], allowed_fields),
72
78
  tags: allowed(payload[:tags], allowed_fields),
73
- user: user(payload[:user]),
79
+ user: user(payload[:user], user_key),
74
80
  backtrace: Array(payload[:backtrace]).map { |frame| frame.reject { |key, _value| SOURCE_CONTEXT_FIELDS.include?(key) } }
75
81
  ).compact
76
82
  end
@@ -167,12 +173,22 @@ module ForgeOpsTracker
167
173
  kept unless kept.empty?
168
174
  end
169
175
 
170
- # The user's id, as a string, and nothing else; nil when there's no id.
171
- def user(user)
176
+ # Only a keyed hash of the user's id (hashed_user_id), and only when the app set
177
+ # Configuration#privacy_user_key; nil otherwise. A raw id can be a record number that identifies
178
+ # a person, and an unkeyed hash of a small number can be guessed back.
179
+ def user(user, key = nil)
172
180
  return nil unless user.is_a?(Hash)
181
+ return nil if key.nil? || key.to_s.empty?
173
182
 
174
183
  id = user[:id] || user["id"]
175
- { id: id.to_s } unless id.nil? || id.to_s.strip.empty?
184
+ { id: hashed_user_id(id, key) } unless id.nil? || id.to_s.strip.empty?
185
+ end
186
+
187
+ # "h1:" and the first 32 lowercase hex characters of HMAC-SHA256 of the id's UTF-8 text, keyed
188
+ # with the app's own secret, which ForgeOps never sees. The same id hashes the same under one
189
+ # key, so affected customers can still be counted.
190
+ def hashed_user_id(id, key)
191
+ "h1:#{OpenSSL::HMAC.hexdigest("SHA256", utf8(key.to_s), utf8(id.to_s))[0, FINGERPRINT_LENGTH]}"
176
192
  end
177
193
  end
178
194
  end
@@ -1,3 +1,3 @@
1
1
  module ForgeOpsTracker
2
- VERSION = "0.21.0"
2
+ VERSION = "0.23.0"
3
3
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: forge_ops_tracker
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.21.0
4
+ version: 0.23.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - ForgeOps