packrat-rails 0.3.0 → 0.4.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: 0d0517644891d1ef5faed2448e36d24f1f496a0fbd834cff6ec69187671d1b78
4
- data.tar.gz: 7d7222c6849bf4b7020d25ce09aae5e8309fa1d807fb102183ea485bca2ed6a4
3
+ metadata.gz: 5daf74b5d37211409de14b6a43c130e01df37a71d255aa7407b0bb1bc78a0917
4
+ data.tar.gz: d7cff3b8ebe3dcd6cbae6a772ee666d9fc0dab95ad4708a7ec49557aaed7f684
5
5
  SHA512:
6
- metadata.gz: cddd52f93532330674451fe218530ed85c56c025f9823a98efd5b7af111a51395ce0480cf98a2e3de2da690f3e88aa2c11e758e6036259de2c9f14b2ed2c01c6
7
- data.tar.gz: 96695d0e66c9f90995b2674fb90ded64e10095dd0be9ce1260fb22bdc6d7ef620c3bf1db97880ed9f4a06d16b38440e16877d6026fb17753f46b506db395a883
6
+ metadata.gz: 81e976750f407842977a412a824a33e3ada0056d4cf66be525b59662125d0a0fe6bc3b412197b4acf73fe5fdcb5f1fd7c1f65adc356ceb2562266219c85379be
7
+ data.tar.gz: 94a4cf7f548a6314a98fbc1e26676e1149fa6219ba82ffbbd129107022f68f4a254ffa8ed18fd0a13b6a2bfcad241ae5df5d90c2d91126abdacc5b4f5f8b275f
data/README.md CHANGED
@@ -27,7 +27,8 @@ run the generator without `--ingest-key` and set `PACKRAT_INGEST_KEY` where the
27
27
 
