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 +4 -4
- data/README.md +52 -8
- data/lib/generators/packrat/packrat_generator.rb +5 -3
- data/lib/packrat/config.rb +1 -1
- data/lib/packrat/otel/query_names.rb +44 -0
- data/lib/packrat/otel.rb +3 -0
- data/lib/packrat/version.rb +1 -1
- data/lib/packrat.rb +1 -0
- metadata +3 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 5daf74b5d37211409de14b6a43c130e01df37a71d255aa7407b0bb1bc78a0917
|
|
4
|
+
data.tar.gz: d7cff3b8ebe3dcd6cbae6a772ee666d9fc0dab95ad4708a7ec49557aaed7f684
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
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,
|
|
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
|
-
|
|
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`, `
|
|
57
|
-
`
|
|
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
|
|
100
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
data/lib/packrat/config.rb
CHANGED
|
@@ -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
|
|
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} " \
|
data/lib/packrat/version.rb
CHANGED
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.
|
|
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-
|
|
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
|