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 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
@@ -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