logdash 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70a2fab7f429c39958bd7ead8fb4e65832e00210971ccc567ccf17cef7eb31dc
-  data.tar.gz: cd6f25cd0edcdf3d1a2ff0bb4318e35dc3e1e8817d86626a6398aeb38788eaf6
+  metadata.gz: 0c20102d3b1fbe508e7520c30fcf14e87eb7cb07e315bc90972b45a6d4d6b873
+  data.tar.gz: 32dc2ed4ef2bfbbd122c4da789cb68bdde85ba32fbb10400fec6a92853bbcde1
 SHA512:
-  metadata.gz: 39e5fa2e4d9a288b36c27f598941c4b4b74ab5b37c87db76ca034abdb8a097a9e8946db77ade930bcd97d26bf544fe900bab5ad54be9d95cd876accdd0cac2f8
-  data.tar.gz: 7d4d669403861177cd8a2aac65be449185aebf73f463be83db7847a7b49b9c9b886d80ee17016bb6d874ef08e90a54759ac09ae12e64dc2005c804a8d0eed8f9
+  metadata.gz: 43c5dad64201cda45a6411302aeca58dab55c739d33fb525b56453b5c3a4b10ba2df707f18914df4ebb9586d23fd75531f4598d9506a3cc82365583f94063fc3
+  data.tar.gz: 6597038b2ea87972c0de8b95a3c4cd8e6df5a7fb1ca07ce759c1cb4b0a4340aa85320ebc7f77b0d6b0c67f2dbd07ce3ff6c8295b34b826351a492550c2404a2e

data/README.md

@@ -49,12 +49,31 @@ logger.silly('Silly level logging')
 require 'logdash'
 
 logdash_client = Logdash.create(api_key: "YOUR_API_KEY")
-metrics = $logdash_client[:metrics]
+metrics = logdash_client[:metrics]
 
 metrics.set('users', 0)
 metrics.mutate('users', 1)
 ```
 
+## Events
+
+```ruby
+require 'logdash'
+
+logdash_client = Logdash.create(api_key: "YOUR_API_KEY")
+events = logdash_client[:events]
+
+events.track('agent_run', { agent: 'support', steps: 4, success: true }, user_id: current_user.id)
+```
+
+Events show up in your domain's Analytics as goals, with a daily trend.
+Pass `user_id` for signed-in users, so one person counts once across your website and apps.
+Without it, Logdash counts a visitor of that app that changes every day.
+Never put personal data in props.
+
+Events are sent in the background, and a script waits for them before it exits.
+Call `events.flush` to wait for them sooner, for example before a serverless function returns.
+
 ## Ruby on Rails
 
 In a Ruby on Rails application, you can use an initializer to configure Logdash. Create a new file in `config/initializers/logdash.rb` with the following content:
@@ -66,18 +85,32 @@ ActiveSupport.on_load(:after_initialize) do
   $logdash_client = Logdash.create(api_key: "YOUR_API_KEY")
   $logger = $logdash_client[:logger]
   $metrics = $logdash_client[:metrics]
+  $events = $logdash_client[:events]
 end
 ```
 
-This will make `$logger` and `$metrics` available throughout your Ruby on Rails application.
+This will make `$logger`, `$metrics` and `$events` available throughout your Ruby on Rails application.
 
 ## Configuration
 
