sillydev 1.0.0

data/lib/sillydev/monitoring.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require_relative "version"
+require_relative "monitoring/client"
+
+module SillyDev
+  # Opt-in application monitoring for Silly Development.
+  #
+  # Nothing is sent, no thread is started, no hook is installed and no environment variable is read
+  # until you call SillyDev::Monitoring.init with a monitoring key (or with SILLYDEV_MONITORING_KEY
+  # set):
+  #
+  #   require "sillydev/monitoring"
+  #
+  #   SillyDev::Monitoring.init # reads SILLYDEV_MONITORING_KEY; does nothing without a key
+  #   SillyDev::Monitoring.increment("orders.created", tags: { plan: "free" })
+  #
+  # Until then every method here does nothing and never raises. require "sillydev" does not load
+  # this file. Docs: https://sillydev.co.uk/docs/monitoring
+  module Monitoring
+    KEY_RE = /\Asdevm_([1-9][0-9]*)_/
+
+    @current = nil
+    @init_lock = Mutex.new
+    @collectors = []
+    @hooks_installed = false
+
+    class << self
+      # Called with the client once per flush window, on its thread (the Discord integration adds
+      # one for its gauges).
+      attr_reader :collectors
+
+      # "sdevm_<N>_..." gives "https://ingest<N>.sillydev.co.uk" (nil for anything else).
+      def endpoint_for_key(key)
+        match = KEY_RE.match(key.to_s)
+        match ? "https://ingest#{match[1]}.sillydev.co.uk" : nil
+      end
+
+      # Starts monitoring. Without a key (argument or SILLYDEV_MONITORING_KEY) nothing happens.
+      #
+      # Options left as nil fall back to SILLYDEV_MONITORING_KEY, SILLYDEV_MONITORING_URL,
+      # SILLYDEV_MONITORING_SERVICE, SILLYDEV_MONITORING_ENVIRONMENT and SILLYDEV_MONITORING_RELEASE.
+      # SILLYDEV_MONITORING_DISABLED=1 (or enabled: false) turns it off. Calling init again shuts the
+      # previous client down and starts a new one. Returns the client; client.enabled? says whether
+      # it is sending.
+      def init(key = nil, endpoint: nil, service: nil, environment: nil, release: nil, runtime_metrics: true,
+               capture_unhandled: true, sample_rate: 1.0, before_send: nil, flush_interval: 10.0,
+               max_buffer_bytes: 1_000_000, slow_threshold_ms: 1000, logger: nil, debug: false, enabled: true)
+        @init_lock.synchronize do
+          previous = @current
+          @current = nil
+          previous&.shutdown(2.0)
+
+          key ||= env("SILLYDEV_MONITORING_KEY")
+          disabled = %w[1 true yes on].include?(env("SILLYDEV_MONITORING_DISABLED").to_s.downcase)
+          endpoint ||= env("SILLYDEV_MONITORING_URL")
+          active = enabled && !disabled && key ? true : false
+          if active && endpoint.nil?
+            endpoint = endpoint_for_key(key)
+            if endpoint.nil?
+              warn "sillydev.monitoring: the key is not a server key (sdevm_<n>_...) and no endpoint was given; " \
+                   "monitoring is off"
+              active = false
+            end
+          end
+
+          client = Client.new(
+            key, endpoint: endpoint, service: service || env("SILLYDEV_MONITORING_SERVICE"),
+                 environment: environment || env("SILLYDEV_MONITORING_ENVIRONMENT"),
+                 release: release || env("SILLYDEV_MONITORING_RELEASE"), runtime_metrics: runtime_metrics,
+                 capture_unhandled: capture_unhandled, sample_rate: sample_rate, before_send: before_send,
+                 flush_interval: flush_interval, max_buffer_bytes: max_buffer_bytes,
+                 slow_threshold_ms: slow_threshold_ms, logger: logger, debug: debug, active: active
+          )
+          @current = client
+          if client.active?
+            install_process_hooks
+            client.start
+          end
+          client
+        end
+      end
+
+      # The client made by the last init, if any.
+      def client
+        @current
+      end
+
+      # True while a client with a key is running and has not been stopped.
+      def enabled?
+        client = @current
+        client ? client.enabled? : false
+      end
+
+      # Adds value to a counter.
+      def increment(name, value = 1, tags: nil)
+        @current&.increment(name, value, tags)
+        nil
+      end
+
+      # Records the latest value of a gauge.
+      def gauge(name, value, tags: nil)
+        @current&.gauge(name, value, tags)
+        nil
+      end
+
+      # Records a duration in milliseconds in a histogram.
+      def timing(name, ms, tags: nil)
+        @current&.timing(name, ms, tags)
+        nil
+      end
+
+      # Times the block into the name histogram (and as a slow operation over the threshold), and
+      # returns the block's value.
+      def time(name, tags: nil)
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        yield
+      ensure
+        finish_timer(name, start, tags) if start
+      end
+
+      # Records something that happened (a deploy, a sign-up). Subject to sample_rate.
+      def event(name, attributes = nil)
+        @current&.event(name, attributes)
+        nil
+      end
+
+      # Reports an exception (the one being handled, $!, when none is given).
+      def capture_exception(exception = $!, tags: nil, context: nil, fingerprint: nil, handled: true)
+        @current&.capture_exception(exception, tags: tags, context: context, fingerprint: fingerprint, handled: handled)
+        nil
+      end
+
+      # Reports a message as an error without an exception.
+      def capture_message(message, level: "error", tags: nil, context: nil)
+        @current&.capture_message(message, level: level, tags: tags, context: context)
+        nil
+      end
+
+      # Reports a slow operation (kind is "http", "discord", "task" or "custom").
+      def record_slow(name, duration_ms, kind: "custom", tags: nil, attributes: nil)
+        @current&.record_slow(name, duration_ms, kind: kind, tags: tags, attributes: attributes)
+        nil
+      end
+
+      # Marks this instance alive now (sent straight away by the background thread).
+      def heartbeat
+        @current&.heartbeat
+        nil
+      end
+
+      # Sends everything buffered now. True when nothing is left to send.
+      def flush(timeout = 2.0)
+        client = @current
+        client ? client.flush(timeout) : false
+      end
+
+      # Flushes and stops. Later calls do nothing until init is called again.
+      def shutdown(timeout = 2.0)
+        client = @init_lock.synchronize do
+          c = @current
+          @current = nil
+          c
+        end
+        client&.shutdown(timeout)
+        nil
+      end
+
+      private
+
+      def env(name)
+        value = ENV.fetch(name, nil)
+        value.nil? || value.strip.empty? ? nil : value.strip
+      end
+
+      def finish_timer(name, start, tags)
+        client = @current
+        return unless client&.enabled?
+
+        ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000.0
+        client.timing(name, ms, tags)
+        client.maybe_slow(name, ms, "task", tags)
+      end
+
+      def install_process_hooks
+        return if @hooks_installed
+
+        @hooks_installed = true
+        at_exit { Monitoring.send(:at_exit_hook, $!) }
+        Process.singleton_class.prepend(ForkHook) if Process.respond_to?(:_fork)
+      end
+
+      # Reports the exception that is ending the program (unless it is a normal exit or Ctrl+C),
+      # then flushes and stops.
+      def at_exit_hook(error)
+        client = @current
+        return if client.nil?
+
+        if error && client.capture_unhandled? && !error.is_a?(SystemExit) && !error.is_a?(Interrupt) &&
+           !error.is_a?(SignalException)
+          client.capture_exception(error, handled: false)
+        end
+        client.shutdown(2.0)
+      rescue StandardError
+        nil
+      end
+
+      def after_fork
+        @init_lock = Mutex.new
+        client = @current
+        client.after_fork if client&.enabled?
+      rescue StandardError
+        nil
+      end
+    end
+
+    # Restarts the client's thread in a child process (Ruby 3.1 and later call Process._fork for
+    # every fork).
+    module ForkHook
+      def _fork
+        pid = super
+        Monitoring.send(:after_fork) if pid.zero?
+        pid
+      end
+    end
+  end
+end