zharp 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/zharp.rb ADDED
@@ -0,0 +1,218 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "monitor"
4
+ require "opentelemetry/sdk"
5
+ require "opentelemetry/exporter/otlp"
6
+ require "opentelemetry-logs-sdk"
7
+ require "opentelemetry-exporter-otlp-logs"
8
+ require_relative "zharp/instrumentations"
9
+
10
+ require_relative "zharp/version"
11
+ require_relative "zharp/config"
12
+ require_relative "zharp/headers"
13
+ require_relative "zharp/bodies"
14
+ require_relative "zharp/capture"
15
+ require_relative "zharp/source"
16
+ require_relative "zharp/errors"
17
+ require_relative "zharp/db_errors"
18
+ require_relative "zharp/context"
19
+ require_relative "zharp/stamp"
20
+ require_relative "zharp/logs"
21
+ require_relative "zharp/fork"
22
+ require_relative "zharp/rack"
23
+ require_relative "zharp/setup"
24
+
25
+ # Zharp Application Monitoring for Ruby.
26
+ #
27
+ # Rails: bundle add zharp, set ZHARP_KEY. That's all (a Railtie starts it).
28
+ # Rack apps: require "zharp"; use Zharp::Rack (in config.ru)
29
+ # Plain Ruby: require "zharp"; Zharp.init(service: "billing-worker")
30
+ #
31
+ # Requests, database queries, outgoing HTTP calls and jobs are traced, errors become Zharp issues
32
+ # (each once, with the code that ran), and each log line written during a request ends with its
33
+ # trace and span id for the Zharp agent that reads the app's output (ZHARP_LOGS=true sends the
34
+ # logs from the SDK instead, where there is no agent). A thin layer over the official
35
+ # OpenTelemetry SDK: anything you instrument with OpenTelemetry yourself is sent too.
36
+ module Zharp
37
+ @state = nil
38
+ @lock = Monitor.new
39
+
40
+ class << self
41
+ # Start sending traces, errors and logs to Zharp. Call once, after your gems are loaded (Rails
42
+ # calls it for you). Anything not passed is read from the environment: ZHARP_KEY (in Rails also
43
+ # credentials.zharp.key), ZHARP_SERVICE (then OTEL_SERVICE_NAME), ZHARP_ENVIRONMENT,
44
+ # ZHARP_RELEASE, ZHARP_ENDPOINT, ZHARP_SAMPLE_RATE, ZHARP_TRACING, ZHARP_LOGS,
45
+ # ZHARP_LOG_CORRELATION, ZHARP_CAPTURE_HEADERS, ZHARP_CAPTURE_QUERY_ERRORS,
46
+ # ZHARP_CAPTURE_SOURCE_CONTEXT. ZHARP_DISABLED=true turns it off.
47
+ #
48
+ # Options: key:, service:, environment:, release:, endpoint:, sample_rate: (0.0-1.0),
49
+ # tracing: (false = logs and errors only), logs: (send log lines from the SDK; default false),
50
+ # log_correlation: (the ids at the end of each line; default true), capture_headers: (false, or
51
+ # { redact: ["x-tenant"] }), capture_query_errors:, capture_source_context:, capture_uncaught:,
52
+ # instrument: (false = no automatic instrumentation), instrumentation: (options per
53
+ # OpenTelemetry instrumentation, by class name), quiet: (no startup line).
54
+ #
55
+ # Returns true when it started. Never raises.
56
+ def init(**args)
57
+ @lock.synchronize do
58
+ return true if @state
59
+ return false if Config.disabled?
60
+
61
+ options = Config.resolve(args)
62
+ unless options
63
+ Config.announce("No key — set ZHARP_KEY or pass key: to Zharp.init. Nothing is sent.") unless args[:quiet]
64
+ return false
65
+ end
66
+ @state = Setup.start(options, exporters: args[:_exporters], batch: args.fetch(:_batch, true))
67
+ install_exit_hook(options)
68
+ end
69
+ Config.announce(Setup.describe(@state)) unless args[:quiet]
70
+ true
71
+ rescue StandardError => e
72
+ Config.announce("Could not start: #{e.message}")
73
+ false
74
+ end
75
+
76
+ def active?
77
+ !@state.nil?
78
+ end
79
+
80
+ def options
81
+ @state&.options
82
+ end
83
+
84
+ def otel_logger
85
+ @state&.logger
86
+ end
87
+
88
+ # Report an exception you rescued. It becomes a Zharp issue (marked handled), with the trace,
89
+ # user and session of the current request.
90
+ #
91
+ # rescue PaymentError => e
92
+ # Zharp.capture_error(e, order_id: order.id)
93
+ def capture_error(error, attributes = {})
94
+ report(error, handled: true, attributes: attributes)
95
+ end
96
+
97
+ # @api private: one report, as a log record in the current context.
98
+ def report(error, handled:, attributes: {}, fatal: false, context: nil)
99
+ return if @state.nil? || !error.is_a?(Exception) || Errors.reported?(error)
100
+
101
+ Errors.mark(error, handled: handled)
102
+ attrs = Context.plain(attributes)
103
+ attrs.merge!(Errors.query_of(error))
104
+ attrs.merge!(Errors.attributes(error, handled))
105
+ message = attrs["exception.message"].to_s
106
+ Logs.emit(fatal ? "FATAL" : "ERROR", fatal ? 21 : 17, message.empty? ? attrs["exception.type"] : "#{attrs['exception.type']}: #{message}", attrs, context)
107
+ rescue StandardError => e
108
+ debug("report: #{e.message}")
109
+ end
110
+
111
+ # The user of the current request (enduser.id), on its spans, logs and errors from here on.
112
+ # Outside a request it applies to everything after. A browser or mobile app using a Zharp SDK
113
+ # already sends its user with each request.
114
+ def set_user(id: nil, email: nil, name: nil)
115
+ Context.set_user(id: id, email: email, name: name)
116
+ rescue StandardError
117
+ nil
118
+ end
119
+
120
+ def clear_user
121
+ Context.clear_user
122
+ rescue StandardError
123
+ nil
124
+ end
125
+
126
+ # An attribute on every span and log from now on (nil removes it).
127
+ def set_tag(key, value)
128
+ Context.set_tag(key, value)
129
+ rescue StandardError
130
+ nil
131
+ end
132
+
133
+ # A span around some work: Zharp.start_span("render invoice") { render(invoice) }. An exception
134
+ # that escapes is recorded on the span and raised on. With tracing off the block runs as is.
135
+ def start_span(name, attributes: {}, kind: :internal, &block)
136
+ tracer = @state&.tracer || ::OpenTelemetry.tracer_provider.tracer("zharp", VERSION)
137
+ tracer.in_span(name, attributes: Context.plain(attributes), kind: kind, &block)
138
+ end
139
+
140
+ # Zharp.log.info("order paid", order_id: 1): debug, info, warn, error, fatal. Sent whether or
141
+ # not ZHARP_LOGS is on: these are the lines you want in Zharp from the SDK itself.
142
+ def log
143
+ @log ||= LogApi.new
144
+ end
145
+
146
+ # Send everything queued now, waiting up to timeout seconds: at the end of a script or job.
147
+ def flush(timeout: 5)
148
+ state = @state
149
+ return true unless state
150
+
151
+ ok = true
152
+ Errors.db_errors&.force_flush
153
+ [state.tracer_provider, state.logger_provider].compact.each do |provider|
154
+ ok = provider.force_flush(timeout: timeout) == 0 && ok
155
+ end
156
+ ok
157
+ rescue StandardError
158
+ false
159
+ end
160
+
161
+ # Send what's left and stop. Runs by itself when the program exits.
162
+ def shutdown(timeout: 5)
163
+ state = nil
164
+ @lock.synchronize do
165
+ state = @state
166
+ @state = nil
167
+ end
168
+ return unless state
169
+
170
+ Errors.db_errors&.force_flush
171
+ [state.tracer_provider, state.logger_provider].compact.each do |provider|
172
+ provider.shutdown(timeout: timeout)
173
+ rescue StandardError
174
+ nil
175
+ end
176
+ end
177
+
178
+ def debug(message)
179
+ Config.announce("debug: #{message}") if Config.flag(ENV["ZHARP_DEBUG"])
180
+ end
181
+
182
+ private
183
+
184
+ # A script that crashes: the exception that ends it is reported (handled=false) and sent before
185
+ # the process exits; then everything left is sent.
186
+ def install_exit_hook(options)
187
+ return if @exit_hook
188
+
189
+ @exit_hook = true
190
+ at_exit do
191
+ error = $!
192
+ if options.capture_uncaught && error && !error.is_a?(SystemExit) && !error.is_a?(Interrupt) &&
193
+ !error.is_a?(SignalException) && !Errors.reported?(error)
194
+ report(error, handled: false, fatal: true)
195
+ end
196
+ # A flush, not a shutdown: at_exit blocks run last-registered first, and one registered
197
+ # before Zharp started (Minitest's, a CLI framework's) may still do traced work after this.
198
+ flush(timeout: 5)
199
+ end
200
+ end
201
+ end
202
+
203
+ class LogApi
204
+ def debug(message, attributes = {}) = Logs.emit("DEBUG", 5, message, Context.plain(attributes))
205
+ def info(message, attributes = {}) = Logs.emit("INFO", 9, message, Context.plain(attributes))
206
+ def warn(message, attributes = {}) = Logs.emit("WARN", 13, message, Context.plain(attributes))
207
+ def fatal(message, attributes = {}) = Logs.emit("FATAL", 21, message, Context.plain(attributes))
208
+
209
+ # An exception (as the message) is reported as an error, handled.
210
+ def error(message, attributes = {})
211
+ return Zharp.capture_error(message, attributes) if message.is_a?(Exception)
212
+
213
+ Logs.emit("ERROR", 17, message, Context.plain(attributes))
214
+ end
215
+ end
216
+ end
217
+
218
+ require_relative "zharp/railtie" if defined?(::Rails::Railtie)
metadata ADDED
@@ -0,0 +1,341 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: zharp
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0
5
+ platform: ruby
6
+ authors:
7
+ - Zharp
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: opentelemetry-sdk
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - "~>"
17
+ - !ruby/object:Gem::Version
18
+ version: '1.13'
19
+ type: :runtime
20
+ prerelease: false
21
+ version_requirements: !ruby/object:Gem::Requirement
22
+ requirements:
23
+ - - "~>"
24
+ - !ruby/object:Gem::Version
25
+ version: '1.13'
26
+ - !ruby/object:Gem::Dependency
27
+ name: opentelemetry-exporter-otlp
28
+ requirement: !ruby/object:Gem::Requirement
29
+ requirements:
30
+ - - "~>"
31
+ - !ruby/object:Gem::Version
32
+ version: '0.37'
33
+ type: :runtime
34
+ prerelease: false
35
+ version_requirements: !ruby/object:Gem::Requirement
36
+ requirements:
37
+ - - "~>"
38
+ - !ruby/object:Gem::Version
39
+ version: '0.37'
40
+ - !ruby/object:Gem::Dependency
41
+ name: opentelemetry-logs-sdk
42
+ requirement: !ruby/object:Gem::Requirement
43
+ requirements:
44
+ - - "~>"
45
+ - !ruby/object:Gem::Version
46
+ version: '0.8'
47
+ type: :runtime
48
+ prerelease: false
49
+ version_requirements: !ruby/object:Gem::Requirement
50
+ requirements:
51
+ - - "~>"
52
+ - !ruby/object:Gem::Version
53
+ version: '0.8'
54
+ - !ruby/object:Gem::Dependency
55
+ name: opentelemetry-exporter-otlp-logs
56
+ requirement: !ruby/object:Gem::Requirement
57
+ requirements:
58
+ - - "~>"
59
+ - !ruby/object:Gem::Version
60
+ version: '0.7'
61
+ type: :runtime
62
+ prerelease: false
63
+ version_requirements: !ruby/object:Gem::Requirement
64
+ requirements:
65
+ - - "~>"
66
+ - !ruby/object:Gem::Version
67
+ version: '0.7'
68
+ - !ruby/object:Gem::Dependency
69
+ name: opentelemetry-instrumentation-rack
70
+ requirement: !ruby/object:Gem::Requirement
71
+ requirements:
72
+ - - "~>"
73
+ - !ruby/object:Gem::Version
74
+ version: '0.32'
75
+ type: :runtime
76
+ prerelease: false
77
+ version_requirements: !ruby/object:Gem::Requirement
78
+ requirements:
79
+ - - "~>"
80
+ - !ruby/object:Gem::Version
81
+ version: '0.32'
82
+ - !ruby/object:Gem::Dependency
83
+ name: opentelemetry-instrumentation-rails
84
+ requirement: !ruby/object:Gem::Requirement
85
+ requirements:
86
+ - - "~>"
87
+ - !ruby/object:Gem::Version
88
+ version: '0.42'
89
+ type: :runtime
90
+ prerelease: false
91
+ version_requirements: !ruby/object:Gem::Requirement
92
+ requirements:
93
+ - - "~>"
94
+ - !ruby/object:Gem::Version
95
+ version: '0.42'
96
+ - !ruby/object:Gem::Dependency
97
+ name: opentelemetry-instrumentation-sinatra
98
+ requirement: !ruby/object:Gem::Requirement
99
+ requirements:
100
+ - - "~>"
101
+ - !ruby/object:Gem::Version
102
+ version: '0.31'
103
+ type: :runtime
104
+ prerelease: false
105
+ version_requirements: !ruby/object:Gem::Requirement
106
+ requirements:
107
+ - - "~>"
108
+ - !ruby/object:Gem::Version
109
+ version: '0.31'
110
+ - !ruby/object:Gem::Dependency
111
+ name: opentelemetry-instrumentation-grape
112
+ requirement: !ruby/object:Gem::Requirement
113
+ requirements:
114
+ - - "~>"
115
+ - !ruby/object:Gem::Version
116
+ version: '0.7'
117
+ type: :runtime
118
+ prerelease: false
119
+ version_requirements: !ruby/object:Gem::Requirement
120
+ requirements:
121
+ - - "~>"
122
+ - !ruby/object:Gem::Version
123
+ version: '0.7'
124
+ - !ruby/object:Gem::Dependency
125
+ name: opentelemetry-instrumentation-net_http
126
+ requirement: !ruby/object:Gem::Requirement
127
+ requirements:
128
+ - - "~>"
129
+ - !ruby/object:Gem::Version
130
+ version: '0.30'
131
+ type: :runtime
132
+ prerelease: false
133
+ version_requirements: !ruby/object:Gem::Requirement
134
+ requirements:
135
+ - - "~>"
136
+ - !ruby/object:Gem::Version
137
+ version: '0.30'
138
+ - !ruby/object:Gem::Dependency
139
+ name: opentelemetry-instrumentation-faraday
140
+ requirement: !ruby/object:Gem::Requirement
141
+ requirements:
142
+ - - "~>"
143
+ - !ruby/object:Gem::Version
144
+ version: '0.33'
145
+ type: :runtime
146
+ prerelease: false
147
+ version_requirements: !ruby/object:Gem::Requirement
148
+ requirements:
149
+ - - "~>"
150
+ - !ruby/object:Gem::Version
151
+ version: '0.33'
152
+ - !ruby/object:Gem::Dependency
153
+ name: opentelemetry-instrumentation-http
154
+ requirement: !ruby/object:Gem::Requirement
155
+ requirements:
156
+ - - "~>"
157
+ - !ruby/object:Gem::Version
158
+ version: '0.30'
159
+ type: :runtime
160
+ prerelease: false
161
+ version_requirements: !ruby/object:Gem::Requirement
162
+ requirements:
163
+ - - "~>"
164
+ - !ruby/object:Gem::Version
165
+ version: '0.30'
166
+ - !ruby/object:Gem::Dependency
167
+ name: opentelemetry-instrumentation-httpx
168
+ requirement: !ruby/object:Gem::Requirement
169
+ requirements:
170
+ - - "~>"
171
+ - !ruby/object:Gem::Version
172
+ version: '0.8'
173
+ type: :runtime
174
+ prerelease: false
175
+ version_requirements: !ruby/object:Gem::Requirement
176
+ requirements:
177
+ - - "~>"
178
+ - !ruby/object:Gem::Version
179
+ version: '0.8'
180
+ - !ruby/object:Gem::Dependency
181
+ name: opentelemetry-instrumentation-pg
182
+ requirement: !ruby/object:Gem::Requirement
183
+ requirements:
184
+ - - "~>"
185
+ - !ruby/object:Gem::Version
186
+ version: '0.37'
187
+ type: :runtime
188
+ prerelease: false
189
+ version_requirements: !ruby/object:Gem::Requirement
190
+ requirements:
191
+ - - "~>"
192
+ - !ruby/object:Gem::Version
193
+ version: '0.37'
194
+ - !ruby/object:Gem::Dependency
195
+ name: opentelemetry-instrumentation-mysql2
196
+ requirement: !ruby/object:Gem::Requirement
197
+ requirements:
198
+ - - "~>"
199
+ - !ruby/object:Gem::Version
200
+ version: '0.34'
201
+ type: :runtime
202
+ prerelease: false
203
+ version_requirements: !ruby/object:Gem::Requirement
204
+ requirements:
205
+ - - "~>"
206
+ - !ruby/object:Gem::Version
207
+ version: '0.34'
208
+ - !ruby/object:Gem::Dependency
209
+ name: opentelemetry-instrumentation-trilogy
210
+ requirement: !ruby/object:Gem::Requirement
211
+ requirements:
212
+ - - "~>"
213
+ - !ruby/object:Gem::Version
214
+ version: '0.69'
215
+ type: :runtime
216
+ prerelease: false
217
+ version_requirements: !ruby/object:Gem::Requirement
218
+ requirements:
219
+ - - "~>"
220
+ - !ruby/object:Gem::Version
221
+ version: '0.69'
222
+ - !ruby/object:Gem::Dependency
223
+ name: opentelemetry-instrumentation-redis
224
+ requirement: !ruby/object:Gem::Requirement
225
+ requirements:
226
+ - - "~>"
227
+ - !ruby/object:Gem::Version
228
+ version: '0.29'
229
+ type: :runtime
230
+ prerelease: false
231
+ version_requirements: !ruby/object:Gem::Requirement
232
+ requirements:
233
+ - - "~>"
234
+ - !ruby/object:Gem::Version
235
+ version: '0.29'
236
+ - !ruby/object:Gem::Dependency
237
+ name: opentelemetry-instrumentation-sidekiq
238
+ requirement: !ruby/object:Gem::Requirement
239
+ requirements:
240
+ - - "~>"
241
+ - !ruby/object:Gem::Version
242
+ version: '0.29'
243
+ type: :runtime
244
+ prerelease: false
245
+ version_requirements: !ruby/object:Gem::Requirement
246
+ requirements:
247
+ - - "~>"
248
+ - !ruby/object:Gem::Version
249
+ version: '0.29'
250
+ - !ruby/object:Gem::Dependency
251
+ name: opentelemetry-instrumentation-resque
252
+ requirement: !ruby/object:Gem::Requirement
253
+ requirements:
254
+ - - "~>"
255
+ - !ruby/object:Gem::Version
256
+ version: '0.9'
257
+ type: :runtime
258
+ prerelease: false
259
+ version_requirements: !ruby/object:Gem::Requirement
260
+ requirements:
261
+ - - "~>"
262
+ - !ruby/object:Gem::Version
263
+ version: '0.9'
264
+ - !ruby/object:Gem::Dependency
265
+ name: opentelemetry-instrumentation-delayed_job
266
+ requirement: !ruby/object:Gem::Requirement
267
+ requirements:
268
+ - - "~>"
269
+ - !ruby/object:Gem::Version
270
+ version: '0.26'
271
+ type: :runtime
272
+ prerelease: false
273
+ version_requirements: !ruby/object:Gem::Requirement
274
+ requirements:
275
+ - - "~>"
276
+ - !ruby/object:Gem::Version
277
+ version: '0.26'
278
+ description: |
279
+ One gem for Zharp Application Monitoring. Rails starts it by itself; Rack apps add `use Zharp::Rack`;
280
+ scripts and workers call `Zharp.init`. Built on the official OpenTelemetry SDK: requests, database
281
+ queries, outgoing HTTP calls and jobs are traced, each error is reported once with the code that
282
+ ran, headers are recorded with secrets filtered, failed queries carry their statement, and each log
283
+ line in a request ends with its trace and span id.
284
+ email:
285
+ - support@zharp.io
286
+ executables: []
287
+ extensions: []
288
+ extra_rdoc_files: []
289
+ files:
290
+ - CHANGELOG.md
291
+ - LICENSE
292
+ - README.md
293
+ - lib/generators/zharp/install/install_generator.rb
294
+ - lib/generators/zharp/install/templates/zharp.rb.tt
295
+ - lib/zharp.rb
296
+ - lib/zharp/bodies.rb
297
+ - lib/zharp/capture.rb
298
+ - lib/zharp/config.rb
299
+ - lib/zharp/context.rb
300
+ - lib/zharp/db_errors.rb
301
+ - lib/zharp/errors.rb
302
+ - lib/zharp/fork.rb
303
+ - lib/zharp/headers.rb
304
+ - lib/zharp/instrumentations.rb
305
+ - lib/zharp/logs.rb
306
+ - lib/zharp/rack.rb
307
+ - lib/zharp/railtie.rb
308
+ - lib/zharp/setup.rb
309
+ - lib/zharp/sidekiq.rb
310
+ - lib/zharp/source.rb
311
+ - lib/zharp/stamp.rb
312
+ - lib/zharp/version.rb
313
+ homepage: https://zharp.io
314
+ licenses:
315
+ - MIT
316
+ metadata:
317
+ homepage_uri: https://zharp.io
318
+ source_code_uri: https://github.com/zharp-io/zharp-ruby-lib
319
+ changelog_uri: https://github.com/zharp-io/zharp-ruby-lib/blob/main/CHANGELOG.md
320
+ documentation_uri: https://zharp.io/docs
321
+ bug_tracker_uri: https://github.com/zharp-io/zharp-ruby-lib/issues
322
+ rubygems_mfa_required: 'true'
323
+ rdoc_options: []
324
+ require_paths:
325
+ - lib
326
+ required_ruby_version: !ruby/object:Gem::Requirement
327
+ requirements:
328
+ - - ">="
329
+ - !ruby/object:Gem::Version
330
+ version: '3.3'
331
+ required_rubygems_version: !ruby/object:Gem::Requirement
332
+ requirements:
333
+ - - ">="
334
+ - !ruby/object:Gem::Version
335
+ version: '0'
336
+ requirements: []
337
+ rubygems_version: 3.6.9
338
+ specification_version: 4
339
+ summary: 'Zharp Application Monitoring for Ruby: traces, errors and logs for Rails,
340
+ Rack, Sinatra, Sidekiq and plain Ruby.'
341
+ test_files: []