-| Parameter | Required | Default | Description                                                                                                              |
-| --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `api_key` | no       | -       | Api key used to authorize against logdash servers. If you don't provide one, logs will be logged into local console only |
-| `host`    | no       | `https://api.logdash.io` | Custom API host, useful with self-hosted instances                                                                       |
-| `verbose` | no       | `false` | Useful for debugging purposes                                                                                            |
+| Parameter | Required | Default                  | Description                                                                                                     |
+| --------- | -------- | ------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `api_key` | no       | -                        | API key used to authorize against Logdash servers. Without one, logs and events print to the local console only |
+| `host`    | no       | `https://api.logdash.io` | Custom API host, useful with self-hosted instances                                                              |
+| `verbose` | no       | `false`                  | Useful for debugging purposes                                                                                   |
+| `app`     | no       | -                        | Name of the app sending logs, metrics and events. See [Apps](#apps)                                             |
+
+### Apps
+
+A domain key is shared by all apps of a domain, for example a desktop app, an API and a landing page.
+`app` names the app this client runs in, so the dashboard can filter logs, metrics and events by app:
+
+```ruby
+logdash_client = Logdash.create(api_key: "YOUR_DOMAIN_KEY", app: "api")
+```
+
+Logdash creates the app on first use.
+Older service keys ignore `app`.
 
 ## View
 

data/lib/logdash/client.rb

@@ -3,41 +3,44 @@
 require_relative 'logger'
 require_relative 'metrics'
 require_relative 'http_log_sync'
+require_relative 'events'
 
 module Logdash
   class Client
-    attr_reader :logger, :metrics
+    attr_reader :logger, :metrics, :events
 
-    def initialize(api_key: nil, host: 'https://api.logdash.io', verbose: false)
+    def initialize(api_key: nil, host: 'https://api.logdash.io', verbose: false, app: nil)
       @api_key = api_key
       @host = host
       @verbose = verbose
+      @app = app
 
-      log_sync_instance = create_log_sync(api_key, host, verbose)
+      log_sync_instance = create_log_sync(api_key, host, verbose, app)
       @logger = Logger.new(log_sync: log_sync_instance)
 
-      @metrics = create_metrics(api_key, host, verbose)
+      @metrics = create_metrics(api_key, host, verbose, app)
+      @events = Events.new(api_key: api_key, host: host, verbose: verbose, app: app)
     end
 
-    def self.create(api_key: nil, host: 'https://api.logdash.io', verbose: false)
-      client = new(api_key: api_key, host: host, verbose: verbose)
-      { logger: client.logger, metrics: client.metrics }
+    def self.create(api_key: nil, host: 'https://api.logdash.io', verbose: false, app: nil)
+      client = new(api_key: api_key, host: host, verbose: verbose, app: app)
+      { logger: client.logger, metrics: client.metrics, events: client.events }
     end
 
     private
 
-    def create_log_sync(api_key, host, verbose)
+    def create_log_sync(api_key, host, verbose, app)
       if api_key && !api_key.empty?
-        HttpLogSync.new(api_key: api_key, host: host, verbose: verbose)
+        HttpLogSync.new(api_key: api_key, host: host, verbose: verbose, app: app)
       else
         puts '[LogDash] API key not provided. Using local logger only.' if verbose
         NoopLogSync.new
       end
     end
 
-    def create_metrics(api_key, host, verbose)
+    def create_metrics(api_key, host, verbose, app)
       if api_key && !api_key.empty?
-        Metrics.new(api_key: api_key, host: host, verbose: verbose)
+        Metrics.new(api_key: api_key, host: host, verbose: verbose, app: app)
       else
         puts '[LogDash] API key not provided. Metrics will not be registered.' if verbose
         NoopMetrics.new

data/lib/logdash/events.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'securerandom'
+require_relative 'logger'
+
+module Logdash
+  class Events
+    NAME = /\A[a-z][a-z0-9_]{0,63}\z/.freeze
+    WEBSITE_EVENTS = %w[pageview pageleave browser_error].freeze
+
+    # Ruby kills the threads still sending events when the main thread exits, so it waits for them first
+    SENDING = ThreadGroup.new
+    at_exit { SENDING.list.each(&:join) }
+
+    def initialize(api_key:, host:, verbose:, app: nil)
+      @api_key = api_key
+      @host = host
+      @verbose = verbose
+      @app = app
+      @console = Logger.new
+    end
+
+    # Ruby < 3 passes a braced props hash as keywords, so keywords other than user_id are props too
+    def track(name, props = {}, user_id: nil, **more_props)
+      name = name.to_s
+      user_id = user_id.to_s
+      validate(name, user_id)
+      props = props.to_h.merge(more_props)
+      return @console.info("Event #{name} #{props.to_json}") if @api_key.to_s.empty?
+
+      body = event_body(name, props, user_id)
+      SENDING.add(Thread.new { send_event(name, body) })
+    rescue StandardError => e
+      @console.warn("Dropping event #{name.inspect}: #{e.message}")
+    end
+
+    # Waits for the events still being sent, for example before a serverless function returns
+    def flush
+      SENDING.list.each(&:join)
+    end
+
+    private
+
+    def validate(name, user_id)
+      if !NAME.match?(name) || WEBSITE_EVENTS.include?(name)
+        raise ArgumentError, 'its name must match [a-z][a-z0-9_]{0,63} and not be pageview, pageleave or browser_error'
+      end
+      raise ArgumentError, 'user_id must be an internal ID, never an email address' if user_id.include?('@')
+    end
+
+    def event_body(name, props, user_id)
+      # The server stores an event once per id, so a retry must send this same body
+      body = { id: SecureRandom.uuid, name: name }
+      body[:props] = props unless props.empty?
+      body[:userId] = user_id unless user_id.empty?
+      body[:app] = @app if @app && !@app.empty?
+      body.to_json
+    end
+
+    def send_event(name, body)
+      uri = URI.parse("#{@host}/events")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+      http.open_timeout = 5
+      http.read_timeout = 5
+      response = http.post(uri.request_uri, body, 'Content-Type' => 'application/json', 'project-api-key' => @api_key)
+      puts "[LogDash BG] Sent event (#{name}), status: #{response.code}" if @verbose
+    rescue StandardError => e
+      puts "[LogDash BG] Error sending event (#{name}): #{e.message}" if @verbose
+    end
+  end
+end

data/lib/logdash/http_log_sync.rb

@@ -6,10 +6,11 @@ require 'json'
 
 module Logdash
   class HttpLogSync
-    def initialize(api_key:, host:, verbose:)
+    def initialize(api_key:, host:, verbose:, app: nil)
       @api_key = api_key
       @host = host
       @verbose = verbose
+      @app = app
       @sequence_number = 0
       @sequence_mutex = Mutex.new
     end
@@ -52,12 +53,9 @@ module Logdash
       request = Net::HTTP::Post.new(uri.request_uri)
       request['Content-Type'] = 'application/json'
       request['project-api-key'] = @api_key
-      request.body = {
-        message: message,
-        level: level,
-        createdAt: created_at,
-        sequenceNumber: sequence_number
-      }.to_json
+      body = { message: message, level: level, createdAt: created_at, sequenceNumber: sequence_number }
+      body[:app] = @app if @app && !@app.empty?
+      request.body = body.to_json
       request
     end
 

data/lib/logdash/logger.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'time'
 
 module Logdash
   module Types
@@ -59,19 +60,26 @@ module Logdash
       "\e[38;2;#{rgb[0]};#{rgb[1]};#{rgb[2]}m#{text}\e[0m"
     end
 
+    def iso8601_timestamp
+      Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%3NZ')
+    end
+
     def default_prefix_proc
-      lambda do |level|
-        timestamp = colorize("[#{Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')}]", Logdash::Types::LogLevel::SILLY)
+      lambda do |level, timestamp|
+        timestamp = colorize("[#{timestamp}]", Logdash::Types::LogLevel::SILLY)
         level_tag = colorize("[#{level.to_s.upcase}]", level)
         "#{timestamp} #{level_tag} "
       end
     end
 
     def _log(level, message)
-      prefix = @prefix_proc.call(level)
+      timestamp = iso8601_timestamp
+      prefix = @prefix_proc.call(level, timestamp)
+
       puts "#{prefix}#{message}"
+
       @on_log_proc&.call(level, message)
-      @log_sync&.send(message, level, Time.now.utc)
+      @log_sync&.send(message, level, timestamp)
     end
   end
 end

data/lib/logdash/metrics.rb

@@ -23,10 +23,11 @@ module Logdash
   class Metrics
     include BaseMetrics
 
-    def initialize(api_key:, host:, verbose:)
+    def initialize(api_key:, host:, verbose:, app: nil)
       @api_key = api_key
       @host = host
       @verbose = verbose
+      @app = app
     end
 
     def set(name, value)
@@ -51,16 +52,7 @@ module Logdash
         http.open_timeout = 5
         http.read_timeout = 5
 
-        request = Net::HTTP::Put.new(uri.request_uri)
-        request['Content-Type'] = 'application/json'
-        request['project-api-key'] = @api_key
-        request.body = {
-          name: name,
-          value: value,
-          operation: operation
-        }.to_json
-
-        response = http.request(request)
+        response = http.request(build_request(uri, name, value, operation))
         puts "[LogDash BG] Sent metric (#{name}, op: #{operation}), status: #{response.code}" if @verbose
       rescue Net::OpenTimeout, Net::ReadTimeout => e
         puts "[LogDash BG] Timeout sending metric (#{name}): #{e.message}" if @verbose
@@ -68,6 +60,16 @@ module Logdash
         puts "[LogDash BG] Error sending metric (#{name}): #{e.message}" if @verbose
       end
     end
+
+    def build_request(uri, name, value, operation)
+      request = Net::HTTP::Put.new(uri.request_uri)
+      request['Content-Type'] = 'application/json'
+      request['project-api-key'] = @api_key
+      body = { name: name, value: value, operation: operation }
+      body[:app] = @app if @app && !@app.empty?
+      request.body = body.to_json
+      request
+    end
   end
 
   class NoopMetrics

data/lib/logdash/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Logdash
-  VERSION = '1.0.1'
+  # CI writes the released version here before it builds the gem; the v<version> tags are the source of truth
+  VERSION = '1.1.0'
 end

data/lib/logdash.rb

@@ -5,11 +5,11 @@ require_relative 'logdash/version'
 require_relative 'logdash/logger'
 
 module Logdash
-  def self.create(api_key: nil, host: 'https://api.logdash.io', verbose: false)
-    Client.create(api_key: api_key, host: host, verbose: verbose)
+  def self.create(api_key: nil, host: 'https://api.logdash.io', verbose: false, app: nil)
+    Client.create(api_key: api_key, host: host, verbose: verbose, app: app)
   end
 
-  def self.new_client(api_key: nil, host: 'https://api.logdash.io', verbose: false)
-    Client.new(api_key: api_key, host: host, verbose: verbose)
+  def self.new_client(api_key: nil, host: 'https://api.logdash.io', verbose: false, app: nil)
+    Client.new(api_key: api_key, host: host, verbose: verbose, app: app)
   end
 end

metadata

@@ -1,43 +1,42 @@
 --- !ruby/object:Gem::Specification
 name: logdash
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - krzysztoff1
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -86,42 +85,56 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.25'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.25'
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
 - !ruby/object:Gem::Dependency
   name: timecop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.18'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.18'
 description: A Ruby client to send logs and metrics to the LogDash.
 email:
 - hello@krzysztof.studio
@@ -129,12 +142,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rubocop.yml"
-- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/logdash.rb
 - lib/logdash/client.rb
+- lib/logdash/events.rb
 - lib/logdash/http_log_sync.rb
 - lib/logdash/logger.rb
 - lib/logdash/metrics.rb
@@ -145,9 +157,8 @@ licenses:
 metadata:
   homepage_uri: https://logdash.io/
   source_code_uri: https://github.com/logdash-io/ruby-sdk
-  changelog_uri: https://github.com/logdash-io/ruby-sdk/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/logdash-io/ruby-sdk/releases
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -162,8 +173,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.20
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby client for LogDash observability platform.
 test_files: []

data/.rubocop.yml

@@ -1,58 +0,0 @@
-require:
-  - rubocop-rspec
-
-AllCops:
-  NewCops: enable
-  TargetRubyVersion: 2.6
-  Exclude:
-    - "bin/*"
-    - "vendor/**/*"
-    - "tmp/**/*"
-    - "logdash-*.gem"
-  SuggestExtensions: false
-
-Capybara:
-  Enabled: false
-
-FactoryBot:
-  Enabled: false
-
-Capybara/RSpec/PredicateMatcher:
-  Enabled: false
-
-Gemspec/DevelopmentDependencies:
-  Enabled: false
-
-Style/Documentation:
-  Enabled: false
-
-Style/FrozenStringLiteralComment:
-  Enabled: true
-
-Layout/LineLength:
-  Max: 120
-
-Metrics/BlockLength:
-  Exclude:
-    - "spec/**/*"
-    - "test/**/*"
-    - "ruby-sdk.gemspec"
-
-Metrics/ModuleLength:
-  Max: 150
-
-Metrics/ClassLength:
-  Max: 150
-
-Metrics/CyclomaticComplexity:
-  Max: 10
-
-Metrics/PerceivedComplexity:
-  Max: 10
-
-Metrics/AbcSize:
-  Max: 26
-
-Metrics/MethodLength:
-  Exclude:
-    - "lib/logdash/metrics.rb"

data/CHANGELOG.md

@@ -1,13 +0,0 @@
-# Changelog
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.0.1] - 2025-05-22
-
-### Added
-- Ensure iso8601 timestamp format is available in other environments
-
-## [1.0.0] - 2025-05-21
-
-### Added
-- Initial release