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
data/lib/tlm/source.rb
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
module Tlm
|
|
2
|
+
# Source lines around a frame, so Tlm can show the failing line.
|
|
3
|
+
module Source
|
|
4
|
+
LINES = 5
|
|
5
|
+
MAX_FILES = 100
|
|
6
|
+
|
|
7
|
+
@cache = {}
|
|
8
|
+
@mutex = Mutex.new
|
|
9
|
+
|
|
10
|
+
class << self
|
|
11
|
+
# Five lines before and after `line` of `path`, or nil when unknown.
|
|
12
|
+
def context(path, line)
|
|
13
|
+
return unless line.is_a?(Integer) && line.positive?
|
|
14
|
+
|
|
15
|
+
lines = lines(path)
|
|
16
|
+
current = lines&.[](line - 1)
|
|
17
|
+
return unless current
|
|
18
|
+
|
|
19
|
+
{
|
|
20
|
+
'pre' => lines[[ line - 1 - LINES, 0 ].max, [ LINES, line - 1 ].min],
|
|
21
|
+
'line' => current,
|
|
22
|
+
'post' => lines[line, LINES]
|
|
23
|
+
}
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
def clear = @mutex.synchronize { @cache.clear }
|
|
27
|
+
|
|
28
|
+
private
|
|
29
|
+
|
|
30
|
+
def lines(path)
|
|
31
|
+
@mutex.synchronize do
|
|
32
|
+
@cache.clear if @cache.size >= MAX_FILES && !@cache.key?(path)
|
|
33
|
+
@cache.fetch(path) { @cache[path] = read(path) }
|
|
34
|
+
end
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
def read(path)
|
|
38
|
+
Text.utf8(File.binread(path)).split("\n", -1).map { |line| line.delete_suffix("\r") }
|
|
39
|
+
rescue SystemCallError, IOError
|
|
40
|
+
nil
|
|
41
|
+
end
|
|
42
|
+
end
|
|
43
|
+
end
|
|
44
|
+
end
|
data/lib/tlm/tasks.rb
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
module Tlm
|
|
2
|
+
# What `rake tlm:test` runs: sends one test event right away and prints
|
|
3
|
+
# what Tlm answered. Returns the exit status, 0 when Tlm accepted it.
|
|
4
|
+
class TestCommand
|
|
5
|
+
def initialize(out: $stdout, err: $stderr)
|
|
6
|
+
@out = out
|
|
7
|
+
@err = err
|
|
8
|
+
end
|
|
9
|
+
|
|
10
|
+
def run
|
|
11
|
+
uuid = Tlm.test_event
|
|
12
|
+
@out.puts "Sent: Tlm accepted the test event #{uuid} (#{config.environment}, release #{config.release || 'none'})"
|
|
13
|
+
0
|
|
14
|
+
rescue StandardError => error
|
|
15
|
+
@err.puts message(error)
|
|
16
|
+
1
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
private
|
|
20
|
+
|
|
21
|
+
def config = Tlm.config
|
|
22
|
+
|
|
23
|
+
def message(error)
|
|
24
|
+
case error
|
|
25
|
+
when NoDsnError then "TLM_DSN isn't set (nor Tlm.config.dsn): nothing to send to"
|
|
26
|
+
when InvalidDsnError then "The DSN isn't valid: expected https://tlm_…@tlm.hullop.com"
|
|
27
|
+
when RejectedError then rejected(error.status, detail(error.body))
|
|
28
|
+
else "Couldn't reach #{config.endpoint}: #{error.message}"
|
|
29
|
+
end
|
|
30
|
+
end
|
|
31
|
+
|
|
32
|
+
def rejected(status, detail)
|
|
33
|
+
case status
|
|
34
|
+
when 401, 403 then "#{config.endpoint} refused the key (HTTP #{status}#{detail}): check the DSN"
|
|
35
|
+
when 404 then "#{config.endpoint} answered HTTP 404#{detail}: is Tlm there? Check the DSN's host"
|
|
36
|
+
else "#{config.endpoint} answered HTTP #{status}#{detail}"
|
|
37
|
+
end
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
# Tlm answers {"error": "…"} or, for an event it refused, {"errors": {…}};
|
|
41
|
+
# anything else (an HTML page, say) is cut to its first line.
|
|
42
|
+
def detail(body)
|
|
43
|
+
case parse(body)
|
|
44
|
+
in { error: String => error } then ", #{error}"
|
|
45
|
+
in { errors: Hash => errors } then ", #{JSON.generate(errors)}"
|
|
46
|
+
else body.to_s.empty? ? '' : ", #{body.to_s.lines.first.chomp[0, 120].inspect}"
|
|
47
|
+
end
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
def parse(body)
|
|
51
|
+
JSON.parse(body.to_s, symbolize_names: true)
|
|
52
|
+
rescue JSON::ParserError
|
|
53
|
+
nil
|
|
54
|
+
end
|
|
55
|
+
end
|
|
56
|
+
end
|
data/lib/tlm/text.rb
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
module Tlm
|
|
2
|
+
module Text
|
|
3
|
+
module_function
|
|
4
|
+
|
|
5
|
+
# At most `bytes` bytes of `string`, without splitting a character.
|
|
6
|
+
def cut(string, bytes)
|
|
7
|
+
return string if string.bytesize <= bytes
|
|
8
|
+
|
|
9
|
+
string.byteslice(0, bytes).scrub('')
|
|
10
|
+
end
|
|
11
|
+
|
|
12
|
+
# `value` as valid UTF-8, invalid bytes replaced.
|
|
13
|
+
def utf8(value)
|
|
14
|
+
string = value.to_s
|
|
15
|
+
return string.scrub if string.encoding == Encoding::UTF_8
|
|
16
|
+
return string.dup.force_encoding(Encoding::UTF_8).scrub if string.encoding == Encoding::BINARY
|
|
17
|
+
|
|
18
|
+
string.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
|
|
19
|
+
end
|
|
20
|
+
end
|
|
21
|
+
end
|
data/lib/tlm/version.rb
ADDED
data/lib/tlm.rb
ADDED
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
require 'monitor'
|
|
2
|
+
require 'time'
|
|
3
|
+
|
|
4
|
+
require_relative 'tlm/version'
|
|
5
|
+
require_relative 'tlm/text'
|
|
6
|
+
require_relative 'tlm/config'
|
|
7
|
+
require_relative 'tlm/context'
|
|
8
|
+
require_relative 'tlm/breadcrumbs'
|
|
9
|
+
require_relative 'tlm/source'
|
|
10
|
+
require_relative 'tlm/backtrace'
|
|
11
|
+
require_relative 'tlm/event'
|
|
12
|
+
require_relative 'tlm/http'
|
|
13
|
+
require_relative 'tlm/sender'
|
|
14
|
+
require_relative 'tlm/heartbeat'
|
|
15
|
+
require_relative 'tlm/job_args'
|
|
16
|
+
|
|
17
|
+
# Reports your app's errors to Tlm (Hullop Telemetry).
|
|
18
|
+
#
|
|
19
|
+
# Set `TLM_DSN` in the deployed app's environment. In Rails that's all;
|
|
20
|
+
# elsewhere, call `Tlm.start` once the app is configured. Without a DSN
|
|
21
|
+
# nothing is sent.
|
|
22
|
+
module Tlm
|
|
23
|
+
autoload :Rack, 'tlm/rack'
|
|
24
|
+
autoload :ActiveJob, 'tlm/active_job'
|
|
25
|
+
autoload :Sidekiq, 'tlm/sidekiq'
|
|
26
|
+
autoload :TestCommand, 'tlm/test_command'
|
|
27
|
+
|
|
28
|
+
class Error < StandardError; end
|
|
29
|
+
|
|
30
|
+
# Raised by `test_event` when there is no DSN to send to.
|
|
31
|
+
class NoDsnError < Error; end
|
|
32
|
+
|
|
33
|
+
# Raised by `test_event` when the DSN can't be parsed.
|
|
34
|
+
class InvalidDsnError < Error; end
|
|
35
|
+
|
|
36
|
+
# Raised by `test_event` when Tlm answered anything but a 2xx.
|
|
37
|
+
class RejectedError < Error
|
|
38
|
+
attr_reader :status, :body
|
|
39
|
+
|
|
40
|
+
def initialize(status, body)
|
|
41
|
+
@status = status
|
|
42
|
+
@body = body
|
|
43
|
+
super("Tlm answered HTTP #{status}")
|
|
44
|
+
end
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
# What `test_event` reports: not a real error, just a check that events
|
|
48
|
+
# arrive.
|
|
49
|
+
class TestError < StandardError
|
|
50
|
+
def initialize(message = 'Tlm test event') = super
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
# Flips forked children (Puma and Unicorn workers, Sidekiq swarms) onto
|
|
54
|
+
# threads of their own: a fork keeps only the thread that forked.
|
|
55
|
+
module ForkHook
|
|
56
|
+
def _fork
|
|
57
|
+
pid = super
|
|
58
|
+
Tlm.after_fork if pid.zero?
|
|
59
|
+
pid
|
|
60
|
+
end
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
REPORTED = :@__tlm_reported
|
|
64
|
+
FLUSH_TIMEOUT = 2
|
|
65
|
+
|
|
66
|
+
@lock = Monitor.new
|
|
67
|
+
|
|
68
|
+
class << self
|
|
69
|
+
def config = @config ||= Config.new
|
|
70
|
+
|
|
71
|
+
def configure
|
|
72
|
+
yield config
|
|
73
|
+
config
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
# Starts the heartbeats, and reports a crash that ends the process.
|
|
77
|
+
# True when there is a DSN to send to.
|
|
78
|
+
def start
|
|
79
|
+
config.logger.warn("Tlm's DSN isn't valid (expected https://tlm_…@host); nothing will be sent") if config.invalid_dsn?
|
|
80
|
+
return false unless config.enabled?
|
|
81
|
+
|
|
82
|
+
@lock.synchronize do
|
|
83
|
+
@heartbeat ||= Heartbeat.new(sender:, config:).start
|
|
84
|
+
end
|
|
85
|
+
true
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
# Stops the background threads; what's queued and unsent is lost.
|
|
89
|
+
def stop
|
|
90
|
+
@lock.synchronize do
|
|
91
|
+
@heartbeat&.stop
|
|
92
|
+
@sender&.stop
|
|
93
|
+
@heartbeat = @sender = nil
|
|
94
|
+
end
|
|
95
|
+
end
|
|
96
|
+
|
|
97
|
+
# Reports an exception you rescued. Returns the event's uuid, or nil
|
|
98
|
+
# when nothing was sent (no DSN, or the exception was reported already).
|
|
99
|
+
#
|
|
100
|
+
# begin
|
|
101
|
+
# charge!(order)
|
|
102
|
+
# rescue PaymentError => error
|
|
103
|
+
# Tlm.capture_exception(error, tags: { gateway: 'acme' })
|
|
104
|
+
# end
|
|
105
|
+
def capture_exception(exception, level: :error, message: nil, fingerprint: nil, tags: {},
|
|
106
|
+
user: Context.user)
|
|
107
|
+
return unless config.enabled? && !reported?(exception)
|
|
108
|
+
|
|
109
|
+
mark_reported(exception)
|
|
110
|
+
event = Event.from_exception(exception, config:, level:, message:, fingerprint:, tags:, user:,
|
|
111
|
+
**context)
|
|
112
|
+
sender.send_event(event)
|
|
113
|
+
event['uuid']
|
|
114
|
+
rescue StandardError
|
|
115
|
+
nil
|
|
116
|
+
end
|
|
117
|
+
|
|
118
|
+
# Reports something that isn't an exception.
|
|
119
|
+
#
|
|
120
|
+
# Tlm.capture_message('Payment gateway slow', level: :warning)
|
|
121
|
+
def capture_message(message, level: :error, fingerprint: nil, tags: {}, user: Context.user)
|
|
122
|
+
return unless config.enabled?
|
|
123
|
+
|
|
124
|
+
event = Event.from_message(message, config:, level:, fingerprint:, tags:, user:, **context)
|
|
125
|
+
sender.send_event(event)
|
|
126
|
+
event['uuid']
|
|
127
|
+
rescue StandardError
|
|
128
|
+
nil
|
|
129
|
+
end
|
|
130
|
+
|
|
131
|
+
# Attaches the current user's id to errors reported from this request
|
|
132
|
+
# or job. An id, not personal data.
|
|
133
|
+
def set_user(id)
|
|
134
|
+
Context.user = id
|
|
135
|
+
end
|
|
136
|
+
|
|
137
|
+
# Waits up to `timeout` seconds for queued events to be sent.
|
|
138
|
+
def flush(timeout = FLUSH_TIMEOUT) = @sender ? @sender.flush(timeout) : true
|
|
139
|
+
|
|
140
|
+
# Sends a test event right away and waits for Tlm's answer, to check
|
|
141
|
+
# the setup end to end. Returns the event's uuid; raises NoDsnError,
|
|
142
|
+
# InvalidDsnError, RejectedError, or the network error.
|
|
143
|
+
def test_event
|
|
144
|
+
raise InvalidDsnError, "The DSN isn't valid" if config.invalid_dsn?
|
|
145
|
+
raise NoDsnError, 'No DSN is set' unless config.enabled?
|
|
146
|
+
|
|
147
|
+
event = Event.from_exception(raised(TestError.new), config:, level: :info, tags: { 'tlm.test' => 'true' })
|
|
148
|
+
response = transport.post(Sender::PATHS.fetch(:event), JSON.generate(event))
|
|
149
|
+
raise RejectedError.new(response.status, response.body) unless response.success?
|
|
150
|
+
|
|
151
|
+
event['uuid']
|
|
152
|
+
end
|
|
153
|
+
|
|
154
|
+
# Whether an integration should report `exception`: anything but the
|
|
155
|
+
# process being told to stop.
|
|
156
|
+
def reportable?(exception) = !exception.is_a?(SystemExit) && !exception.is_a?(SignalException)
|
|
157
|
+
|
|
158
|
+
def after_fork
|
|
159
|
+
@lock = Monitor.new
|
|
160
|
+
@sender&.after_fork
|
|
161
|
+
@heartbeat&.after_fork
|
|
162
|
+
end
|
|
163
|
+
|
|
164
|
+
private
|
|
165
|
+
|
|
166
|
+
def sender
|
|
167
|
+
@lock.synchronize do
|
|
168
|
+
@sender ||= begin
|
|
169
|
+
install_hooks
|
|
170
|
+
Sender.new(transport:, logger: config.logger).start
|
|
171
|
+
end
|
|
172
|
+
end
|
|
173
|
+
end
|
|
174
|
+
|
|
175
|
+
def transport = config.transport || Http.new(key: config.key, endpoint: config.endpoint)
|
|
176
|
+
|
|
177
|
+
def context
|
|
178
|
+
{ request: Context.request, request_id: Context.request_id, breadcrumbs: Context.breadcrumbs }
|
|
179
|
+
end
|
|
180
|
+
|
|
181
|
+
def install_hooks
|
|
182
|
+
return if @hooks_installed
|
|
183
|
+
|
|
184
|
+
@hooks_installed = true
|
|
185
|
+
Process.singleton_class.prepend(ForkHook)
|
|
186
|
+
at_exit { exiting($!) }
|
|
187
|
+
end
|
|
188
|
+
|
|
189
|
+
# A process that exits must not wait on Tlm for a heartbeat.
|
|
190
|
+
def exiting(error)
|
|
191
|
+
capture_exception(error, level: :fatal) if error && reportable?(error)
|
|
192
|
+
@sender&.flush(FLUSH_TIMEOUT, heartbeats: false)
|
|
193
|
+
end
|
|
194
|
+
|
|
195
|
+
def reported?(exception) = exception.instance_variable_defined?(REPORTED)
|
|
196
|
+
|
|
197
|
+
def mark_reported(exception)
|
|
198
|
+
exception.instance_variable_set(REPORTED, true) unless exception.frozen?
|
|
199
|
+
end
|
|
200
|
+
|
|
201
|
+
def raised(exception)
|
|
202
|
+
raise exception
|
|
203
|
+
rescue exception.class => error
|
|
204
|
+
error
|
|
205
|
+
end
|
|
206
|
+
end
|
|
207
|
+
end
|
|
208
|
+
|
|
209
|
+
require_relative 'tlm/railtie' if defined?(Rails::Railtie)
|
metadata
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: tlm
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.1.0
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- Hullop
|
|
8
|
+
bindir: bin
|
|
9
|
+
cert_chain: []
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
|
+
dependencies: []
|
|
12
|
+
description: Error reporting for Ruby, Rack, Rails, ActiveJob and Sidekiq apps, sent
|
|
13
|
+
in the background to Hullop Telemetry (Tlm).
|
|
14
|
+
executables: []
|
|
15
|
+
extensions: []
|
|
16
|
+
extra_rdoc_files: []
|
|
17
|
+
files:
|
|
18
|
+
- CHANGELOG.md
|
|
19
|
+
- LICENSE
|
|
20
|
+
- README.md
|
|
21
|
+
- lib/tlm.rb
|
|
22
|
+
- lib/tlm/active_job.rb
|
|
23
|
+
- lib/tlm/backtrace.rb
|
|
24
|
+
- lib/tlm/breadcrumbs.rb
|
|
25
|
+
- lib/tlm/config.rb
|
|
26
|
+
- lib/tlm/context.rb
|
|
27
|
+
- lib/tlm/event.rb
|
|
28
|
+
- lib/tlm/heartbeat.rb
|
|
29
|
+
- lib/tlm/http.rb
|
|
30
|
+
- lib/tlm/job_args.rb
|
|
31
|
+
- lib/tlm/rack.rb
|
|
32
|
+
- lib/tlm/railtie.rb
|
|
33
|
+
- lib/tlm/sender.rb
|
|
34
|
+
- lib/tlm/sidekiq.rb
|
|
35
|
+
- lib/tlm/source.rb
|
|
36
|
+
- lib/tlm/tasks.rb
|
|
37
|
+
- lib/tlm/test_command.rb
|
|
38
|
+
- lib/tlm/text.rb
|
|
39
|
+
- lib/tlm/version.rb
|
|
40
|
+
homepage: https://tlm.hullop.com
|
|
41
|
+
licenses:
|
|
42
|
+
- MIT
|
|
43
|
+
metadata:
|
|
44
|
+
homepage_uri: https://tlm.hullop.com
|
|
45
|
+
changelog_uri: https://rubygems.org/gems/tlm/versions
|
|
46
|
+
rubygems_mfa_required: 'true'
|
|
47
|
+
rdoc_options: []
|
|
48
|
+
require_paths:
|
|
49
|
+
- lib
|
|
50
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
51
|
+
requirements:
|
|
52
|
+
- - ">="
|
|
53
|
+
- !ruby/object:Gem::Version
|
|
54
|
+
version: 3.4.0
|
|
55
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
56
|
+
requirements:
|
|
57
|
+
- - ">="
|
|
58
|
+
- !ruby/object:Gem::Version
|
|
59
|
+
version: '0'
|
|
60
|
+
requirements: []
|
|
61
|
+
rubygems_version: 4.0.20
|
|
62
|
+
specification_version: 4
|
|
63
|
+
summary: Reports your Ruby app's errors and heartbeats to Hullop Telemetry.
|
|
64
|
+
test_files: []
|