visionary-sdk 0.7.1 → 0.8.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 +501 -216
- data/lib/visionary/telemetry/sql_text.rb +1 -1
- data/lib/visionary/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: ca07d6745b2626ed4827e0c0188c3b7afe9e747c59a2feba67aa968369f28724
|
|
4
|
+
data.tar.gz: 4a3a1eeab89d64b5c91929bd8822050c38d312e388e1607848d683b599ec6d15
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: ff9130688d3060b25cea356a2f6c6ae2f891bdd5172687eb889ff8090d27c3f7704085186af4527e48ce249078d6d51c9baafbc8c331fb428cffee2c92cf55d6
|
|
7
|
+
data.tar.gz: b21edcb8f1ad0c6ceab0f65e1715af4c0f0c09156449db3dd55e3ef7cb6d90c4db8f77c792df2b38521be69b1d72ce060986c686292b57ae721c333b7c7a768e
|
data/README.md
CHANGED
|
@@ -1,298 +1,583 @@
|
|
|
1
1
|
# visionary-sdk (Ruby)
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
-
|
|
10
|
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
the database is down, the SDK only writes log lines.
|
|
18
|
-
|
|
19
|
-
Every Visionary SDK behaves the same way. The contract is
|
|
20
|
-
[`sdks/SPEC.md`](../SPEC.md).
|
|
3
|
+
Add one gem to a Rails or Rack app and every request shows up in the
|
|
4
|
+
[Visionary](../../Readme.md) dashboard: route, status, time, user, redacted
|
|
5
|
+
bodies, the database and HTTP calls it made, and any exception. You also get
|
|
6
|
+
host and process metrics, and CPU profiles when you turn them on in the
|
|
7
|
+
dashboard.
|
|
8
|
+
|
|
9
|
+
- [Quick start](#quick-start)
|
|
10
|
+
- [Integration recipes](#integration-recipes)
|
|
11
|
+
- [Choosing the database](#choosing-the-database)
|
|
12
|
+
- [Configuration reference](#configuration-reference)
|
|
13
|
+
- [Troubleshooting](#troubleshooting)
|
|
14
|
+
- [How it works](#how-it-works)
|
|
15
|
+
|
|
16
|
+
## Quick start
|
|
21
17
|
|
|
22
|
-
|
|
18
|
+
You need Ruby 3.1 or later, and a database the Visionary server also reads
|
|
19
|
+
(PostgreSQL, MySQL, a SQLite file or Cloudflare D1).
|
|
20
|
+
|
|
21
|
+
**1. Install the gem.** Add it to your Gemfile with the driver for your
|
|
22
|
+
database:
|
|
23
23
|
|
|
24
24
|
```ruby
|
|
25
25
|
# Gemfile
|
|
26
|
-
gem "visionary-sdk", require: "visionary"
|
|
26
|
+
gem "visionary-sdk", "~> 0.1", require: "visionary"
|
|
27
|
+
gem "pg" # or "mysql2", or "sqlite3"; none for D1
|
|
27
28
|
```
|
|
28
29
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
`Net::HTTP`), and an ActiveRecord app can hand over its own pool instead.
|
|
30
|
+
```sh
|
|
31
|
+
bundle install
|
|
32
|
+
```
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
The gem has no runtime dependencies of its own. In a Rails app that already
|
|
35
|
+
uses ActiveRecord you can skip the driver and
|
|
36
|
+
[write through the app's pool](#write-through-the-activerecord-pool).
|
|
35
37
|
|
|
36
|
-
|
|
38
|
+
**2. Point it at the database.** Use the same database as the Visionary
|
|
39
|
+
server:
|
|
37
40
|
|
|
38
41
|
```sh
|
|
39
|
-
export VISIONARY_DATABASE_URL=postgres://user:pass@
|
|
42
|
+
export VISIONARY_DATABASE_URL=postgres://user:pass@db.internal:5432/visionary
|
|
43
|
+
export VISIONARY_SERVICE=my-api # any name; lets several services share one database
|
|
40
44
|
```
|
|
41
45
|
|
|
46
|
+
For D1, set `D1_ACCOUNT_ID`, `D1_DATABASE_ID` and `D1_API_TOKEN` instead. See
|
|
47
|
+
[Choosing the database](#choosing-the-database).
|
|
48
|
+
|
|
49
|
+
**3. Add the middleware.**
|
|
50
|
+
|
|
51
|
+
- **Rails:** nothing to do. The gem's Railtie adds the middleware first in the
|
|
52
|
+
stack.
|
|
53
|
+
- **Any other Rack app** (Sinatra, Hanami, Roda, Grape):
|
|
54
|
+
|
|
55
|
+
```ruby
|
|
56
|
+
# config.ru
|
|
57
|
+
require "visionary"
|
|
58
|
+
use Visionary::Middleware # first, so it sees the final response
|
|
59
|
+
run MyApp
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
**4. Start the app and send a request.** Collection starts on the first
|
|
63
|
+
request (or at boot if you call `Visionary.start`). The log shows:
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
visionary: logging requests (path_prefix="", bodies=true, retention_days=0)
|
|
67
|
+
visionary: recording system metrics every 15.0s as web-1
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Tables are created on first use. At exit the SDK flushes what is queued (it
|
|
71
|
+
registers an `at_exit` hook that calls `Visionary.close`).
|
|
72
|
+
|
|
73
|
+
**5. Check the dashboard.** Open the Visionary dashboard. The request appears
|
|
74
|
+
on the API overview within a few seconds, with its route, status, time and
|
|
75
|
+
any error. Open it from Performance → Slowest requests to see its database and
|
|
76
|
+
HTTP calls on a timeline.
|
|
77
|
+
|
|
78
|
+
## Integration recipes
|
|
79
|
+
|
|
42
80
|
### Rails
|
|
43
81
|
|
|
44
|
-
Adding the gem is
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
82
|
+
**When:** any Rails app. Adding the gem is the whole integration. The Railtie:
|
|
83
|
+
|
|
84
|
+
- inserts `Visionary::Middleware` first in the middleware stack,
|
|
85
|
+
- records ActiveRecord queries as `db` spans,
|
|
86
|
+
- sees exceptions Rails turns into error pages,
|
|
87
|
+
- reads route patterns from Rails routing, and uses `Rails.logger`.
|
|
88
|
+
|
|
89
|
+
Optional extras go in an initializer:
|
|
48
90
|
|
|
49
91
|
```ruby
|
|
50
|
-
# config/initializers/visionary.rb
|
|
92
|
+
# config/initializers/visionary.rb
|
|
51
93
|
Visionary.configure do |c|
|
|
52
|
-
c.connection = ActiveRecord::Base
|
|
94
|
+
c.connection = ActiveRecord::Base # write through the app's pool instead of a URL
|
|
53
95
|
c.lookup_user = ->(id) { u = User.find_by(id: id); u && [u.email, u.role] }
|
|
54
96
|
end
|
|
55
|
-
|
|
56
|
-
# app/controllers/application_controller.rb
|
|
57
|
-
before_action { Visionary.set_user(current_user.id, handle: current_user.email, role: current_user.role) if current_user }
|
|
58
97
|
```
|
|
59
98
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
99
|
+
**What it records:**
|
|
100
|
+
|
|
101
|
+
- **Route:** the Rails route pattern without `(.:format)`, e.g.
|
|
102
|
+
`/users/:id`. Rails 7.1+ reads `request.route_uri_pattern`; older versions
|
|
103
|
+
recognize the request again.
|
|
63
104
|
- **Request id:** Visionary's id is handed to Rails, so `request.request_id`
|
|
64
105
|
and the `X-Request-ID` response header match the `api_logs` row.
|
|
65
106
|
- **Errors:** exceptions that become a 5xx response are recorded with
|
|
66
|
-
`handled = 0
|
|
107
|
+
`handled = 0`. Ones Rails maps to a 4xx (`RecordNotFound`, routing errors)
|
|
67
108
|
are not errors.
|
|
68
109
|
|
|
69
|
-
### Sinatra
|
|
110
|
+
### Sinatra, Grape and other Rack apps
|
|
111
|
+
|
|
112
|
+
**When:** any app with a `config.ru`.
|
|
70
113
|
|
|
71
114
|
```ruby
|
|
72
115
|
# config.ru
|
|
73
116
|
require "visionary"
|
|
74
|
-
use Visionary::Middleware
|
|
117
|
+
use Visionary::Middleware
|
|
75
118
|
run MyApp
|
|
76
119
|
```
|
|
77
120
|
|
|
78
|
-
Sinatra and Grape route patterns are read
|
|
79
|
-
|
|
80
|
-
|
|
121
|
+
Sinatra (`env["sinatra.route"]`) and Grape route patterns are read
|
|
122
|
+
automatically. For other routers, report the pattern so `/users/42` and
|
|
123
|
+
`/users/43` count as one route. Either call this in the handler:
|
|
124
|
+
|
|
125
|
+
```ruby
|
|
126
|
+
Visionary.set_route("/users/:id")
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
or give a resolver once:
|
|
81
130
|
|
|
82
131
|
```ruby
|
|
83
132
|
Visionary.configure { |c| c.route = ->(env) { env["my.router.pattern"] } }
|
|
84
133
|
```
|
|
85
134
|
|
|
86
|
-
|
|
135
|
+
**Records:** one `api_logs` row per request, and exceptions that escape the
|
|
136
|
+
app (recorded, then re-raised unchanged; the request is logged as 500).
|
|
137
|
+
Exceptions a framework turned into a 5xx page are found in
|
|
138
|
+
`env["sinatra.error"]`, `env["rack.exception"]` or
|
|
139
|
+
`env["action_dispatch.exception"]`.
|
|
140
|
+
|
|
141
|
+
### Attach the signed-in user
|
|
142
|
+
|
|
143
|
+
**When:** your app has logins and you want to see who made each request.
|
|
87
144
|
|
|
88
145
|
```ruby
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
Visionary.
|
|
92
|
-
|
|
93
|
-
Visionary.capture_exception(e) # a handled error (handled = 1)
|
|
94
|
-
Visionary.start # start now instead of on the first request
|
|
95
|
-
Visionary.close(10) # flush; also runs at exit
|
|
146
|
+
# Rails: app/controllers/application_controller.rb
|
|
147
|
+
before_action do
|
|
148
|
+
Visionary.set_user(current_user.id, handle: current_user.email, role: current_user.role) if current_user
|
|
149
|
+
end
|
|
96
150
|
```
|
|
97
151
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
`
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
152
|
+
Call it from any auth code (a `before_action`, a Warden callback, a Rack
|
|
153
|
+
middleware) once the user is known. Only `id` is required. To fill in handle
|
|
154
|
+
and role from the id, set `lookup_user` as in the Rails recipe. It runs on the
|
|
155
|
+
writer thread, once per distinct user per batch, only for users missing a
|
|
156
|
+
handle or role.
|
|
157
|
+
|
|
158
|
+
**Records:** `user_id`, `user_handle`, `user_role` on the request row and on
|
|
159
|
+
its errors.
|
|
160
|
+
|
|
161
|
+
### Database queries (ActiveRecord)
|
|
162
|
+
|
|
163
|
+
**When:** the app uses ActiveRecord (Rails or standalone). Nothing to add.
|
|
164
|
+
The hook is installed when the agent starts, if ActiveRecord is loaded.
|
|
165
|
+
|
|
166
|
+
**Records:** every `sql.active_record` notification, except `SCHEMA` and
|
|
167
|
+
cached queries, becomes a `db` span:
|
|
168
|
+
|
|
169
|
+
- name: the statement kind and table, e.g. `SELECT users`, `INSERT bookings`,
|
|
170
|
+
`BEGIN`;
|
|
171
|
+
- target: the adapter and database, e.g. `postgresql/shop`, `mysql/shop`,
|
|
172
|
+
`sqlite/app`;
|
|
173
|
+
- detail: the statement, sanitized (literals replaced by `?`, `IN (...)`
|
|
174
|
+
collapsed). Parameter values are never stored.
|
|
175
|
+
|
|
176
|
+
Each request row gets `db_count` and `db_ms`. Both are NULL when no database
|
|
177
|
+
hook was installed and no `db` span was recorded. Queries made with `pg`,
|
|
178
|
+
`mysql2` or `sqlite3` directly, without ActiveRecord, are not hooked; wrap
|
|
179
|
+
them in a [custom span](#custom-spans-redis-queues-cpu-work) with
|
|
180
|
+
`kind: "db"`.
|
|
181
|
+
|
|
182
|
+
### Outbound HTTP (Net::HTTP, Faraday, HTTParty)
|
|
183
|
+
|
|
184
|
+
**When:** the app calls other APIs. Nothing to add. `Net::HTTP` is hooked when
|
|
185
|
+
the agent starts, so clients built on it are covered too: Faraday's default
|
|
186
|
+
adapter, HTTParty, and others.
|
|
187
|
+
|
|
188
|
+
**Records:** an `http` span per call, named `METHOD host` (e.g.
|
|
189
|
+
`POST api.stripe.com`), with the URL without its query string as detail. A
|
|
190
|
+
5xx answer or a transport error marks the span as an error. Each request row
|
|
191
|
+
gets `http_count` and `http_ms`.
|
|
192
|
+
|
|
193
|
+
Clients that don't use `Net::HTTP` (Faraday with another adapter, `httpx`,
|
|
194
|
+
`typhoeus`) are not seen. Wrap their calls in a custom span with
|
|
195
|
+
`kind: "http"`.
|
|
196
|
+
|
|
197
|
+
### Custom spans (Redis, queues, CPU work)
|
|
198
|
+
|
|
199
|
+
**When:** time inside a request shows as **Untracked** in its breakdown. That
|
|
200
|
+
is time spent in something the SDK has no hook for: Redis, a queue client, a
|
|
201
|
+
client without `Net::HTTP`, or your own CPU work.
|
|
202
|
+
|
|
203
|
+
```ruby
|
|
204
|
+
value = Visionary.span("GET session", kind: "cache", target: "redis/sessions") do
|
|
205
|
+
redis.get(key)
|
|
206
|
+
end
|
|
207
|
+
|
|
208
|
+
Visionary.span("resize image", kind: "custom") { image.resize(800, 600) }
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
`span` returns the block's value. `kind` is `custom` (default), `cache`,
|
|
212
|
+
`queue`, `db`, `http`, `graphql` or `background`. Keep `name` low-cardinality
|
|
213
|
+
(the operation, not its arguments). `detail` is optional extra text; never
|
|
214
|
+
put secrets or parameter values in it.
|
|
215
|
+
|
|
216
|
+
**Records:** a span row with status `error` and the exception message if the
|
|
217
|
+
block raises (the exception is re-raised).
|
|
218
|
+
|
|
219
|
+
### Background work
|
|
220
|
+
|
|
221
|
+
**When:** a handler starts work it does not wait for, such as sending an email
|
|
222
|
+
after the response.
|
|
138
223
|
|
|
139
224
|
```ruby
|
|
140
225
|
Visionary.background("send welcome email") { UserMailer.welcome(user).deliver_now }
|
|
141
226
|
```
|
|
142
227
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
228
|
+
It runs the block in a new thread and returns the `Thread`.
|
|
229
|
+
|
|
230
|
+
**Records:**
|
|
231
|
+
|
|
232
|
+
- One span of kind `background` with the name you give, from start to finish.
|
|
233
|
+
If the block raises, the span is marked `error` and the exception is
|
|
234
|
+
re-raised in the thread as Ruby normally does.
|
|
147
235
|
- Calls made inside it keep the request's `request_id`, and their `offset_ms`
|
|
148
236
|
counts from the request's start, even after the response was sent. Calls
|
|
149
237
|
that end after the request was logged don't change its `db_*`/`http_*`
|
|
150
238
|
totals. They are stored whatever their duration, up to
|
|
151
|
-
`VISIONARY_SPAN_MAX`
|
|
152
|
-
|
|
239
|
+
`VISIONARY_SPAN_MAX` per request; after that only those taking at least
|
|
240
|
+
`VISIONARY_SPAN_THRESHOLD_MS`. `background` spans never count in the
|
|
153
241
|
totals.
|
|
154
|
-
- Outside a request the
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
On Ruby 3.2+ any thread or fiber started during a request inherits it, so
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
242
|
+
- Outside a request the span has no `request_id` and is stored only when it
|
|
243
|
+
takes at least `VISIONARY_SPAN_THRESHOLD_MS`.
|
|
244
|
+
|
|
245
|
+
On Ruby 3.2+ any thread or fiber started during a request inherits it, so a
|
|
246
|
+
plain `Thread.new` is attributed too. `background` also carries the request
|
|
247
|
+
over on 3.1, and adds the span around the work.
|
|
248
|
+
|
|
249
|
+
### Errors
|
|
250
|
+
|
|
251
|
+
**When:** always on. Exceptions that escape the app, or that the framework
|
|
252
|
+
turned into a 5xx page, are recorded with `handled = 0`. To record one you
|
|
253
|
+
rescued:
|
|
254
|
+
|
|
255
|
+
```ruby
|
|
256
|
+
begin
|
|
257
|
+
charge!(order)
|
|
258
|
+
rescue PaymentError => e
|
|
259
|
+
Visionary.capture_exception(e) # handled = 1, linked to the current request
|
|
260
|
+
render status: 402
|
|
261
|
+
end
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
**Records:** an `errors` row with the type, message and stack. Errors are
|
|
265
|
+
grouped by a fingerprint over the exception class and the top five frames of
|
|
266
|
+
your own code (not gems, the standard library or this SDK), as `method@path`
|
|
267
|
+
relative to the working directory, so the group stays the same across deploys
|
|
268
|
+
and line changes. At most 20 rows per fingerprint per minute are written.
|
|
269
|
+
|
|
270
|
+
### Error codes from JSON responses
|
|
271
|
+
|
|
272
|
+
**When:** your API answers errors with a JSON body like
|
|
273
|
+
`{"error": {"code": "card_declined", "key": "payment.declined"}}`.
|
|
274
|
+
|
|
275
|
+
Nothing to add for that shape. For another shape, set the dotted paths:
|
|
276
|
+
|
|
277
|
+
```sh
|
|
278
|
+
VISIONARY_LOG_ERROR_CODE_FIELD=errors.0.code
|
|
279
|
+
VISIONARY_LOG_ERROR_KEY_FIELD=errors.0.key
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
**Records:** `error_code` and `error_key` on requests with status 400 or
|
|
283
|
+
above.
|
|
284
|
+
|
|
285
|
+
### Write through the ActiveRecord pool
|
|
286
|
+
|
|
287
|
+
**When:** a Rails app that wants Visionary's tables in its own database,
|
|
288
|
+
without a second connection setup.
|
|
289
|
+
|
|
290
|
+
```ruby
|
|
291
|
+
# config/initializers/visionary.rb
|
|
292
|
+
Visionary.configure { |c| c.connection = ActiveRecord::Base }
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Any abstract connection class works, for example one with its own
|
|
296
|
+
`connects_to` database. Each write checks a connection out of that pool on
|
|
297
|
+
the background thread and returns it right after; Visionary uses at most one
|
|
298
|
+
pool connection at a time. The adapter must be PostgreSQL, MySQL (or
|
|
299
|
+
Trilogy) or SQLite.
|
|
300
|
+
|
|
301
|
+
### Puma and Unicorn (forking servers)
|
|
302
|
+
|
|
303
|
+
**When:** Puma in cluster mode or Unicorn, especially with `preload_app!`.
|
|
304
|
+
|
|
305
|
+
Threads don't survive `fork`. Visionary hooks `Process._fork`, so when
|
|
306
|
+
workers are forked after the agent started, each worker restarts its writer,
|
|
307
|
+
sampler, profiler and retention threads with fresh queues and connections.
|
|
308
|
+
Without an explicit `Visionary.start`, each worker starts collection on its
|
|
309
|
+
first request and nothing runs in the master.
|
|
310
|
+
|
|
311
|
+
To be explicit, add Puma's hooks. They are safe to combine with the automatic
|
|
312
|
+
restart:
|
|
313
|
+
|
|
314
|
+
```ruby
|
|
315
|
+
# config/puma.rb
|
|
316
|
+
on_worker_boot { Visionary.after_fork }
|
|
317
|
+
on_worker_shutdown { Visionary.close }
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
### Start and stop by hand
|
|
321
|
+
|
|
322
|
+
**When:** you want collection to start at boot (so system metrics begin
|
|
323
|
+
before the first request), or you run a script or job runner.
|
|
324
|
+
|
|
325
|
+
```ruby
|
|
326
|
+
Visionary.start # start now instead of on the first request
|
|
327
|
+
# ...
|
|
328
|
+
Visionary.close(10) # flush, waiting at most 10 seconds; also runs at exit
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
`start` never raises. On any problem it logs a warning and collection is off.
|
|
332
|
+
|
|
333
|
+
### Database pool metrics
|
|
334
|
+
|
|
335
|
+
**When:** you want the `db_*` pool columns of `system_metrics` filled.
|
|
336
|
+
|
|
337
|
+
With ActiveRecord loaded, they come from its pool. For another pool, return
|
|
338
|
+
its numbers:
|
|
339
|
+
|
|
340
|
+
```ruby
|
|
341
|
+
Visionary.configure do |c|
|
|
342
|
+
c.db_stats = -> { { total: pool.size, idle: pool.idle, in_use: pool.busy, max: pool.max } }
|
|
343
|
+
end
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
Optional cumulative keys: `acquires`, `empty_acquires`, `acquire_wait_ms`.
|
|
347
|
+
|
|
348
|
+
### CPU profiles
|
|
349
|
+
|
|
350
|
+
**When:** you want to see where CPU time goes. Nothing to add in code.
|
|
351
|
+
|
|
352
|
+
1. In the dashboard, open **Settings → Profiling** and turn it on. Pick the
|
|
353
|
+
services (matched by `VISIONARY_SERVICE`), the interval (default every
|
|
354
|
+
300 s) and the duration (default 10 s).
|
|
355
|
+
2. Within 30 s the app logs
|
|
356
|
+
`visionary: CPU profiling on (10000 ms every 300s)`.
|
|
357
|
+
3. Profiles appear on the CPU profiles page. **Profile now** takes one within
|
|
358
|
+
30 s.
|
|
359
|
+
|
|
360
|
+
Turn it off in the same place; no redeploy either way. To keep a service out
|
|
170
361
|
of profiling whatever the dashboard says, set `VISIONARY_PROFILE=false`.
|
|
171
362
|
|
|
363
|
+
**Records:** one `profiles` row per profile, with `folded` stacks and
|
|
364
|
+
`routes` (the milliseconds per `METHOD route` for requests that finished
|
|
365
|
+
during the profile). See [How profiling works](#how-profiling-works).
|
|
366
|
+
|
|
367
|
+
### Query plans (Explain)
|
|
368
|
+
|
|
369
|
+
The Ruby SDK has no explainer. It does not answer **Explain** on the Queries
|
|
370
|
+
page. See [Troubleshooting](#troubleshooting).
|
|
371
|
+
|
|
372
|
+
## Choosing the database
|
|
373
|
+
|
|
374
|
+
The app and the Visionary server must point at the same database. The first
|
|
375
|
+
match wins:
|
|
376
|
+
|
|
377
|
+
| Setting | Backend | Driver gem |
|
|
378
|
+
|---|---|---|
|
|
379
|
+
| `c.connection = ActiveRecord::Base` | the app's ActiveRecord pool (PostgreSQL, MySQL/Trilogy, SQLite) | the app's adapter |
|
|
380
|
+
| `VISIONARY_DATABASE_URL=postgres://user:pass@host:5432/db` (or `postgresql://`) | PostgreSQL | `pg` |
|
|
381
|
+
| `VISIONARY_DATABASE_URL=mysql://user:pass@host:3306/db` (or `mysql2://`) | MySQL | `mysql2` |
|
|
382
|
+
| `VISIONARY_DATABASE_URL=sqlite:///absolute/path.db` | SQLite, absolute path | `sqlite3` |
|
|
383
|
+
| `VISIONARY_DATABASE_URL=sqlite://relative.db` | SQLite, relative to the working directory | `sqlite3` |
|
|
384
|
+
| `D1_ACCOUNT_ID`, `D1_DATABASE_ID`, `D1_API_TOKEN` (optionally `VISIONARY_DATABASE_URL=d1://`) | Cloudflare D1 over HTTPS | none (`Net::HTTP`) |
|
|
385
|
+
|
|
386
|
+
Notes:
|
|
387
|
+
|
|
388
|
+
- On Windows, write an absolute SQLite path as
|
|
389
|
+
`sqlite:///C:/data/visionary.db`.
|
|
390
|
+
- With a URL, Visionary opens one connection of its own and reopens it after
|
|
391
|
+
errors.
|
|
392
|
+
- For D1, `D1_API_BASE` replaces `https://api.cloudflare.com/client/v4`, for
|
|
393
|
+
a proxy.
|
|
394
|
+
- The tables (`api_logs`, `system_metrics`, `spans`, `errors`, `releases`)
|
|
395
|
+
are created on first use, and tables from older versions gain the newer
|
|
396
|
+
columns. `profiles` and `visionary_settings` are created by the Visionary
|
|
397
|
+
server.
|
|
398
|
+
- SQLite and D1 suit modest traffic. For thousands of requests a second, use
|
|
399
|
+
PostgreSQL or MySQL.
|
|
400
|
+
|
|
401
|
+
## Configuration reference
|
|
402
|
+
|
|
403
|
+
Every option comes from the environment. `Visionary.configure` sets the same
|
|
404
|
+
options in code, plus the hooks below. Set them before the first request
|
|
405
|
+
(for example in an initializer). Booleans accept `true/false/1/0/yes/no`.
|
|
406
|
+
|
|
407
|
+
| Variable | `Visionary.configure` | Default | What it does |
|
|
408
|
+
|---|---|---|---|
|
|
409
|
+
| `VISIONARY_DATABASE_URL` | `database_url` | none | Where rows go; see [Choosing the database](#choosing-the-database) |
|
|
410
|
+
| `D1_ACCOUNT_ID`, `D1_DATABASE_ID`, `D1_API_TOKEN` | `d1_account_id`, `d1_database_id`, `d1_api_token` | none | Cloudflare D1 credentials |
|
|
411
|
+
| `D1_API_BASE` | `d1_api_base` | Cloudflare's API | D1 API URL, for a proxy |
|
|
412
|
+
| `VISIONARY_INSTANCE` | `instance` | hostname | Labels this process's rows |
|
|
413
|
+
| `VISIONARY_SERVICE` | `service` | NULL | Service name; lets several services share a database |
|
|
414
|
+
| `VISIONARY_RELEASE` | `version` | the platform's commit variable | Release for the deploy marker; hashes are cut to 12 characters |
|
|
415
|
+
| `VISIONARY_LOG_REQUESTS` | `log_requests` | `true` | Write one `api_logs` row per request |
|
|
416
|
+
| `VISIONARY_LOG_PATH_PREFIX` | `path_prefix` | empty (everything) | Log only paths starting with this, e.g. `/api` |
|
|
417
|
+
| `VISIONARY_LOG_BODIES` | `capture_bodies` | `true` | Store redacted request and response bodies |
|
|
418
|
+
| `VISIONARY_LOG_MAX_BODY_BYTES` | `max_body_bytes` | `8192` | Capture cap per body |
|
|
419
|
+
| `VISIONARY_LOG_REDACT_HEADERS` | `redact_headers` | empty | Comma list of extra headers to redact |
|
|
420
|
+
| `VISIONARY_LOG_REDACT_FIELDS` | `redact_fields` | empty | Comma list of extra JSON/form keys to redact in both bodies |
|
|
421
|
+
| `VISIONARY_LOG_REDACT_REQUEST_FIELDS` | `redact_request_fields` | empty | Comma list of keys to redact in request bodies only |
|
|
422
|
+
| `VISIONARY_LOG_ERROR_CODE_FIELD` | `error_code_field` | `error.code` | Dotted path to the error code in JSON error bodies |
|
|
423
|
+
| `VISIONARY_LOG_ERROR_KEY_FIELD` | `error_key_field` | `error.key` | Dotted path to the error key |
|
|
424
|
+
| `VISIONARY_LOG_RETENTION_DAYS` | `log_retention_days` | `0` (off) | Above 0, the SDK also deletes older `api_logs`, `spans`, `errors` and `profiles` rows |
|
|
425
|
+
| `VISIONARY_SYSTEM_METRICS` | `system_metrics` | `true` | Write `system_metrics` samples |
|
|
426
|
+
| `VISIONARY_SYSTEM_INTERVAL` | `system_interval` (seconds) | `15s` | Sample interval: `15`, `15s`, `500ms`, `1m`, `1h` |
|
|
427
|
+
| `VISIONARY_SYSTEM_RETENTION_DAYS` | `system_retention_days` | `0` (off) | Above 0, the SDK also deletes older `system_metrics` rows |
|
|
428
|
+
| `VISIONARY_SPANS` | `spans` | `true` | Record database, HTTP and custom spans, and per-request totals |
|
|
429
|
+
| `VISIONARY_SPAN_THRESHOLD_MS` | `span_threshold_ms` | `100` | Spans outside a request (or past `SPAN_MAX`) are kept when at least this slow |
|
|
430
|
+
| `VISIONARY_SPAN_MAX` | `span_max` | `100` | Span rows stored per request |
|
|
431
|
+
| `VISIONARY_ERRORS` | `errors` | `true` | Record exceptions |
|
|
432
|
+
| `VISIONARY_PROFILE` | `profile` | `true` | Follow the dashboard's Profiling setting; `false` never profiles |
|
|
433
|
+
|
|
434
|
+
If `VISIONARY_RELEASE` is unset, the release is read from the first of
|
|
435
|
+
`RAILWAY_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT`, `VERCEL_GIT_COMMIT_SHA`,
|
|
436
|
+
`HEROKU_SLUG_COMMIT`, `SOURCE_VERSION`, `GIT_COMMIT`, `GITHUB_SHA`,
|
|
437
|
+
`K_REVISION`.
|
|
438
|
+
|
|
439
|
+
Old rows are normally deleted by the Visionary server, following Settings →
|
|
440
|
+
Retention in the dashboard. The two `*_RETENTION_DAYS` options only matter
|
|
441
|
+
when the service writes to a database no Visionary server reads.
|
|
442
|
+
|
|
443
|
+
Options only available in code:
|
|
444
|
+
|
|
445
|
+
| `Visionary.configure` | Default | What it does |
|
|
446
|
+
|---|---|---|
|
|
447
|
+
| `connection` | nil | An ActiveRecord connection class to write through |
|
|
448
|
+
| `logger` | `Rails.logger` in Rails, else stderr | Where the SDK logs |
|
|
449
|
+
| `lookup_user` | nil | `->(id) { [handle, role] }`, fills in missing user details |
|
|
450
|
+
| `route` | nil | `->(env) { "/users/:id" }`, route pattern for routers the SDK can't see |
|
|
451
|
+
| `db_stats` | the ActiveRecord pool | `-> { { total:, idle:, in_use:, max: } }`, pool metrics |
|
|
452
|
+
| `disk_path` | working directory | Filesystem whose usage is reported |
|
|
453
|
+
| `queue_size` | `5000` | Rows queued before new ones are dropped |
|
|
454
|
+
| `batch_size` | `50` | Rows per write (1 to 50) |
|
|
455
|
+
| `flush_interval` | `3.0` | Seconds between writes when the batch isn't full |
|
|
456
|
+
|
|
457
|
+
Always redacted: the headers `Authorization`, `Proxy-Authorization`,
|
|
458
|
+
`Cookie`, `Set-Cookie`, `X-Api-Key`, `X-Auth-Token`, and the body keys
|
|
459
|
+
`password`, `passwd`, `secret`, `client_secret`, `token`, `access_token`,
|
|
460
|
+
`refresh_token`, `id_token`, `api_key`, `apikey`, `otp`, `pin`,
|
|
461
|
+
`card_number`, `cvv`, `private_key`.
|
|
462
|
+
|
|
463
|
+
## Troubleshooting
|
|
464
|
+
|
|
465
|
+
| Symptom | Cause | Fix |
|
|
466
|
+
|---|---|---|
|
|
467
|
+
| Nothing shows up, and the log says `visionary: no database configured (set VISIONARY_DATABASE_URL or D1_*); collection is off` | The variables aren't set in the process that runs the app | Set `VISIONARY_DATABASE_URL` (or all three `D1_*`) where the app runs, then restart it |
|
|
468
|
+
| Nothing shows up, and there is no `visionary:` line at all | Collection starts on the first request; or the middleware isn't in the stack (not Rails, no `use Visionary::Middleware`) | Send a request, or call `Visionary.start` at boot. In a Rack app, add `use Visionary::Middleware` to `config.ru` |
|
|
469
|
+
| `visionary: unsupported database URL scheme ...` or a `LoadError` for `pg`, `mysql2` or `sqlite3` | Wrong scheme, or the driver gem is missing | Use one of the URLs in [Choosing the database](#choosing-the-database) and add the driver to the Gemfile |
|
|
470
|
+
| Rows are written but the dashboard is empty | The app and the server use different databases, or the dashboard filters another service | Point both at the same database. Check `VISIONARY_SERVICE` and the service filter |
|
|
471
|
+
| Some requests are missing | `VISIONARY_LOG_PATH_PREFIX` excludes them | Clear it or widen the prefix |
|
|
472
|
+
| Requests have no route, so `/users/42` and `/users/43` aren't grouped as `/users/:id` | The router isn't Rails, Sinatra or Grape | Call `Visionary.set_route` or set `c.route` |
|
|
473
|
+
| A request's breakdown is mostly **Untracked** | Its time goes to a client the SDK doesn't hook (Redis, non-`Net::HTTP` HTTP, raw `pg`) or to CPU work | Wrap those calls in [`Visionary.span`](#custom-spans-redis-queues-cpu-work) |
|
|
474
|
+
| **Explain** on the Queries page stays pending forever ("No SDK has picked this up") | The Ruby SDK has no explainer, so it never answers Explain requests | Plans come only from a service running an SDK with an explainer (Go or Node) for the same database. Its explainer target must match the span's target, e.g. `postgresql/<dbname>` |
|
|
475
|
+
| CPU profiles missing | Profiling is off in the dashboard, the service isn't in its service list, or `VISIONARY_PROFILE=false` | Turn it on in **Settings → Profiling** and check the service list. Wait for `visionary: CPU profiling on ...` in the log. A scheduled turn is skipped when no request arrived since the last one |
|
|
476
|
+
| `visionary: profiling settings unreadable (...); profiling stays off` | The Visionary server hasn't created `visionary_settings` yet in this database | Start the server against the same database |
|
|
477
|
+
| `visionary: batch write failed; ... entries dropped: d1: status ...: ... exceeded D1's free tier daily row read limit` | The D1 database hit Cloudflare's free-tier daily limit | Wait for the daily reset or move to the Workers Paid plan. To use less, log only `/api` (`VISIONARY_LOG_PATH_PREFIX`), raise `VISIONARY_SYSTEM_INTERVAL`, or switch to PostgreSQL or MySQL |
|
|
478
|
+
| `visionary: queue full; N entries dropped` | Writes can't keep up with traffic (common on SQLite and D1) | Use PostgreSQL or MySQL, or log fewer paths or no bodies |
|
|
479
|
+
| Rows lost on shutdown, or `visionary: log flush timed out; N pending` | The process was killed before the queue was flushed | Let the process exit normally (`at_exit` calls `Visionary.close`). In Puma, add `on_worker_shutdown { Visionary.close }`. In scripts, call `Visionary.close` before exiting |
|
|
480
|
+
| Nothing from Puma or Unicorn workers | The agent started in the master before `fork`, and the restart failed | Look for `visionary: restart after fork failed`. Add `on_worker_boot { Visionary.after_fork }` |
|
|
481
|
+
| A request body is empty in the log | Bodies are captured as the app reads them; the app never read it | Expected. The size is still stored, from `Content-Length` |
|
|
482
|
+
|
|
483
|
+
## How it works
|
|
484
|
+
|
|
485
|
+
All slow work runs on background threads, so requests are never blocked or
|
|
486
|
+
slowed. If the database is down, the SDK only writes log lines. Every
|
|
487
|
+
Visionary SDK follows the same contract,
|
|
488
|
+
[`sdks/SPEC.md`](../SPEC.md).
|
|
489
|
+
|
|
490
|
+
### What is written
|
|
491
|
+
|
|
492
|
+
- `api_logs`: one row per request: method, route pattern, status, timing,
|
|
493
|
+
user, redacted headers and bodies, error codes, and `db_count`, `db_ms`,
|
|
494
|
+
`http_count`, `http_ms`.
|
|
495
|
+
- `spans`: database, outbound HTTP, custom and background spans. Rows are
|
|
496
|
+
stored for every request, at most `VISIONARY_SPAN_MAX` per request. Spans
|
|
497
|
+
outside requests are stored when they take at least
|
|
498
|
+
`VISIONARY_SPAN_THRESHOLD_MS`. Visionary's own writes never become spans.
|
|
499
|
+
- `errors`: exceptions, grouped by fingerprint.
|
|
500
|
+
- `releases`: one row per process start, when the release is known.
|
|
501
|
+
- `system_metrics`: a sample every `VISIONARY_SYSTEM_INTERVAL`.
|
|
502
|
+
- `profiles`: CPU profiles, only while they are on in the dashboard.
|
|
503
|
+
|
|
504
|
+
Request bodies are captured as the app reads them. Multipart, image, video,
|
|
505
|
+
audio, octet-stream, zip and PDF bodies are not captured.
|
|
506
|
+
|
|
507
|
+
The request is kept in fiber storage (Ruby 3.2+, inherited by child fibers
|
|
508
|
+
and threads) or a fiber-local variable on 3.1, so `set_user`, `set_route` and
|
|
509
|
+
spans work under Puma, Falcon and in Async tasks.
|
|
510
|
+
|
|
511
|
+
### System metrics
|
|
512
|
+
|
|
513
|
+
On Linux the host and node columns come from `/proc` (CPU split, load,
|
|
514
|
+
memory, swap, disk I/O, network, TCP, processes, context switches) and `df`
|
|
515
|
+
(disk usage). Process CPU comes from `Process.clock_gettime`, GC count and
|
|
516
|
+
time from `GC.stat`, heap from `GC.stat` slot and page counts, threads from
|
|
517
|
+
`/proc/self/status` (else `Thread.list`). Pool columns come from the
|
|
518
|
+
ActiveRecord pool, or from `c.db_stats`. On macOS and Windows most host
|
|
519
|
+
columns are NULL. In a container (or a cgroup with a CPU or memory limit) the
|
|
520
|
+
`container_*` columns come from the process's own cgroup, v2 or v1: CPU used,
|
|
521
|
+
limit and throttling, memory used (without inactive page cache) and limit,
|
|
522
|
+
OOM kills.
|
|
523
|
+
|
|
524
|
+
### How profiling works
|
|
525
|
+
|
|
526
|
+
The SDK reads the switch from the `visionary_settings` table at start and
|
|
527
|
+
every 30 s after that, on its own thread, and logs one line when profiling
|
|
528
|
+
turns on or off.
|
|
529
|
+
|
|
172
530
|
While a profile runs, a thread wakes about every 10 ms and takes the stack of
|
|
173
531
|
each app thread whose status is `run`. Threads that sleep, wait on a lock or
|
|
174
532
|
queue, or block on IO (a database or HTTP call) have the status `sleep`, so
|
|
175
|
-
they are left out, and so are Visionary's own threads.
|
|
176
|
-
profile:
|
|
533
|
+
they are left out, and so are Visionary's own threads.
|
|
177
534
|
|
|
178
535
|
- `folded`: one `frame;frame;... count` line per distinct stack, outermost
|
|
179
536
|
call first. Each sample counts about 10 ms of CPU. Frames read
|
|
180
537
|
`Class#method file:line`. Your code's paths are relative to the working
|
|
181
|
-
directory. Gems
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
one `(other)` line.
|
|
538
|
+
directory. Gems read `lib:<gem>/<path>` (e.g. `lib:rack/rack/builder.rb`),
|
|
539
|
+
the standard library `std:<path>` (e.g. `std:json/common.rb`). Each row is
|
|
540
|
+
capped at 90 000 bytes; the lightest stacks are summed into one `(other)`
|
|
541
|
+
line.
|
|
186
542
|
- `routes`: the milliseconds that the requests finishing during the profile
|
|
187
543
|
took, per `METHOD route`.
|
|
188
544
|
|
|
189
545
|
A turn is skipped when no request arrived since the last one. A scheduled
|
|
190
|
-
profile
|
|
191
|
-
|
|
192
|
-
|
|
546
|
+
profile with fewer than 20 samples (about 200 ms of CPU) is dropped, and kept
|
|
547
|
+
otherwise even when no request finished during it (`routes` is then `{}`). A
|
|
548
|
+
**Profile now** one is kept with any samples.
|
|
193
549
|
|
|
194
|
-
**Cost:** nothing while profiling is off apart from the settings read every
|
|
195
|
-
30 s. While a profile runs,
|
|
196
|
-
second, which costs a few percent of one CPU.
|
|
550
|
+
**Cost:** nothing while profiling is off, apart from the settings read every
|
|
551
|
+
30 s. While a profile runs, a few percent of one CPU.
|
|
197
552
|
|
|
198
|
-
**
|
|
199
|
-
|
|
553
|
+
**Accuracy.** Ruby has no built-in CPU sampler, so these are wall-clock
|
|
554
|
+
samples of runnable threads:
|
|
200
555
|
|
|
201
556
|
- Only the thread holding the GVL really runs. Several busy threads are each
|
|
202
557
|
counted, so time spent waiting for the GVL counts as CPU.
|
|
203
558
|
- A thread computing in Ruby keeps the GVL for up to 100 ms while the sampler
|
|
204
|
-
waits for it.
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
quantum
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
within a few ms (short bursts between IO calls) is still under-counted.
|
|
559
|
+
waits for it. So while a profile runs, the SDK lowers the app's threads to
|
|
560
|
+
Ruby's lowest thread priority (`-3`, a 12.5 ms quantum) and gives each
|
|
561
|
+
thread its own priority back afterwards. In CRuby, priority sets only this
|
|
562
|
+
quantum, so no thread gains on another. A late sample counts for the 10 ms
|
|
563
|
+
ticks it missed. Code that gives up the GVL within a few ms is still
|
|
564
|
+
under-counted.
|
|
211
565
|
- A C extension that releases the GVL to do work (some database drivers,
|
|
212
566
|
compression) keeps the status `run`. Its time shows on the Ruby frame that
|
|
213
567
|
called it.
|
|
214
568
|
- C methods (`Array#each`, `Time#strftime`) show the file and line of the Ruby
|
|
215
569
|
code that called them.
|
|
216
570
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
Threads don't survive `fork`. Visionary hooks `Process._fork` (Ruby 3.1+), so
|
|
220
|
-
when Puma or Unicorn forks workers after the agent started (for example with
|
|
221
|
-
`preload_app!` and an initializer that calls `Visionary.start`), each worker
|
|
222
|
-
restarts its writer, sampler, profiler and retention threads with fresh queues and
|
|
223
|
-
connections. If you prefer to be explicit, Puma's hook does the same and is
|
|
224
|
-
safe to combine with it:
|
|
571
|
+
### API summary
|
|
225
572
|
|
|
226
573
|
```ruby
|
|
227
|
-
#
|
|
228
|
-
|
|
229
|
-
|
|
574
|
+
Visionary.set_user(id, handle: nil, role: nil) # the signed-in user of the current request
|
|
575
|
+
Visionary.set_route("/users/:id") # route pattern, for routers Visionary can't see
|
|
576
|
+
Visionary.span(name, kind: "custom", target: nil, detail: nil) { ... } # a manual span
|
|
577
|
+
Visionary.background(name) { ... } # a thread that stays with the request
|
|
578
|
+
Visionary.capture_exception(e) # a handled error (handled = 1)
|
|
579
|
+
Visionary.configure { |c| ... } # options and hooks, before the first request
|
|
580
|
+
Visionary.start # start now instead of on the first request
|
|
581
|
+
Visionary.after_fork # restart threads in a forked worker
|
|
582
|
+
Visionary.close(10) # flush; also runs at exit
|
|
230
583
|
```
|
|
231
|
-
|
|
232
|
-
Without an explicit start, each worker starts collection on its first
|
|
233
|
-
request, and nothing runs in the master.
|
|
234
|
-
|
|
235
|
-
## Choosing the database
|
|
236
|
-
|
|
237
|
-
In this order:
|
|
238
|
-
|
|
239
|
-
1. `Visionary.config.connection = ActiveRecord::Base` (or any abstract
|
|
240
|
-
connection class, e.g. one with its own `connects_to` database). Each write
|
|
241
|
-
checks a connection out of that pool on the background thread and returns
|
|
242
|
-
it right after; Visionary uses at most one pool connection at a time.
|
|
243
|
-
2. `VISIONARY_DATABASE_URL`: `postgres://` / `postgresql://` (gem `pg`),
|
|
244
|
-
`mysql://` (gem `mysql2`), `sqlite:///absolute/path.db` or
|
|
245
|
-
`sqlite://relative.db` (gem `sqlite3`). Visionary opens one connection of
|
|
246
|
-
its own and reopens it after errors.
|
|
247
|
-
3. Cloudflare D1: `D1_ACCOUNT_ID`, `D1_DATABASE_ID`, `D1_API_TOKEN` (and
|
|
248
|
-
`D1_API_BASE` for a proxy), or `VISIONARY_DATABASE_URL=d1://` with those.
|
|
249
|
-
|
|
250
|
-
The tables (`api_logs`, `system_metrics`, `spans`, `errors`, `releases`) are
|
|
251
|
-
created on first use, and tables from older versions gain the newer columns.
|
|
252
|
-
With no database configured, Visionary logs one warning and does nothing.
|
|
253
|
-
|
|
254
|
-
## System metrics
|
|
255
|
-
|
|
256
|
-
Every `VISIONARY_SYSTEM_INTERVAL` a sample is written (four per batch). On
|
|
257
|
-
Linux the host and node columns come from `/proc` (CPU split, load, memory,
|
|
258
|
-
swap, disk I/O, network, TCP, processes, context switches) and `df` (disk
|
|
259
|
-
usage). Process CPU comes from `Process.clock_gettime`, GC count and time
|
|
260
|
-
from `GC.stat`, heap from `GC.stat` slot and page counts, threads from
|
|
261
|
-
`/proc/self/status` (else `Thread.list`). Pool columns come from the
|
|
262
|
-
ActiveRecord pool when it exists, or from `c.db_stats = -> { { total:, idle:,
|
|
263
|
-
in_use:, max: } }`. On macOS and Windows most host columns are NULL.
|
|
264
|
-
In a container (or a cgroup with a CPU or memory limit) the `container_*`
|
|
265
|
-
columns come from the process's own cgroup, v2 or v1: CPU used, limit and
|
|
266
|
-
throttling, memory used (without inactive page cache) and limit, OOM kills.
|
|
267
|
-
|
|
268
|
-
## Configuration
|
|
269
|
-
|
|
270
|
-
Everything comes from the environment (see the table in
|
|
271
|
-
[`sdks/SPEC.md`](../SPEC.md#environment)); `Visionary.configure` sets the same
|
|
272
|
-
options in code (`c.path_prefix = "/api"`, `c.capture_bodies = false`, ...)
|
|
273
|
-
plus the hooks above. Set it before the first request.
|
|
274
|
-
|
|
275
|
-
| Variable | Default |
|
|
276
|
-
|---|---|
|
|
277
|
-
| `VISIONARY_DATABASE_URL` | — |
|
|
278
|
-
| `VISIONARY_INSTANCE` | hostname |
|
|
279
|
-
| `VISIONARY_LOG_REQUESTS`, `VISIONARY_LOG_BODIES` | `true` |
|
|
280
|
-
| `VISIONARY_LOG_PATH_PREFIX` | everything |
|
|
281
|
-
| `VISIONARY_LOG_MAX_BODY_BYTES` | `8192` |
|
|
282
|
-
| `VISIONARY_LOG_RETENTION_DAYS`, `VISIONARY_SYSTEM_RETENTION_DAYS` | `0` (off; above 0 the SDK also deletes older rows) |
|
|
283
|
-
| `VISIONARY_LOG_REDACT_HEADERS`, `_REDACT_FIELDS`, `_REDACT_REQUEST_FIELDS` | added to the defaults |
|
|
284
|
-
| `VISIONARY_LOG_ERROR_CODE_FIELD`, `_ERROR_KEY_FIELD` | `error.code`, `error.key` |
|
|
285
|
-
| `VISIONARY_SYSTEM_METRICS` | `true` |
|
|
286
|
-
| `VISIONARY_SYSTEM_INTERVAL` | `15s` |
|
|
287
|
-
| `VISIONARY_SERVICE` | NULL |
|
|
288
|
-
| `VISIONARY_RELEASE` | the platform's commit variable, shortened to 12 characters |
|
|
289
|
-
| `VISIONARY_SPANS`, `VISIONARY_ERRORS` | `true` |
|
|
290
|
-
| `VISIONARY_SPAN_THRESHOLD_MS`, `VISIONARY_SPAN_MAX` | `100`, `100` |
|
|
291
|
-
| `VISIONARY_PROFILE` | `true`: follow the dashboard's Profiling setting; `false` never profiles |
|
|
292
|
-
|
|
293
|
-
Old rows are deleted by the Visionary server, following Settings → Retention in
|
|
294
|
-
the dashboard. The two `*_RETENTION_DAYS` variables only matter when the
|
|
295
|
-
service writes to a database no Visionary server reads.
|
|
296
|
-
|
|
297
|
-
Request bodies are captured as the app reads them, so a body the app never
|
|
298
|
-
reads is not stored (its size still is, from `Content-Length`).
|
data/lib/visionary/version.rb
CHANGED