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.
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,10 @@
1
+ require 'rake'
2
+ require 'tlm'
3
+
4
+ namespace :tlm do
5
+ desc 'Sends a test event to Tlm and prints the answer'
6
+ task :test do
7
+ status = Tlm::TestCommand.new.run
8
+ exit(status) unless status.zero?
9
+ end
10
+ end
@@ -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
@@ -0,0 +1,3 @@
1
+ module Tlm
2
+ VERSION = '0.1.0'
3
+ end
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: []