28
28
  The generator also turns on the [Packrat plugin for Claude Code](https://packrat.sh/docs/claude-code-plugin)
29
29
  in `.claude/settings.json`. Commit the file, and everyone who opens Claude Code in the repository and
30
- trusts the folder gets the plugin. If the file exists, the generator adds the plugin and keeps the rest.
30
+ trusts the folder gets the plugin, and Claude Code keeps it up to date (`"autoUpdate": true` on the
31
+ `packrat` marketplace). If the file exists, the generator adds the plugin and keeps the rest.
31
32
  To leave the file alone, pass `--no-claude-code`.
32
33
 
33
34
  To start with [strict privacy](#privacy), pass `--strict`.
@@ -36,13 +37,13 @@ On boot the gem writes one line to the Rails log. It names the service and envir
36
37
  reports under:
37
38
 
38
39
  ```
39
- Packrat: sending traces and logs for shop/production to https://ingest.packrat.sh (rack, action_pack, active_job, active_record, net_http, pg, logger); redacting email and ip
40
+ Packrat: sending traces and logs for shop/production to https://ingest.packrat.sh (rack, action_pack, active_job, net_http, pg, logger); redacting email and ip
40
41
  ```
41
42
 
42
43
  ## Configuration
43
44
 
44
- The ingest key, the ingest URL and the privacy level are the only settings in `Packrat.configure`. Everything else is
45
- an environment variable.
45
+ `Packrat.configure` sets the ingest key, the ingest URL, the privacy level,
46
+ [your own redaction](#redact-your-own-data) and `debug_export`. Everything else is an environment variable.
46
47
 
47
48
  | Variable | Default | Note |
48
49
  | ------------------------------- | --------------------------- | ------------------------------------------------------------ |
@@ -52,13 +53,20 @@ an environment variable.
52
53
  | `PACKRAT_OTEL_INSTRUMENTATIONS` | the list below | Comma-separated names to add; a leading `-` removes one |
53
54
  | `PACKRAT_PRIVACY` | `config.privacy`, else `standard` | `standard` or `strict`. Wins over the initializer. Any other value is strict |
54
55
  | `PACKRAT_REDACT` | `email,ip` | Patterns redacted from values; `-ip` stops masking IP addresses |
56
+ | `PACKRAT_DEBUG_EXPORT` | `config.debug_export`, else off | `1` prints everything sent to stdout. See [what is sent](#see-what-is-sent) |
55
57
 
56
- The instrumentations are `rack`, `action_pack`, `action_view`, `active_job`, `active_record`,
57
- `net_http`, `pg`, `mysql2`, `sidekiq`, `redis`, `aws_sdk`, `concurrent_ruby`, `rake` and `logger`. One for a library that is not in the app installs nothing.
58
+ The instrumentations are `rack`, `action_pack`, `action_view`, `active_job`, `net_http`, `pg`,
59
+ `mysql2`, `sidekiq`, `redis`, `aws_sdk`, `concurrent_ruby`, `rake` and `logger`. One for a library that is not in the app installs nothing.
58
60
  `PACKRAT_OTEL_INSTRUMENTATIONS=faraday,-action_view` adds Faraday (with
59
61
  `opentelemetry-instrumentation-faraday` in the Gemfile) and removes Action View. `action_mailer` and
60
62
  `active_storage` cannot be added: they must load before boot ends.
61
63
 
64
+ Each database query is one span. The `pg` or `mysql2` span is named after the query the way the
65
+ Rails log names it (`Order Load`, `Order Create`, `TRANSACTION`) and carries the SQL in
66
+ `db.statement`. A query Rails does not name, such as `connection.select_value`, keeps the driver's
67
+ name. `active_record` is not on the list because its span wraps the driver's and would record each
68
+ query twice. `PACKRAT_OTEL_INSTRUMENTATIONS=active_record` adds it back.
69
+
62
70
  The service name is `OTEL_SERVICE_NAME`, else `service.name` in `OTEL_RESOURCE_ATTRIBUTES`, else the
63
71
  app's module name (`Shop::Application` is `shop`). The environment is `Rails.env` unless
64
72
  `OTEL_RESOURCE_ATTRIBUTES` names one. The version is `BUILD_COMMIT`, `HEROKU_SLUG_COMMIT` or
@@ -96,11 +104,47 @@ In standard, the gem redacts:
96
104
  - **Credentials**: values named like a key, token, password, secret, signature or credential, and
97
105
  `Bearer` or `Basic` values.
98
106
 
99
- Patterns can't recognize other personal data, such as a name or a support ticket's text in a log
100
- line. If your logs can hold that, use strict: pass `--strict` to the generator, set
107
+ Patterns can't recognize other personal data, such as a name or an account number in a log line.
108
+ To remove that, [redact your own data](#redact-your-own-data). If your logs can hold text you can't
109
+ describe, such as a support ticket's body, use strict: pass `--strict` to the generator, set
101
110
  `config.privacy = :strict`, or set `PACKRAT_PRIVACY=strict`. Strict keeps routes, durations, status
102
111
  codes, errors by class and the shape of each query, which is what a deploy check needs.
103
112
 
113
+ ### Redact your own data
114
+
115
+ Your own keys, patterns and block run after the gem's redaction, in standard and in strict:
116
+
117
+ ```ruby
118
+ Packrat.configure do |config|
119
+ config.redact_keys = %w[ssn account_number] # the whole value of these attributes and parameters
120
+ config.redact_patterns = [/acct \d{4}-\d{2}/] # each match, in every value and log line
121
+ config.redact { |value, name| value.gsub(Customer::NAME_PATTERN, "[name]") }
122
+ end
123
+ ```
124
+
125
+ - **`redact_keys`** replaces the value with `[REDACTED]` in a span attribute, a query parameter, a
126
+ `Rails.error` context key or a key in a structured log line. An attribute matches on its whole name
127
+ or its last segment (`ssn` matches `enduser.ssn`). Unlike `filter_parameters`, a key matches only a
128
+ whole name: `ssn` doesn't match `ssn_last4`.
129
+ - **`redact_patterns`** replaces each match with `[REDACTED]`. A string is matched literally.
130
+ - **The `redact` block** receives each string value and its attribute name (`nil` for a log line) and
131
+ returns the string to send. If it raises or returns something other than a string, the gem sends
132
+ `[REDACTED]` and logs one warning.
133
+
134
+ ### See what is sent
135
+
136
+ Set `PACKRAT_DEBUG_EXPORT=1`, or `config.debug_export = true`, and the gem prints each span and log
137
+ line to stdout as it is sent, after redaction:
138
+
139
+ ```
140
+ Packrat export: {"span":"GET /orders/:id","kind":"server","attributes":{"url.query":"token=[REDACTED]&page=2",…},"events":[]}
141
+ Packrat export: {"log":"Refund issued to [email:4f2a91c0]","severity":"INFO","attributes":{}}
142
+ ```
143
+
144
+ Everything is still sent to Packrat. `PACKRAT_DEBUG_EXPORT=0` wins over the initializer.
145
+
146
+ How long Packrat keeps your data: https://packrat.sh/docs/ruby-on-rails#how-long-data-is-kept
147
+
104
148
  ## Beside other tools
105
149
 
106
150
  - **Nothing else:** the gem configures OpenTelemetry.
@@ -18,7 +18,8 @@ module Packrat
18
18
  desc: "Turn on the Packrat plugin for Claude Code in .claude/settings.json"
19
19
 
20
20
  CLAUDE_SETTINGS = ".claude/settings.json"
21
- MARKETPLACE = { "source" => { "source" => "github", "repo" => "packratlabs/claude-plugin" } }.freeze
21
+ # Claude Code leaves a marketplace that is not Anthropic's off auto-update, and says nothing when it has a newer plugin.
22
+ MARKETPLACE = { "source" => { "source" => "github", "repo" => "packratlabs/claude-plugin" }, "autoUpdate" => true }.freeze
22
23
  PLUGIN = "packrat@packrat"
23
24
 
24
25
  def create_initializer
@@ -26,7 +27,7 @@ module Packrat
26
27
  end
27
28
 
28
29
  # Everyone who opens Claude Code in the repository and trusts the folder gets the plugin. Other
29
- # settings in the file are kept, and so is a plugin someone turned off on purpose.
30
+ # settings in the file are kept, and so is a plugin someone turned off on purpose, or auto-update turned off.
30
31
  def enable_claude_code_plugin
31
32
  return unless options[:claude_code]
32
33
 
@@ -59,7 +60,8 @@ module Packrat
59
60
 
60
61
  def settings_json(settings)
61
62
  settings = settings.dup
62
- settings["extraKnownMarketplaces"] = { "packrat" => MARKETPLACE }.merge(settings["extraKnownMarketplaces"] || {})
63
+ known = settings["extraKnownMarketplaces"] || {}
64
+ settings["extraKnownMarketplaces"] = known.merge("packrat" => MARKETPLACE.merge(known["packrat"] || {}))
63
65
  settings["enabledPlugins"] = { PLUGIN => true }.merge(settings["enabledPlugins"] || {})
64
66
  "#{JSON.pretty_generate(settings)}\n"
65
67
  end
@@ -6,7 +6,7 @@ module Packrat
6
6
  # wins: the gem fills in only what the standard variables leave empty.
7
7
  class Config
8
8
  DEFAULT_URL = "https://ingest.packrat.sh".freeze
9
- INSTRUMENTATIONS = %w[rack action_pack action_view active_job active_record net_http pg mysql2 sidekiq redis aws_sdk concurrent_ruby rake logger].freeze
9
+ INSTRUMENTATIONS = %w[rack action_pack action_view active_job net_http pg mysql2 sidekiq redis aws_sdk concurrent_ruby rake logger].freeze
10
10
  COMMIT_VARIABLES = %w[BUILD_COMMIT HEROKU_SLUG_COMMIT SOURCE_VERSION].freeze
11
11
  REDACTIONS = %w[email ip].freeze
12
12
  PRIVACY = %w[standard strict].freeze
@@ -0,0 +1,44 @@
1
+ require "active_support/isolated_execution_state"
2
+ require "active_support/notifications"
3
+
4
+ module Packrat
5
+ module Otel
6
+ # One span per query, in place of the Active Record instrumentation's span around the driver's.
7
+ # Rails names each query in the sql.active_record event its log line prints ("Order Load",
8
+ # "Order Create"), and the driver's span starts inside that event, so the driver's span takes the
9
+ # name and keeps its SQL. A query Rails did not name keeps the driver's name.
10
+ class QueryNames < OpenTelemetry::SDK::Trace::SpanProcessor
11
+ EVENT = "sql.active_record".freeze
12
+ SCOPES = %w[OpenTelemetry::Instrumentation::PG OpenTelemetry::Instrumentation::Mysql2 OpenTelemetry::Instrumentation::Trilogy].freeze
13
+ KEY = :packrat_query_names
14
+
15
+ # The sql.active_record subscriber: the name of each query in flight, innermost last.
16
+ class Names
17
+ def start(_event, _id, payload)
18
+ name = payload[:name]
19
+ Names.stack << (name unless name.nil? || name.empty?)
20
+ end
21
+
22
+ def finish(_event, _id, _payload)
23
+ Names.stack.pop
24
+ end
25
+
26
+ def self.stack
27
+ ActiveSupport::IsolatedExecutionState[KEY] ||= []
28
+ end
29
+ end
30
+
31
+ def self.install(provider)
32
+ ActiveSupport::Notifications.subscribe(EVENT, Names.new)
33
+ provider.add_span_processor(new)
34
+ end
35
+
36
+ def on_start(span, _parent_context)
37
+ return unless SCOPES.include?(span.instrumentation_scope&.name)
38
+
39
+ name = Names.stack.last
40
+ span.name = name if name
41
+ end
42
+ end
43
+ end
44
+ end
data/lib/packrat/otel.rb CHANGED
@@ -21,6 +21,8 @@ module Packrat
21
21
  BOOT_ONLY = %w[action_mailer active_storage].freeze
22
22
  ACTION_VIEW_EVENTS = %w[render_template render_partial render_collection render_layout].map { |event| "#{event}.action_view" }.freeze
23
23
  EXIT_TIMEOUT = 5
24
+ # The drivers whose spans take the name Rails gives each query (QueryNames).
25
+ QUERY_DRIVERS = %w[pg mysql2 trilogy].freeze
24
26
 
25
27
  # dogstatsd-ruby defines Datadog::Statsd without the tracer, hence the method check.
26
28
  def self.datadog?
@@ -84,6 +86,7 @@ module Packrat
84
86
  @outcome = :configured
85
87
  step("sampler") { use_sampler } unless @config.set?("OTEL_TRACES_SAMPLER")
86
88
  @config.instrumentations.each { |name| step("instrumentation #{name}") { install(name) } }
89
+ step("query names") { QueryNames.install(OpenTelemetry.tracer_provider) } if (@installed & QUERY_DRIVERS).any?
87
90
  step("Rails.error") { @errors.subscribe(ErrorSpans.new(scrubber)) }
88
91
  step("at_exit") { at_exit { shutdown_providers } }
89
92
  @line = "Packrat: sending #{signals(records)} for #{@config.service_name}/#{@config.environment} " \
@@ -1,3 +1,3 @@
1
1
  module Packrat
2
- VERSION = "0.3.0"
2
+ VERSION = "0.4.0"
3
3
  end
data/lib/packrat.rb CHANGED
@@ -6,6 +6,7 @@ require_relative "packrat/config"
6
6
  require_relative "packrat/otel/scrubber"
7
7
  require_relative "packrat/otel/error_spans"
8
8
  require_relative "packrat/otel/root_kind_sampler"
9
+ require_relative "packrat/otel/query_names"
9
10
  require_relative "packrat/otel"
10
11
  require_relative "packrat/rack_span"
11
12
  require_relative "packrat/railtie" if defined?(Rails::Railtie)
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: packrat-rails
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.3.0
4
+ version: 0.4.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Packrat Labs
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-11-07 00:00:00.000000000 Z
11
+ date: 2026-11-17 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: railties
@@ -291,6 +291,7 @@ files:
291
291
  - lib/packrat/config.rb
292
292
  - lib/packrat/otel.rb
293
293
  - lib/packrat/otel/error_spans.rb
294
+ - lib/packrat/otel/query_names.rb
294
295
  - lib/packrat/otel/root_kind_sampler.rb
295
296
  - lib/packrat/otel/scrubber.rb
296
297
  - lib/packrat/rack_span.rb