tlm 0.1.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 +7 -0
- data/CHANGELOG.md +36 -0
- data/LICENSE +21 -0
- data/README.md +159 -0
- data/lib/tlm/active_job.rb +30 -0
- data/lib/tlm/backtrace.rb +118 -0
- data/lib/tlm/breadcrumbs.rb +22 -0
- data/lib/tlm/config.rb +121 -0
- data/lib/tlm/context.rb +53 -0
- data/lib/tlm/event.rb +88 -0
- data/lib/tlm/heartbeat.rb +74 -0
- data/lib/tlm/http.rb +43 -0
- data/lib/tlm/job_args.rb +36 -0
- data/lib/tlm/rack.rb +103 -0
- data/lib/tlm/railtie.rb +98 -0
- data/lib/tlm/sender.rb +298 -0
- data/lib/tlm/sidekiq.rb +58 -0
- data/lib/tlm/source.rb +44 -0
- data/lib/tlm/tasks.rb +10 -0
- data/lib/tlm/test_command.rb +56 -0
- data/lib/tlm/text.rb +21 -0
- data/lib/tlm/version.rb +3 -0
- data/lib/tlm.rb +209 -0
- metadata +64 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: b9bf4922845acd465c32adba465eb5427917f9bd0bcb200f9f3f881e9693463c
|
|
4
|
+
data.tar.gz: 0ac16b2c2da3f24e07323a5439a2f45e37e5498f827d08c53c7f63453a03b739
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 5bf4b6bf6a266291291b27a9dc97ac31dc102c120374314af9498186f873d309a41ef61eabc46c47776b460698acdda991a789e101672682c0526457d39559a6
|
|
7
|
+
data.tar.gz: 6ef4c1f0a0f660e0a4494d97d2eccbc310183758c1c06c4a1be91cfa02205b59d2d6a2cf289938993a71c1f17605c7d0bcaab6d0c2a273c93558818a9bb8a88b
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
First release.
|
|
6
|
+
|
|
7
|
+
- Reports errors from Rails controllers, ActiveJob and Sidekiq jobs, and
|
|
8
|
+
whatever reaches `Rails.error`, each once. Exceptions Rails maps to a
|
|
9
|
+
4xx status (`ActiveRecord::RecordNotFound`, …) aren't reported.
|
|
10
|
+
- `Tlm::Rack` middleware for any Rack app: reports the exceptions that
|
|
11
|
+
escape it, and attaches the request (credentials left out) and its
|
|
12
|
+
request id to errors reported while handling it.
|
|
13
|
+
- A crash that ends the process is reported as `fatal`, and unsent
|
|
14
|
+
errors get up to 2 seconds to go out before it exits.
|
|
15
|
+
- Failed jobs are tagged with the job, queue, job id, attempt (and max
|
|
16
|
+
attempts, for Sidekiq) and args, secret-looking keys filtered at any
|
|
17
|
+
depth, records as their global id, cut past 2 KB of JSON
|
|
18
|
+
(`config.job_args = false` leaves them out). Errors `retry_on` will
|
|
19
|
+
retry and `discard_on` jobs aren't reported.
|
|
20
|
+
- Breadcrumbs from the request's or job's log lines (info and above) and
|
|
21
|
+
database queries.
|
|
22
|
+
- Frames marked `in_app` for the app's own code, not installed gems or
|
|
23
|
+
methods written in C; gems are named from `gems/` on.
|
|
24
|
+
- Heartbeats: one when the app starts and one every hour, with its
|
|
25
|
+
release, environment, server, SDK, Ruby and Rails versions.
|
|
26
|
+
- Configured by DSN, `https://tlm_…@tlm.hullop.com`, from
|
|
27
|
+
`config.dsn` or the `TLM_DSN` environment variable; `key` (`TLM_KEY`)
|
|
28
|
+
and `endpoint` work too. An invalid DSN sends nothing and warns at
|
|
29
|
+
start. The release defaults to `TLM_RELEASE`, else the app's git
|
|
30
|
+
commit.
|
|
31
|
+
- `rake tlm:test` and `Tlm.test_event` send a test event right away and
|
|
32
|
+
report the answer.
|
|
33
|
+
- `Tlm.capture_exception`, `Tlm.capture_message` and `Tlm.set_user`.
|
|
34
|
+
- Background sending with a bounded queue, safe retries and
|
|
35
|
+
`Retry-After` support, that carries on in forked workers. A refused
|
|
36
|
+
key (401, 403) stops sending until the app restarts.
|
data/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Hullop
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
# Tlm
|
|
2
|
+
|
|
3
|
+
Reports your Ruby app's errors to
|
|
4
|
+
[Hullop Telemetry](https://tlm.hullop.com) (Tlm), which groups them into
|
|
5
|
+
issues and shows you what broke and why.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
Add the gem to your `Gemfile`:
|
|
10
|
+
|
|
11
|
+
```ruby
|
|
12
|
+
gem 'tlm', '>= 0.1.0'
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Give it your project's DSN (from its setup page in Tlm) in the
|
|
16
|
+
`TLM_DSN` environment variable of the deployed app. Or, to take it from
|
|
17
|
+
somewhere else, in `config/initializers/tlm.rb`:
|
|
18
|
+
|
|
19
|
+
```ruby
|
|
20
|
+
Tlm.configure do |config|
|
|
21
|
+
config.dsn = ENV['MY_TLM_DSN']
|
|
22
|
+
end
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
In a Rails app, that's it. From now on, errors are reported on their
|
|
26
|
+
own: controllers, ActiveJob jobs, Sidekiq jobs, runners, and whatever
|
|
27
|
+
reaches `Rails.error`. A crash that ends the process is reported too.
|
|
28
|
+
Exceptions Rails turns into a 4xx, like `ActiveRecord::RecordNotFound`,
|
|
29
|
+
aren't bugs and aren't reported.
|
|
30
|
+
|
|
31
|
+
It also sends a heartbeat when the app starts and every hour after, so
|
|
32
|
+
Tlm knows the app is up even when nothing breaks, and shows its release,
|
|
33
|
+
environment and SDK version.
|
|
34
|
+
|
|
35
|
+
Without a DSN nothing is sent, so development and test stay quiet: don't
|
|
36
|
+
export `TLM_DSN` there.
|
|
37
|
+
|
|
38
|
+
### Without Rails
|
|
39
|
+
|
|
40
|
+
Start Tlm once the app is configured, and add the middleware to a Rack
|
|
41
|
+
app:
|
|
42
|
+
|
|
43
|
+
```ruby
|
|
44
|
+
require 'tlm'
|
|
45
|
+
|
|
46
|
+
Tlm.start
|
|
47
|
+
use Tlm::Rack # in config.ru
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
For Sidekiq, wherever Sidekiq is configured:
|
|
51
|
+
|
|
52
|
+
```ruby
|
|
53
|
+
require 'tlm/sidekiq'
|
|
54
|
+
|
|
55
|
+
Tlm::Sidekiq.install
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Checking the setup
|
|
59
|
+
|
|
60
|
+
Send a test event and see Tlm's answer:
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
RAILS_ENV=production bin/rails tlm:test
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
It prints the event's id when Tlm accepted it, or what went wrong (no
|
|
67
|
+
DSN, a refused key, Tlm unreachable), and exits with 1 then. Without
|
|
68
|
+
Rails, add `require 'tlm/tasks'` to your `Rakefile` and run
|
|
69
|
+
`rake tlm:test`, or call `Tlm.test_event` from a console.
|
|
70
|
+
|
|
71
|
+
## Users
|
|
72
|
+
|
|
73
|
+
Say who hit the error, by id:
|
|
74
|
+
|
|
75
|
+
```ruby
|
|
76
|
+
Tlm.set_user(current_user.id)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The request each error happened in is attached on its own (credentials
|
|
80
|
+
such as cookies are never sent), and so is what led to it: the request's
|
|
81
|
+
or job's last 50 log lines and its database queries.
|
|
82
|
+
|
|
83
|
+
## Job args
|
|
84
|
+
|
|
85
|
+
A failed job's issue shows the job, its queue, id and attempt, and its
|
|
86
|
+
args, so the input that broke it is at hand. Values under keys that look
|
|
87
|
+
secret (`password`, `token`, `secret`, `api_key`, `key`, `auth`,
|
|
88
|
+
`cookie`, `session`, …, at any depth) are sent as `"[FILTERED]"`,
|
|
89
|
+
records as their global id, and args past 2 KB are cut. For apps whose
|
|
90
|
+
job args are sensitive by nature:
|
|
91
|
+
|
|
92
|
+
```ruby
|
|
93
|
+
Tlm.configure do |config|
|
|
94
|
+
config.job_args = false
|
|
95
|
+
end
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
A job that raises is reported on every attempt. Errors a job handles
|
|
99
|
+
itself (`retry_on`, `discard_on`) aren't, until `retry_on` gives up.
|
|
100
|
+
|
|
101
|
+
## Reporting by hand
|
|
102
|
+
|
|
103
|
+
```ruby
|
|
104
|
+
begin
|
|
105
|
+
charge!(order)
|
|
106
|
+
rescue PaymentError => error
|
|
107
|
+
Tlm.capture_exception(error, tags: { gateway: 'acme' })
|
|
108
|
+
end
|
|
109
|
+
|
|
110
|
+
Tlm.capture_message('Payment gateway slow', level: :warning)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Both return the event's id, which you can show the user to quote. Each
|
|
114
|
+
takes `level` (`:fatal`, `:error`, `:warning` or `:info`), `tags`,
|
|
115
|
+
`fingerprint` (to group events your way) and `user`.
|
|
116
|
+
|
|
117
|
+
## Options
|
|
118
|
+
|
|
119
|
+
| Option | Default | |
|
|
120
|
+
|---|---|---|
|
|
121
|
+
| `dsn` | `TLM_DSN` | `https://tlm_…@tlm.hullop.com`: where Tlm runs plus the project's key. Nothing is sent without it |
|
|
122
|
+
| `key`, `endpoint` | `TLM_KEY`, `https://tlm.hullop.com` | The DSN's two halves, set apart. A DSN wins over both |
|
|
123
|
+
| `environment` | `Rails.env`, `RAILS_ENV`, `RACK_ENV`, `development` | `production`, `staging`, … |
|
|
124
|
+
| `release` | `TLM_RELEASE`, else the app's git commit | Version or git sha |
|
|
125
|
+
| `app_root` | `Rails.root`, else the current directory | Code under it is "your code", except installed gems |
|
|
126
|
+
| `job_args` | `true` | `false` leaves job args out of job failures |
|
|
127
|
+
| `logger` | `Rails.logger`, else standard error | Where Tlm's own warnings go |
|
|
128
|
+
|
|
129
|
+
## How it behaves
|
|
130
|
+
|
|
131
|
+
Events are sent in the background, one at a time, from a bounded queue
|
|
132
|
+
(the oldest is dropped past 1000), so a slow or unreachable Tlm never
|
|
133
|
+
slows your app down. Failed sends are retried with the same id, so
|
|
134
|
+
nothing is counted twice; when Tlm asks to slow down, it does. When it
|
|
135
|
+
refuses the key, nothing more is sent until the app restarts. Heartbeats
|
|
136
|
+
share that queue, at most one waiting at a time. They have their own
|
|
137
|
+
rate limit, so being slowed down on heartbeats never pauses errors, and
|
|
138
|
+
they never log anything.
|
|
139
|
+
|
|
140
|
+
A process that exits waits up to 2 seconds for its unsent errors, never
|
|
141
|
+
for a heartbeat. Forked workers (Puma, Unicorn, Sidekiq) get a sending
|
|
142
|
+
thread of their own.
|
|
143
|
+
|
|
144
|
+
The protocol is documented in Tlm's `docs/protocol.md`, if you'd like to
|
|
145
|
+
report from another language.
|
|
146
|
+
|
|
147
|
+
## Development
|
|
148
|
+
|
|
149
|
+
```sh
|
|
150
|
+
bundle install
|
|
151
|
+
bundle exec rake
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
That runs the core, Rails and Sidekiq suites, each in its own process,
|
|
155
|
+
and RuboCop.
|
|
156
|
+
|
|
157
|
+
## License
|
|
158
|
+
|
|
159
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
module Tlm
|
|
2
|
+
# Reports ActiveJob failures, tagged with the job, queue, job id, attempt
|
|
3
|
+
# and arguments (see Tlm::JobArgs). Prepended to ActiveJob::Base by the
|
|
4
|
+
# Railtie.
|
|
5
|
+
#
|
|
6
|
+
# A job that raises is reported on every attempt: that is its code
|
|
7
|
+
# meeting something it could not handle. Errors a job handles itself
|
|
8
|
+
# (`retry_on`, `discard_on`, `rescue_from`) aren't, until `retry_on` runs
|
|
9
|
+
# out of attempts and raises.
|
|
10
|
+
module ActiveJob
|
|
11
|
+
def self.tags(job)
|
|
12
|
+
{
|
|
13
|
+
'job' => job.class.name,
|
|
14
|
+
'queue' => job.queue_name.to_s,
|
|
15
|
+
'job_id' => job.job_id.to_s,
|
|
16
|
+
'attempt' => job.executions.to_s,
|
|
17
|
+
'args' => JobArgs.tag(job.arguments)
|
|
18
|
+
}.compact
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
def perform_now
|
|
22
|
+
Context.isolate do
|
|
23
|
+
super
|
|
24
|
+
rescue Exception => exception
|
|
25
|
+
Tlm.capture_exception(exception, tags: Tlm::ActiveJob.tags(self)) if Tlm.reportable?(exception)
|
|
26
|
+
raise
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
end
|
|
30
|
+
end
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
require 'rbconfig'
|
|
2
|
+
|
|
3
|
+
module Tlm
|
|
4
|
+
# Turns a Ruby backtrace into protocol frames, innermost first (the
|
|
5
|
+
# order Ruby already uses), each marked `in_app` when it is the app's
|
|
6
|
+
# own code. Tlm groups errors by those frames, so that mark is the most
|
|
7
|
+
# important thing this gem gets right.
|
|
8
|
+
module Backtrace
|
|
9
|
+
# "block (2 levels) in Shop::Orders#charge": the class and the method.
|
|
10
|
+
LABEL = /\A(?<prefix>(?:(?:block|rescue|ensure)(?: \(\d+ levels\))? in )*)(?<owner>[A-Z][\w:]*)(?<separator>[#.])(?<method>.+)\z/
|
|
11
|
+
|
|
12
|
+
# A backtrace line made of strings: "lib/shop.rb:12:in 'Shop#charge'".
|
|
13
|
+
LINE = /\A(?<path>.+?):(?<line>\d+)(?::in [`'](?<label>.*)')?\z/
|
|
14
|
+
|
|
15
|
+
DIRS = {}
|
|
16
|
+
|
|
17
|
+
module_function
|
|
18
|
+
|
|
19
|
+
def frames(exception, root:)
|
|
20
|
+
locations(exception).map { |path, line, label| frame(path, line, label, root) }
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
def frame(path, line, label, root)
|
|
24
|
+
in_app = in_app?(path, root) && !native?(label)
|
|
25
|
+
owner, function = split_label(label)
|
|
26
|
+
frame = {
|
|
27
|
+
'module' => owner,
|
|
28
|
+
'function' => function,
|
|
29
|
+
'file' => display_path(path, in_app, root),
|
|
30
|
+
'line' => line,
|
|
31
|
+
'in_app' => in_app
|
|
32
|
+
}
|
|
33
|
+
context = in_app && Source.context(path, line)
|
|
34
|
+
context ? frame.merge('context' => context) : frame
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
def split_label(label)
|
|
38
|
+
return [ nil, nil ] if label.nil?
|
|
39
|
+
|
|
40
|
+
label = Text.utf8(label).gsub(/:0x\h+/, '')
|
|
41
|
+
match = LABEL.match(label)
|
|
42
|
+
match ? [ match[:owner], "#{match[:prefix]}#{match[:method]}" ] : [ nil, label ]
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
def in_app?(path, root)
|
|
46
|
+
under?(path, roots(root)) && !under?(path, dependency_dirs(root))
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
# Ruby gives a method written in C (Array#each) the file and line of
|
|
50
|
+
# its caller, so it would pass for the app's own code.
|
|
51
|
+
def native?(label)
|
|
52
|
+
match = LABEL.match(label.to_s)
|
|
53
|
+
return false if match.nil? || !match[:prefix].empty?
|
|
54
|
+
|
|
55
|
+
owner = Object.const_get(match[:owner])
|
|
56
|
+
method = match[:separator] == '.' ? owner.method(match[:method]) : owner.instance_method(match[:method])
|
|
57
|
+
method.source_location.nil?
|
|
58
|
+
rescue NameError, TypeError
|
|
59
|
+
false
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
def display_path(path, in_app, root)
|
|
63
|
+
roots = roots(root)
|
|
64
|
+
return relative(path, roots) if in_app
|
|
65
|
+
return path.sub(%r{\A.*/gems/}, 'gems/') if under?(path, dependency_dirs(root))
|
|
66
|
+
return relative(path, [ ruby_lib_dir ]) if under?(path, [ ruby_lib_dir ])
|
|
67
|
+
return relative(path, roots) if under?(path, roots)
|
|
68
|
+
|
|
69
|
+
path
|
|
70
|
+
end
|
|
71
|
+
|
|
72
|
+
def locations(exception)
|
|
73
|
+
if (locations = exception.backtrace_locations)
|
|
74
|
+
locations.map { |l| [ l.absolute_path || l.path, l.lineno, l.label ] }
|
|
75
|
+
else
|
|
76
|
+
(exception.backtrace || []).map { |line| parse_line(line) }
|
|
77
|
+
end
|
|
78
|
+
end
|
|
79
|
+
|
|
80
|
+
def parse_line(line)
|
|
81
|
+
match = LINE.match(line)
|
|
82
|
+
match ? [ match[:path], match[:line].to_i, match[:label] ] : [ line, nil, nil ]
|
|
83
|
+
end
|
|
84
|
+
|
|
85
|
+
def under?(path, dirs)
|
|
86
|
+
dirs.any? { |dir| path.start_with?("#{dir}/") }
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
def relative(path, dirs)
|
|
90
|
+
dir = dirs.find { |d| path.start_with?("#{d}/") }
|
|
91
|
+
path.delete_prefix("#{dir}/")
|
|
92
|
+
end
|
|
93
|
+
|
|
94
|
+
# The app's root as given and as resolved, since a deploy may run it
|
|
95
|
+
# through a symlink.
|
|
96
|
+
def roots(root)
|
|
97
|
+
DIRS.fetch([ :roots, root ]) do
|
|
98
|
+
DIRS[[ :roots, root ]] = [ root, (File.realpath(root) rescue root) ].uniq
|
|
99
|
+
end
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
def dependency_dirs(root)
|
|
103
|
+
DIRS.fetch([ :dependencies, root ]) do
|
|
104
|
+
DIRS[[ :dependencies, root ]] = (gem_dirs + [ "#{root}/vendor", "#{root}/node_modules" ]).uniq
|
|
105
|
+
end
|
|
106
|
+
end
|
|
107
|
+
|
|
108
|
+
def gem_dirs
|
|
109
|
+
dirs = Gem.path + [ Gem.dir ]
|
|
110
|
+
dirs << Bundler.bundle_path.to_s if defined?(Bundler) && Bundler.respond_to?(:bundle_path)
|
|
111
|
+
dirs.map { |dir| dir.to_s.chomp('/') }
|
|
112
|
+
rescue StandardError
|
|
113
|
+
Gem.path
|
|
114
|
+
end
|
|
115
|
+
|
|
116
|
+
def ruby_lib_dir = RbConfig::CONFIG['rubylibdir']
|
|
117
|
+
end
|
|
118
|
+
end
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
module Tlm
|
|
2
|
+
# What the current request or job did just before it failed: its last
|
|
3
|
+
# 50 log lines (info and above) and database queries.
|
|
4
|
+
module Breadcrumbs
|
|
5
|
+
MESSAGE_LENGTH = 500
|
|
6
|
+
|
|
7
|
+
module_function
|
|
8
|
+
|
|
9
|
+
def add(category, level, message, time = Time.now)
|
|
10
|
+
Context.add_breadcrumb(build(category, level, message, time))
|
|
11
|
+
end
|
|
12
|
+
|
|
13
|
+
def build(category, level, message, time = Time.now)
|
|
14
|
+
{
|
|
15
|
+
'timestamp' => time.utc.iso8601(3),
|
|
16
|
+
'category' => category,
|
|
17
|
+
'level' => level.to_s,
|
|
18
|
+
'message' => Text.utf8(message)[0, MESSAGE_LENGTH]
|
|
19
|
+
}
|
|
20
|
+
end
|
|
21
|
+
end
|
|
22
|
+
end
|
data/lib/tlm/config.rb
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
require 'uri'
|
|
2
|
+
|
|
3
|
+
module Tlm
|
|
4
|
+
# Where events go and what they say about the app. Everything has a
|
|
5
|
+
# default, the DSN included: set `TLM_DSN` in the environment, or
|
|
6
|
+
# configure it yourself:
|
|
7
|
+
#
|
|
8
|
+
# Tlm.configure do |config|
|
|
9
|
+
# config.dsn = ENV['MY_TLM_DSN']
|
|
10
|
+
# end
|
|
11
|
+
#
|
|
12
|
+
# The DSN is where Tlm runs plus the project's key, in one URL:
|
|
13
|
+
# `https://tlm_…@tlm.hullop.com`. A port and a path are fine too.
|
|
14
|
+
class Config
|
|
15
|
+
DEFAULT_ENDPOINT = 'https://tlm.hullop.com'.freeze
|
|
16
|
+
|
|
17
|
+
class InvalidDsn < StandardError; end
|
|
18
|
+
|
|
19
|
+
Dsn = Data.define(:key, :endpoint) do
|
|
20
|
+
# The key and the endpoint of `dsn`, nil when there is none.
|
|
21
|
+
def self.parse(dsn)
|
|
22
|
+
return if dsn.nil? || dsn.empty?
|
|
23
|
+
|
|
24
|
+
uri = URI.parse(dsn)
|
|
25
|
+
raise InvalidDsn unless valid?(uri)
|
|
26
|
+
|
|
27
|
+
port = ":#{uri.port}" unless uri.port == uri.default_port
|
|
28
|
+
new(key: uri.userinfo, endpoint: "#{uri.scheme}://#{uri.host}#{port}#{uri.path}".sub(%r{/+\z}, ''))
|
|
29
|
+
rescue URI::Error
|
|
30
|
+
raise InvalidDsn
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
def self.valid?(uri)
|
|
34
|
+
%w[ http https ].include?(uri.scheme) && present?(uri.userinfo) && present?(uri.host)
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
def self.present?(value) = !value.nil? && !value.empty?
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
attr_writer :dsn, :key, :endpoint, :environment, :release, :app_root, :logger
|
|
41
|
+
|
|
42
|
+
# Whether failed jobs carry their (filtered) arguments as a tag.
|
|
43
|
+
attr_accessor :job_args
|
|
44
|
+
|
|
45
|
+
# What sends requests: anything with `post(path, body)` answering a
|
|
46
|
+
# Tlm::Http::Response. Defaults to Tlm::Http.
|
|
47
|
+
attr_accessor :transport
|
|
48
|
+
|
|
49
|
+
def initialize
|
|
50
|
+
@job_args = true
|
|
51
|
+
@release_from_git = {}
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
def dsn = @dsn || env('TLM_DSN')
|
|
55
|
+
|
|
56
|
+
def key
|
|
57
|
+
parsed = parsed_dsn
|
|
58
|
+
parsed == :invalid ? nil : parsed&.key || @key || env('TLM_KEY')
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
def endpoint
|
|
62
|
+
parsed = parsed_dsn
|
|
63
|
+
parsed.is_a?(Dsn) ? parsed.endpoint : @endpoint || DEFAULT_ENDPOINT
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
def enabled? = !key.nil? && !key.empty?
|
|
67
|
+
|
|
68
|
+
def invalid_dsn? = parsed_dsn == :invalid
|
|
69
|
+
|
|
70
|
+
def environment
|
|
71
|
+
@environment&.to_s || rails_env || env('RAILS_ENV') || env('RACK_ENV') || 'development'
|
|
72
|
+
end
|
|
73
|
+
|
|
74
|
+
def release = @release&.to_s || env('TLM_RELEASE') || release_from_git
|
|
75
|
+
|
|
76
|
+
# The directory of the app's own code: frames under it are "yours",
|
|
77
|
+
# unless they belong to an installed gem.
|
|
78
|
+
def app_root = (@app_root || rails_root || Dir.pwd).to_s
|
|
79
|
+
|
|
80
|
+
def logger = @logger || rails_logger || StderrLogger
|
|
81
|
+
|
|
82
|
+
module StderrLogger
|
|
83
|
+
def self.warn(message) = Kernel.warn("[tlm] #{message}")
|
|
84
|
+
end
|
|
85
|
+
|
|
86
|
+
private
|
|
87
|
+
|
|
88
|
+
def parsed_dsn
|
|
89
|
+
Dsn.parse(dsn)
|
|
90
|
+
rescue InvalidDsn
|
|
91
|
+
:invalid
|
|
92
|
+
end
|
|
93
|
+
|
|
94
|
+
def env(name)
|
|
95
|
+
value = ENV[name]
|
|
96
|
+
value unless value.nil? || value.empty?
|
|
97
|
+
end
|
|
98
|
+
|
|
99
|
+
def release_from_git
|
|
100
|
+
root = app_root
|
|
101
|
+
return @release_from_git[root] if @release_from_git.key?(root)
|
|
102
|
+
|
|
103
|
+
@release_from_git[root] = git_sha(root)
|
|
104
|
+
end
|
|
105
|
+
|
|
106
|
+
def git_sha(root)
|
|
107
|
+
sha = IO.popen([ 'git', 'rev-parse', 'HEAD' ], chdir: root, err: File::NULL, &:read).strip
|
|
108
|
+
sha if $?.success? && sha.match?(/\A\h{40}(\h{24})?\z/)
|
|
109
|
+
rescue SystemCallError
|
|
110
|
+
nil
|
|
111
|
+
end
|
|
112
|
+
|
|
113
|
+
def rails_env = rails? && ::Rails.respond_to?(:env) ? ::Rails.env.to_s : nil
|
|
114
|
+
|
|
115
|
+
def rails_root = rails? && ::Rails.respond_to?(:root) ? ::Rails.root : nil
|
|
116
|
+
|
|
117
|
+
def rails_logger = rails? && ::Rails.respond_to?(:logger) ? ::Rails.logger : nil
|
|
118
|
+
|
|
119
|
+
def rails? = defined?(::Rails)
|
|
120
|
+
end
|
|
121
|
+
end
|
data/lib/tlm/context.rb
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
module Tlm
|
|
2
|
+
# What the current request or job is about: who, which request, and
|
|
3
|
+
# what happened before. Fiber-local, so threads and fibers serving
|
|
4
|
+
# other requests never see it.
|
|
5
|
+
module Context
|
|
6
|
+
MAX_BREADCRUMBS = 50
|
|
7
|
+
|
|
8
|
+
State = Struct.new(:user, :request, :request_id, :breadcrumbs)
|
|
9
|
+
|
|
10
|
+
module_function
|
|
11
|
+
|
|
12
|
+
def user = state.user
|
|
13
|
+
def user=(id)
|
|
14
|
+
state.user = id&.to_s
|
|
15
|
+
end
|
|
16
|
+
|
|
17
|
+
def request = state.request
|
|
18
|
+
def request=(request)
|
|
19
|
+
state.request = request
|
|
20
|
+
end
|
|
21
|
+
|
|
22
|
+
def request_id = state.request_id
|
|
23
|
+
def request_id=(id)
|
|
24
|
+
state.request_id = id
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
# The breadcrumbs, oldest first.
|
|
28
|
+
def breadcrumbs = state.breadcrumbs.dup
|
|
29
|
+
|
|
30
|
+
def add_breadcrumb(crumb)
|
|
31
|
+
crumbs = state.breadcrumbs
|
|
32
|
+
crumbs << crumb
|
|
33
|
+
crumbs.shift while crumbs.size > MAX_BREADCRUMBS
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
def reset
|
|
37
|
+
Thread.current[:tlm_context] = nil
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
# Runs the block with a fresh context, and puts the previous one back.
|
|
41
|
+
def isolate
|
|
42
|
+
previous = Thread.current[:tlm_context]
|
|
43
|
+
reset
|
|
44
|
+
yield
|
|
45
|
+
ensure
|
|
46
|
+
Thread.current[:tlm_context] = previous
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
def state
|
|
50
|
+
Thread.current[:tlm_context] ||= State.new(nil, nil, nil, [])
|
|
51
|
+
end
|
|
52
|
+
end
|
|
53
|
+
end
|
data/lib/tlm/event.rb
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
require 'securerandom'
|
|
2
|
+
require 'socket'
|
|
3
|
+
|
|
4
|
+
module Tlm
|
|
5
|
+
# Builds protocol v1 events (see Tlm's `docs/protocol.md`): plain
|
|
6
|
+
# string-keyed hashes, ready to encode as JSON.
|
|
7
|
+
module Event
|
|
8
|
+
LEVELS = %w[ fatal error warning info ].freeze
|
|
9
|
+
LEVEL_ALIASES = { 'warn' => 'warning', 'debug' => 'info' }.freeze
|
|
10
|
+
REQUEST_ID_LENGTH = 200
|
|
11
|
+
|
|
12
|
+
module_function
|
|
13
|
+
|
|
14
|
+
# An event for an exception. Options: `level`, `message`,
|
|
15
|
+
# `fingerprint`, `user`, `request`, `request_id`, `tags`, `breadcrumbs`.
|
|
16
|
+
def from_exception(exception, config:, **options)
|
|
17
|
+
exception_part = {
|
|
18
|
+
'type' => exception.class.name || exception.class.inspect,
|
|
19
|
+
'message' => exception_message(exception),
|
|
20
|
+
'frames' => Backtrace.frames(exception, root: config.app_root)
|
|
21
|
+
}
|
|
22
|
+
safe(base(config, **options).merge('exception' => exception_part))
|
|
23
|
+
end
|
|
24
|
+
|
|
25
|
+
# An event for a message that isn't an exception. Same options.
|
|
26
|
+
def from_message(message, config:, **options)
|
|
27
|
+
safe(base(config, **options, message: message.to_s))
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
# Whatever the app put in a message, tag or user id, the event must
|
|
31
|
+
# encode as JSON: an event that can't be sent is lost.
|
|
32
|
+
def safe(value)
|
|
33
|
+
case value
|
|
34
|
+
when String then Text.utf8(value)
|
|
35
|
+
when Symbol then Text.utf8(value.name)
|
|
36
|
+
when Hash then value.to_h { |key, item| [ Text.utf8(key.is_a?(Symbol) ? key.name : key.to_s), safe(item) ] }
|
|
37
|
+
when Array then value.map { |item| safe(item) }
|
|
38
|
+
when Integer, true, false, nil then value
|
|
39
|
+
when Float then value.finite? ? value : value.to_s
|
|
40
|
+
else Text.utf8(describe(value))
|
|
41
|
+
end
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
def level(value)
|
|
45
|
+
value = value.to_s
|
|
46
|
+
value = LEVEL_ALIASES.fetch(value, value)
|
|
47
|
+
LEVELS.include?(value) ? value : 'error'
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
def server = Socket.gethostname
|
|
51
|
+
|
|
52
|
+
def base(config, level: :error, message: nil, fingerprint: nil, user: nil, request: nil,
|
|
53
|
+
request_id: nil, tags: nil, breadcrumbs: nil)
|
|
54
|
+
{
|
|
55
|
+
'v' => 1,
|
|
56
|
+
'uuid' => SecureRandom.uuid,
|
|
57
|
+
'timestamp' => Time.now.utc.iso8601(3),
|
|
58
|
+
'platform' => 'ruby',
|
|
59
|
+
'level' => level(level),
|
|
60
|
+
'environment' => config.environment,
|
|
61
|
+
'release' => config.release,
|
|
62
|
+
'server' => server,
|
|
63
|
+
'exception' => nil,
|
|
64
|
+
'message' => message,
|
|
65
|
+
'fingerprint' => fingerprint&.map(&:to_s),
|
|
66
|
+
'request' => request,
|
|
67
|
+
'request_id' => request_id && Text.utf8(request_id)[0, REQUEST_ID_LENGTH],
|
|
68
|
+
'user' => user.nil? ? nil : { 'id' => user.to_s },
|
|
69
|
+
'tags' => tags || {},
|
|
70
|
+
'breadcrumbs' => breadcrumbs || [],
|
|
71
|
+
'sdk' => { 'name' => 'tlm', 'version' => VERSION }
|
|
72
|
+
}
|
|
73
|
+
end
|
|
74
|
+
|
|
75
|
+
# A broken #message must not stop the report.
|
|
76
|
+
def exception_message(exception)
|
|
77
|
+
exception.message
|
|
78
|
+
rescue StandardError
|
|
79
|
+
describe(exception)
|
|
80
|
+
end
|
|
81
|
+
|
|
82
|
+
def describe(value)
|
|
83
|
+
value.inspect
|
|
84
|
+
rescue StandardError
|
|
85
|
+
"#<#{value.class}>"
|
|
86
|
+
end
|
|
87
|
+
end
|
|
88
|
+
end
|