trifle-stats 2.3.1 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfb651d581720b40adf3219aab3bf3323b89d3046e624ec0c66bb1b633f6dcca
-  data.tar.gz: f6a79c45b2bf41370cdbfec36d068d8fca48be14ce4c24e258480cbe41577d73
+  metadata.gz: 574331154d00b65ea5a994f7c7fbc754a1225c39617294acbeed3886c88d5b98
+  data.tar.gz: d4cca3dd912c0642594805395f727fcce350cee4cd6b388ddf09fb3032895317
 SHA512:
-  metadata.gz: 22f6f8b84aa2494f75a573ee47023ba8a6774c6fd65b3a022fb3df58360bf9e527388afc463603946f67e6c37083dd3205eeba950d6c18dadb661cddc8a965c6
-  data.tar.gz: dfd898c4beb30d76982c3476b5c3c533f0bf6279feaae86711ff59a7407d7e0ca99a661873f1fcd86a61dc9d59299dd5cd7cef9f3451a23fcda454386d5ec41e
+  metadata.gz: 423c591af0e2f61178be6553afef6ec4a52ab96268f30b82720e8bf591d079ece3b5b4753766f1ebeecffe442b92162ea89619a4aa7fa58298aee62b226f1cba
+  data.tar.gz: a1fdba88136d21091e95eb59b1b87fab7e917626e40860d5e7128f7771c0428547e2070ba98ae8a9cf5437ee5d61c7671745336226fc25c46492fd6aee1756f1

data/.github/workflows/ruby.yml

@@ -42,6 +42,19 @@ jobs:
         ports:
           - 6379:6379
 
+      mysql:
+        image: mysql:8
+        env:
+          MYSQL_ROOT_PASSWORD: password
+          MYSQL_DATABASE: trifle_stats_test
+        options: >-
+          --health-cmd "mysqladmin ping -h 127.0.0.1 -uroot -ppassword"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+        ports:
+          - 3306:3306
+
       mongodb:
         image: mongo:6.0
         env:
@@ -64,6 +77,11 @@ jobs:
       DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test_db
       REDIS_URL: redis://localhost:6379/0
       MONGODB_URL: mongodb://root:password@localhost:27017/test_db?authSource=admin
+      MYSQL_HOST: 127.0.0.1
+      MYSQL_PORT: 3306
+      MYSQL_USER: root
+      MYSQL_PASSWORD: password
+      MYSQL_DATABASE: trifle_stats_test
 
     steps:
       - uses: actions/checkout@v4
@@ -94,6 +112,12 @@ jobs:
             sleep 2
           done
 
+          # Wait for MySQL
+          until timeout 1 bash -c "</dev/tcp/localhost/3306"; do
+            echo "Waiting for MySQL..."
+            sleep 2
+          done
+
       - name: Setup Database
         run: |
           # Create database if needed (adjust based on your setup)
@@ -107,6 +131,11 @@ jobs:
           DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test_db
           REDIS_URL: redis://localhost:6379/0
           MONGODB_URL: mongodb://root:password@localhost:27017/test_db?authSource=admin
+          MYSQL_HOST: 127.0.0.1
+          MYSQL_PORT: 3306
+          MYSQL_USER: root
+          MYSQL_PASSWORD: password
+          MYSQL_DATABASE: trifle_stats_test
 
       - name: Rubocop
         run: bundle exec rubocop

data/Gemfile

@@ -6,6 +6,7 @@ gemspec
 gem "rake", "~> 12.0"
 gem "rspec", "~> 3.0"
 gem "mongo", require: false
+gem "mysql2", require: false
 gem "pg", require: false
 gem "redis", require: false
 gem "sqlite3", require: false

data/Gemfile.lock

@@ -1,13 +1,14 @@
 PATH
   remote: .
   specs:
-    trifle-stats (2.3.1)
+    trifle-stats (2.4.1)
       tzinfo (~> 2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    bigdecimal (4.0.1)
     bson (4.12.1)
     byebug (11.1.3)
     concurrent-ruby (1.3.6)
@@ -16,6 +17,8 @@ GEM
     mini_portile2 (2.8.9)
     mongo (2.14.0)
       bson (>= 4.8.2, < 5.0.0)
+    mysql2 (0.5.7)
+      bigdecimal
     parallel (1.20.1)
     parser (3.0.0.0)
       ast (~> 2.4.1)
@@ -66,6 +69,7 @@ DEPENDENCIES
   byebug
   dotenv
   mongo
+  mysql2
   pg
   rake (~> 12.0)
   redis

data/README.md

@@ -3,92 +3,83 @@
 [![Gem Version](https://badge.fury.io/rb/trifle-stats.svg)](https://rubygems.org/gems/trifle-stats)
 [![Ruby](https://github.com/trifle-io/trifle-stats/workflows/Ruby/badge.svg?branch=main)](https://github.com/trifle-io/trifle-stats)
 
-Simple analytics backed by Redis, Postgres, MongoDB, Google Analytics, Segment, or whatever. It gets you from having bunch of events occuring within few minutes to being able to say what happened on 25th January 2021.
+Time-series metrics for Ruby. Track anything (signups, revenue, job durations) using the database you already have. No InfluxDB. No TimescaleDB. Just one call and your existing Postgres, Redis, MongoDB, MySQL, or SQLite.
 
-## Documentation
+Part of the [Trifle](https://trifle.io) ecosystem. Also available in [Elixir](https://github.com/trifle-io/trifle_stats) and [Go](https://github.com/trifle-io/trifle_stats_go).
+
+## Why Trifle::Stats?
 
-For comprehensive guides, API reference, and examples, visit [trifle.io/trifle-stats-rb](https://trifle.io/trifle-stats-rb)
+- **No new infrastructure.** Uses your existing database. No dedicated time-series DB to deploy, maintain, or pay for.
+- **One call, many dimensions.** Track nested breakdowns (revenue by country by channel) in a single `track` call. Automatic rollup across dynamic time granularities (`1m`, `6h`, `1d`, etc.).
+- **Library-first.** Start with the gem. Add [Trifle App](https://trifle.io/product/app) dashboards, [Trifle CLI](https://github.com/trifle-io/trifle-cli) terminal access, or AI agent integration via MCP when you need them.
 
-## Installation
+## Quick Start
 
-Add this line to your application's Gemfile:
+### 1. Install
 
 ```ruby
 gem 'trifle-stats'
 ```
 
-And then execute:
-
-```bash
-$ bundle install
-```
-
-Or install it yourself as:
-
-```bash
-$ gem install trifle-stats
-```
-
-## Quick Start
-
-### 1. Configure
+### 2. Configure
 
 ```ruby
-require 'trifle/stats'
-
 Trifle::Stats.configure do |config|
-  config.driver = Trifle::Stats::Driver::Redis.new(Redis.new)
-  config.granularities = ['1m', '1h', '1d', '1w', '1mo', '1q', '1y']
+  config.driver = Trifle::Stats::Driver::Postgres.new(ActiveRecord::Base.connection)
+  config.granularities = ['1h', '1d', '1w', '1mo']
 end
 ```
 
-### 2. Track events
+### 3. Track
 
 ```ruby
-Trifle::Stats.track(key: 'event::logs', at: Time.now, values: { count: 1, duration: 2.11 })
+Trifle::Stats.track(
+  key: 'orders',
+  at: Time.now,
+  values: {
+    count: 1,
+    revenue: 49_90,
+    revenue_by_country: { us: 49_90 },
+    revenue_by_channel: { organic: 49_90 }
+  }
+)
 ```
 
-### 3. Retrieve values
+### 4. Query
 
 ```ruby
-Trifle::Stats.values(key: 'event::logs', from: 1.month.ago, to: Time.now, granularity: :day)
-#=> {:at=>[Wed, 25 Jan 2023 00:00:00 +0000], :values=>[{"count"=>1, "duration"=>2.11}]}
+Trifle::Stats.values(
+  key: 'orders',
+  from: 1.week.ago,
+  to: Time.now,
+  granularity: :day
+)
+#=> { at: [Mon, Tue, Wed, ...], values: [{ "count" => 12, "revenue" => 598_80, ... }, ...] }
 ```
 
 ## Drivers
 
-Trifle::Stats supports multiple backends:
-
-- **Redis** - Fast, in-memory storage
-- **Postgres** - SQL database with JSONB support
-- **SQLite** - SQL database in a file
-- **MongoDB** - Document database
-- **Process** - Thread-safe in-memory storage (development/testing)
-- **Dummy** - No-op driver for disabled analytics
+| Driver | Backend | Best for |
+|--------|---------|----------|
+| **Postgres** | JSONB upsert | Most production apps |
+| **Redis** | Hash increment | High-throughput counters |
+| **MongoDB** | Document upsert | Document-oriented stacks |
+| **MySQL** | JSON column | MySQL shops |
+| **SQLite** | JSON1 extension | Single-server apps, dev/test |
+| **Process** | In-memory | Testing |
+| **Dummy** | No-op | Disabled analytics |
 
 ## Features
 
-- **Multiple time granularities** - Track data across different time periods
-- **Custom aggregators** - Sum, average, min, max with custom logic
-- **Series operations** - Advanced data manipulation and calculations
-- **Performance optimized** - Efficient storage and retrieval patterns
-- **Buffered writes** - Queue metrics locally before flushing to the driver
-- **Driver flexibility** - Switch between storage backends easily
+- **Dynamic time granularities.** Use any interval like `1m`, `10m`, `1h`, `6h`, `1d`, `1w`, `1mo`, `1q`, `1y`.
+- **Nested value hierarchies.** Track dimensional breakdowns in a single call.
+- **Series operations.** Aggregators (sum, avg, min, max), transponders, formatters.
+- **Buffered writes.** Queue metrics in-memory before flushing to reduce write load.
+- **Driver flexibility.** Switch backends without changing application code.
 
 ## Buffered Persistence
 
-Every `track/assert/assort` call can be buffered before touching the driver. The buffer is enabled by
-default and flushes on an interval, when the queue reaches a configurable size, and again on shutdown
-(`SIGTERM`/`at_exit`).
-
-Available configuration options:
-
-- `buffer_enabled` (default: `true`) – Disable to write-through synchronously
-- `buffer_duration` (default: `1` second) – Maximum time between automatic flushes
-- `buffer_size` (default: `256`) – Maximum queued actions before forcing a flush
-- `buffer_aggregate` (default: `true`) – Combine repeated operations on the same key set
-
-Example:
+Every `track`/`assert`/`assort` call is buffered by default. The buffer flushes on an interval, when the queue reaches a configurable size, and on shutdown (`SIGTERM`/`at_exit`).
 
 ```ruby
 Trifle::Stats.configure do |config|
@@ -99,34 +90,25 @@ Trifle::Stats.configure do |config|
 end
 ```
 
-If your application manages database connections manually (e.g. ActiveRecord with a pool size of 1),
-increase the pool size or disable buffering to avoid starving other threads.
-
-## Testing
-
-Tests are run against all supported drivers. To run the test suite:
-
-```bash
-$ bundle exec rspec
-```
-
-Ensure Redis, Postgres, and MongoDB are running locally. The test suite will handle database setup automatically.
+Set `buffer_enabled = false` for synchronous write-through.
 
-Tests are meant to be **simple and isolated**. Every test should be **independent** and able to run in any order. Tests should be **self-contained** and set up their own configuration. This makes it easier to debug and maintain the test suite.
-
-Use **single layer testing** to focus on testing a specific class or module in isolation. Use **appropriate stubbing** for driver methods when testing higher-level operations.
+## Documentation
 
-Driver tests use real database connections for accurate behavior validation. The `Process` driver is preferred for in-memory testing environments.
+Full guides, API reference, and examples at **[docs.trifle.io/trifle-stats-rb](https://docs.trifle.io/trifle-stats-rb)**
 
-**Repeat yourself** in test setup for clarity rather than complex shared setups that can hide dependencies.
+## Trifle Ecosystem
 
-For performance testing:
+Trifle::Stats is the tracking layer. The ecosystem grows with you:
 
-```bash
-$ cd specs/performance
-$ bundle install
-$ ruby run.rb 100 '{"a":1}'
-```
+| Component | What it does |
+|-----------|-------------|
+| **[Trifle App](https://trifle.io/product/app)** | Dashboards, alerts, scheduled reports, AI-powered chat. Cloud or self-hosted. |
+| **[Trifle CLI](https://github.com/trifle-io/trifle-cli)** | Query and push metrics from the terminal. MCP server mode for AI agents. |
+| **[Trifle::Stats (Elixir)](https://github.com/trifle-io/trifle_stats)** | Elixir implementation with the same API and storage format. |
+| **[Trifle Stats (Go)](https://github.com/trifle-io/trifle_stats_go)** | Go implementation with the same API and storage format. |
+| **[Trifle::Traces](https://github.com/trifle-io/trifle-traces)** | Structured execution tracing for background jobs. |
+| **[Trifle::Logs](https://github.com/trifle-io/trifle-logs)** | File-based log storage with ripgrep-powered search. |
+| **[Trifle::Docs](https://github.com/trifle-io/trifle-docs)** | Map a folder of Markdown files to documentation URLs. |
 
 ## Contributing
 

data/lib/trifle/stats/driver/mysql.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require_relative '../mixins/packer'
+
+module Trifle
+  module Stats
+    module Driver
+      class Mysql # rubocop:disable Metrics/ClassLength
+        include Mixins::Packer
+        attr_accessor :client, :table_name, :ping_table_name
+
+        def initialize(client, table_name: 'trifle_stats', joined_identifier: :full, ping_table_name: nil, system_tracking: true) # rubocop:disable Layout/LineLength
+          @client = client
+          @table_name = table_name
+          @ping_table_name = ping_table_name || "#{table_name}_ping"
+          @joined_identifier = self.class.normalize_joined_identifier(joined_identifier)
+          @system_tracking = system_tracking
+          @separator = '::'
+        end
+
+        def self.setup!(client, table_name: 'trifle_stats', joined_identifier: :full, ping_table_name: nil) # rubocop:disable Metrics/MethodLength
+          ping_table_name ||= "#{table_name}_ping"
+          identifier_mode = normalize_joined_identifier(joined_identifier)
+          quoted_table_name = quote_identifier(table_name)
+          quoted_ping_table_name = quote_identifier(ping_table_name)
+
+          case identifier_mode
+          when :full
+            client.query(<<~SQL)
+              CREATE TABLE IF NOT EXISTS #{quoted_table_name}
+              (`key` VARCHAR(255) PRIMARY KEY, `data` JSON NOT NULL)
+            SQL
+          when :partial
+            client.query(<<~SQL)
+              CREATE TABLE IF NOT EXISTS #{quoted_table_name}
+              (`key` VARCHAR(255) NOT NULL, `at` DATETIME(6) NOT NULL, `data` JSON NOT NULL, PRIMARY KEY (`key`, `at`))
+            SQL
+          else
+            client.query(<<~SQL)
+              CREATE TABLE IF NOT EXISTS #{quoted_table_name}
+              (`key` VARCHAR(255) NOT NULL, `granularity` VARCHAR(255) NOT NULL, `at` DATETIME(6) NOT NULL, `data` JSON NOT NULL, PRIMARY KEY (`key`, `granularity`, `at`))
+            SQL
+            client.query(<<~SQL)
+              CREATE TABLE IF NOT EXISTS #{quoted_ping_table_name}
+              (`key` VARCHAR(255) PRIMARY KEY, `at` DATETIME(6) NOT NULL, `data` JSON NOT NULL)
+            SQL
+          end
+        end
+
+        def description
+          mode = if @joined_identifier == :full
+                   'J'
+                 else
+                   @joined_identifier == :partial ? 'P' : 'S'
+                 end
+          "#{self.class.name}(#{mode})"
+        end
+
+        attr_reader :separator
+
+        def system_identifier_for(key:)
+          key = Nocturnal::Key.new(key: '__system__key__', granularity: key.granularity, at: key.at)
+          identifier_for(key)
+        end
+
+        def system_data_for(key:, count: 1, tracking_key: nil)
+          tracking_key ||= key.key
+          self.class.pack(hash: { count: count, keys: { tracking_key => count } })
+        end
+
+        def inc(keys:, values:, count: 1, tracking_key: nil)
+          data = self.class.pack(hash: values)
+          with_transaction(client) do |connection|
+            keys.each do |key|
+              identifier = identifier_for(key)
+              query, args = inc_query(identifier: identifier, data: data)
+              execute_prepared(connection, query, args)
+              track_system_data(connection, key, count, tracking_key)
+            end
+          end
+        end
+
+        def set(keys:, values:, count: 1, tracking_key: nil)
+          data = self.class.pack(hash: values)
+          with_transaction(client) do |connection|
+            keys.each do |key|
+              identifier = identifier_for(key)
+              query, args = set_query(identifier: identifier, data: data)
+              execute_prepared(connection, query, args)
+              track_system_data(connection, key, count, tracking_key)
+            end
+          end
+        end
+
+        def get(keys:)
+          keys.map do |key|
+            identifier = identifier_for(key)
+            self.class.unpack(hash: fetch_packed_data(identifier))
+          end
+        end
+
+        def ping(key:, values:)
+          return [] if @joined_identifier
+
+          data = self.class.pack(hash: { data: values, at: key.at })
+          query, args = ping_query(key: key.key, at: key.at, data: data)
+
+          with_transaction(client) do |connection|
+            execute_prepared(connection, query, args)
+          end
+        end
+
+        # rubocop:disable Metrics/MethodLength
+        def scan(key:)
+          return [] if @joined_identifier
+
+          query = <<~SQL
+            SELECT `at`, CAST(`data` AS CHAR) AS data
+            FROM #{self.class.quote_identifier(ping_table_name)}
+            WHERE `key` = ?
+            ORDER BY `at` DESC
+            LIMIT 1
+          SQL
+          result = execute_prepared(client, query, [key.key]).first
+          return [] if result.nil?
+
+          [parse_time_value(result['at']), self.class.unpack(hash: JSON.parse(result['data']))]
+        rescue JSON::ParserError
+          []
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        def self.normalize_joined_identifier(value)
+          case value
+          when nil, :full, 'full', :partial, 'partial'
+            value.nil? ? nil : value.to_sym
+          else
+            raise ArgumentError, 'joined_identifier must be nil, :full, "full", :partial, or "partial"'
+          end
+        end
+
+        def self.quote_identifier(identifier)
+          "`#{identifier.to_s.gsub('`', '``')}`"
+        end
+
+        private
+
+        def track_system_data(connection, key, count, tracking_key)
+          return unless @system_tracking
+
+          query, args = inc_query(
+            identifier: system_identifier_for(key: key),
+            data: system_data_for(key: key, count: count, tracking_key: tracking_key)
+          )
+          execute_prepared(connection, query, args)
+        end
+
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        def fetch_packed_data(identifier)
+          conditions = identifier.keys.map { |column| "#{self.class.quote_identifier(column)} = ?" }.join(' AND ')
+          query = <<~SQL
+            SELECT CAST(`data` AS CHAR) AS data
+            FROM #{self.class.quote_identifier(table_name)}
+            WHERE #{conditions}
+            LIMIT 1
+          SQL
+          packed_data = execute_prepared(client, query, query_values(identifier)).first&.fetch('data', nil)
+          return {} if packed_data.nil? || packed_data.empty?
+
+          JSON.parse(packed_data)
+        rescue JSON::ParserError
+          {}
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+        def inc_query(identifier:, data:)
+          upsert_query(
+            identifier: identifier,
+            data: data,
+            conflict_data_sql: build_inc_json_set_expression(data),
+            conflict_values: increment_values(data)
+          )
+        end
+
+        def set_query(identifier:, data:)
+          upsert_query(
+            identifier: identifier,
+            data: data,
+            conflict_data_sql: build_set_json_set_expression(data),
+            conflict_values: serialized_set_values(data)
+          )
+        end
+
+        def upsert_query(identifier:, data:, conflict_data_sql:, conflict_values:)
+          columns = identifier.keys
+          columns_sql = columns.map { |column| self.class.quote_identifier(column) }.join(', ')
+          values_sql = (['?'] * columns.size + ['CAST(? AS JSON)']).join(', ')
+
+          query = <<~SQL
+            INSERT INTO #{self.class.quote_identifier(table_name)} (#{columns_sql}, `data`) VALUES (#{values_sql})
+            ON DUPLICATE KEY UPDATE `data` = #{conflict_data_sql}
+          SQL
+
+          [query, query_values(identifier) + [JSON.generate(data)] + conflict_values]
+        end
+
+        def ping_query(key:, at:, data:)
+          query = <<~SQL
+            INSERT INTO #{self.class.quote_identifier(ping_table_name)} (`key`, `at`, `data`) VALUES (?, ?, CAST(? AS JSON))
+            ON DUPLICATE KEY UPDATE `at` = VALUES(`at`), `data` = VALUES(`data`)
+          SQL
+          [query, [key.to_s, format_time_value(at), JSON.generate(data)]]
+        end
+
+        def build_inc_json_set_expression(data)
+          expression = +'JSON_SET(COALESCE(`data`, JSON_OBJECT())'
+          data.each_key do |path_key|
+            path = json_path_for(path_key)
+            expression << ", '#{path}', (COALESCE(CAST(JSON_UNQUOTE(JSON_EXTRACT(COALESCE(`data`, JSON_OBJECT()), '#{path}')) AS DECIMAL(65,10)), 0) + CAST(? AS DECIMAL(65,10)))" # rubocop:disable Layout/LineLength
+          end
+          expression << ')'
+          expression
+        end
+
+        def build_set_json_set_expression(data)
+          expression = +'JSON_SET(COALESCE(`data`, JSON_OBJECT())'
+          data.each_key do |path_key|
+            path = json_path_for(path_key)
+            expression << ", '#{path}', CAST(? AS JSON)"
+          end
+          expression << ')'
+          expression
+        end
+
+        def query_values(identifier)
+          identifier.values.map { |value| normalize_query_value(value) }
+        end
+
+        def increment_values(data)
+          data.map do |key, value|
+            next value if value.is_a?(Numeric)
+
+            raise ArgumentError, "increment requires numeric value for key #{key.inspect}"
+          end
+        end
+
+        def serialized_set_values(data)
+          data.values.map { |value| JSON.generate(value) }
+        end
+
+        def normalize_query_value(value)
+          return format_time_value(value) if value.is_a?(Time)
+
+          value
+        end
+
+        def format_time_value(value)
+          parse_time_value(value).utc.strftime('%Y-%m-%d %H:%M:%S.%6N')
+        end
+
+        def parse_time_value(value)
+          case value
+          when Time
+            value
+          when String
+            Time.parse(value)
+          when DateTime
+            value.to_time
+          else
+            raise ArgumentError, "unsupported time value: #{value.inspect}"
+          end
+        end
+
+        def json_path_for(key)
+          escaped = key.to_s.gsub('\\', '\\\\').gsub('"', '\"').gsub("'", "''")
+          "$.\"#{escaped}\""
+        end
+
+        def with_transaction(connection)
+          connection.query('START TRANSACTION')
+          result = yield(connection)
+          connection.query('COMMIT')
+          result
+        rescue StandardError
+          connection.query('ROLLBACK')
+          raise
+        end
+
+        def execute_prepared(connection, query, args = [])
+          statement = connection.prepare(query)
+          result = statement.execute(*args)
+          result.respond_to?(:to_a) ? result.to_a : result
+        ensure
+          statement&.close
+        end
+
+        def identifier_for(key)
+          key.identifier(separator, @joined_identifier)
+        end
+      end
+    end
+  end
+end

data/lib/trifle/stats/driver/sqlite.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'time'
 require_relative '../mixins/packer'
 
 module Trifle
@@ -126,7 +127,7 @@ module Trifle
           sample = identifiers.first
 
           results.each_with_object(Hash.new({})) do |r, o|
-            identifier = sample.each_with_index.to_h { |(k, _), i| [k, k == :at ? Time.parse(r[i]) : r[i]] }
+            identifier = sample.each_with_index.to_h { |(k, _), i| [k, k == :at ? Time.iso8601(r[i]) : r[i]] }
 
             o[identifier] = JSON.parse(r.last)
           rescue JSON::ParserError
@@ -136,7 +137,7 @@ module Trifle
 
         def get_query(identifiers:)
           conditions = identifiers.map do |identifier|
-            identifier.map { |k, v| "#{k} = #{format_value(v)}" }.join(' AND ')
+            identifier.map { |k, v| build_field_condition(k, v) }.join(' AND ')
           end.join(' OR ')
 
           <<-SQL
@@ -155,9 +156,11 @@ module Trifle
         end
 
         def ping_query(key:, at:, data:)
+          at_formatted = format_time_value(at)
+
           <<-SQL
-            INSERT INTO #{ping_table_name} (key, at, data) VALUES ('#{key}', '#{at.strftime('%Y-%m-%d %H:%M:%S')}', json('#{data.to_json}'))
-            ON CONFLICT (key) DO UPDATE SET at = '#{at.strftime('%Y-%m-%d %H:%M:%S')}', data = json('#{data.to_json}');
+            INSERT INTO #{ping_table_name} (key, at, data) VALUES ('#{key}', '#{at_formatted}', json('#{data.to_json}'))
+            ON CONFLICT (key) DO UPDATE SET at = '#{at_formatted}', data = json('#{data.to_json}');
           SQL
         end
 
@@ -168,7 +171,7 @@ module Trifle
           return [] if result.nil?
 
           # SQLite returns columns in order: key, at, data
-          [Time.parse(result[1]), self.class.unpack(hash: JSON.parse(result[2]))]
+          [Time.iso8601(result[1]), self.class.unpack(hash: JSON.parse(result[2]))]
         rescue JSON::ParserError
           []
         end
@@ -190,6 +193,15 @@ module Trifle
 
         private
 
+        def build_field_condition(key, value)
+          return "#{key} = #{format_value(value)}" unless key == :at
+
+          formatted = format_time_value(value)
+          with_microseconds = formatted.sub('Z', '.000000Z')
+
+          "(at = '#{formatted}' OR at = '#{with_microseconds}')"
+        end
+
         # Batch data operations to avoid SQLite parser stack overflow
         # Splits large data hashes into smaller chunks to prevent too many nested json_set calls
         def batch_data_operations(identifier:, data:, connection:, operation:)
@@ -203,15 +215,22 @@ module Trifle
         end
 
         def format_value(value)
+          return "'#{format_time_value(value)}'" if value.is_a?(Time) || value.is_a?(DateTime)
+          return value.to_s if value.is_a?(Integer) || value.is_a?(Float)
+
+          "'#{value}'"
+        end
+
+        def format_time_value(value)
           case value
-          when String
-            "'#{value}'"
           when Time
-            "'#{value.strftime('%Y-%m-%d %H:%M:%S')}'"
-          when Integer, Float
-            value.to_s
+            value.getutc.iso8601(0)
+          when DateTime
+            value.to_time.getutc.iso8601(0)
+          when Integer
+            Time.at(value).getutc.iso8601(0)
           else
-            "'#{value}'"
+            Time.iso8601(value.to_s).getutc.iso8601(0)
           end
         end
 
@@ -224,11 +243,9 @@ module Trifle
 
         def build_identifier_key(identifier)
           return identifier[:key] if @joined_identifier == :full
-          if @joined_identifier == :partial
-            return "#{identifier[:key]}::#{identifier[:at].strftime('%Y-%m-%d %H:%M:%S')}"
-          end
+          return "#{identifier[:key]}::#{format_time_value(identifier[:at])}" if @joined_identifier == :partial
 
-          "#{identifier[:key]}::#{identifier[:granularity]}::#{identifier[:at].strftime('%Y-%m-%d %H:%M:%S')}"
+          "#{identifier[:key]}::#{identifier[:granularity]}::#{format_time_value(identifier[:at])}"
         end
 
         def identifier_for(key)

data/lib/trifle/stats/operations/timeseries/increment.rb

@@ -21,7 +21,7 @@ module Trifle
 
           def key_for(granularity:)
             pgrn = Nocturnal::Parser.new(granularity)
-            at = Nocturnal.new(@at, config: config).floor(pgrn.offset, pgrn.unit)
+            at = Nocturnal.new(localized_time(@at), config: config).floor(pgrn.offset, pgrn.unit)
             Nocturnal::Key.new(key: key, granularity: granularity, at: at)
           end
 
@@ -41,6 +41,13 @@ module Trifle
           def tracking_key
             @untracked ? '__untracked__' : nil
           end
+
+          private
+
+          def localized_time(time)
+            base_time = time.is_a?(Time) ? time : time.to_time
+            config.tz.utc_to_local(base_time.getutc)
+          end
         end
       end
     end

data/lib/trifle/stats/operations/timeseries/set.rb

@@ -21,7 +21,7 @@ module Trifle
 
           def key_for(granularity:)
             pgrn = Nocturnal::Parser.new(granularity)
-            at = Nocturnal.new(@at, config: config).floor(pgrn.offset, pgrn.unit)
+            at = Nocturnal.new(localized_time(@at), config: config).floor(pgrn.offset, pgrn.unit)
             Nocturnal::Key.new(key: key, granularity: granularity, at: at)
           end
 
@@ -41,6 +41,13 @@ module Trifle
           def tracking_key
             @untracked ? '__untracked__' : nil
           end
+
+          private
+
+          def localized_time(time)
+            base_time = time.is_a?(Time) ? time : time.to_time
+            config.tz.utc_to_local(base_time.getutc)
+          end
         end
       end
     end

data/lib/trifle/stats/operations/timeseries/values.rb

@@ -23,7 +23,13 @@ module Trifle
           def timeline
             @timeline ||= begin
               pgrn = Nocturnal::Parser.new(granularity)
-              Nocturnal.timeline(from: @from, to: @to, offset: pgrn.offset, unit: pgrn.unit)
+              Nocturnal.timeline(
+                from: localized_time(@from),
+                to: localized_time(@to),
+                offset: pgrn.offset,
+                unit: pgrn.unit,
+                config: config
+              )
             end
           end
 
@@ -54,6 +60,13 @@ module Trifle
           def perform
             @skip_blanks ? clean_values : values
           end
+
+          private
+
+          def localized_time(time)
+            base_time = time.is_a?(Time) ? time : time.to_time
+            config.tz.utc_to_local(base_time.getutc)
+          end
         end
       end
     end

data/lib/trifle/stats/version.rb

@@ -2,6 +2,6 @@
 
 module Trifle
   module Stats
-    VERSION = '2.3.1'
+    VERSION = '2.4.1'
   end
 end

data/lib/trifle/stats.rb

@@ -14,6 +14,7 @@ require 'trifle/stats/designator/custom'
 require 'trifle/stats/designator/geometric'
 require 'trifle/stats/designator/linear'
 require 'trifle/stats/driver/mongo'
+require 'trifle/stats/driver/mysql'
 require 'trifle/stats/driver/postgres'
 require 'trifle/stats/driver/process'
 require 'trifle/stats/driver/redis'

data/trifle-stats.gemspec

@@ -6,19 +6,18 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Jozef Vaclavik']
   spec.email         = ['jozef@hey.com']
 
-  spec.summary       = 'Simple analytics backed by Redis, Postgres, MongoDB, '\
-                       'Google Analytics, Segment, or whatever.'
-  spec.description   = 'Trifle::Stats is a way too simple timeline analytics '\
-                       'that helps you track custom metrics. Automatically '\
-                       'increments counters for each enabled range. '\
-                       'It supports timezones and different week beginning.'
+  spec.summary       = 'Time-series metrics for Ruby backed by Postgres, Redis, MongoDB, MySQL, or SQLite.'
+  spec.description   = 'Track custom business metrics using your existing database. '\
+                       'One call to record nested, multi-dimensional counters with '\
+                       'automatic rollup across configurable time granularities.'
   spec.homepage      = 'https://trifle.io'
   spec.licenses      = ['MIT']
   spec.required_ruby_version = Gem::Requirement.new('>= 2.6')
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/trifle-io/trifle-stats'
-  spec.metadata['changelog_uri'] = 'https://trifle.io/trifle-stats/changelog'
+  spec.metadata['changelog_uri'] = 'https://docs.trifle.io/trifle-stats-rb/changelog'
+  spec.metadata['documentation_uri'] = 'https://docs.trifle.io/trifle-stats-rb'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -33,6 +32,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency('byebug', '>= 0')
   spec.add_development_dependency('dotenv')
   spec.add_development_dependency('mongo', '>= 2.14.0')
+  spec.add_development_dependency('mysql2', '>= 0.5.5')
   spec.add_development_dependency('sqlite3', '>= 1.4.4')
   spec.add_development_dependency('pg', '>= 1.2')
   spec.add_development_dependency('rake', '~> 13.0')

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trifle-stats
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.4.1
 platform: ruby
 authors:
 - Jozef Vaclavik
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-05 00:00:00.000000000 Z
+date: 2026-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.14.0
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.5
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -164,9 +178,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: Trifle::Stats is a way too simple timeline analytics that helps you track
-  custom metrics. Automatically increments counters for each enabled range. It supports
-  timezones and different week beginning.
+description: Track custom business metrics using your existing database. One call
+  to record nested, multi-dimensional counters with automatic rollup across configurable
+  time granularities.
 email:
 - jozef@hey.com
 executables: []
@@ -212,6 +226,7 @@ files:
 - lib/trifle/stats/designator/linear.rb
 - lib/trifle/stats/driver/README.md
 - lib/trifle/stats/driver/mongo.rb
+- lib/trifle/stats/driver/mysql.rb
 - lib/trifle/stats/driver/postgres.rb
 - lib/trifle/stats/driver/process.rb
 - lib/trifle/stats/driver/redis.rb
@@ -248,7 +263,8 @@ licenses:
 metadata:
   homepage_uri: https://trifle.io
   source_code_uri: https://github.com/trifle-io/trifle-stats
-  changelog_uri: https://trifle.io/trifle-stats/changelog
+  changelog_uri: https://docs.trifle.io/trifle-stats-rb/changelog
+  documentation_uri: https://docs.trifle.io/trifle-stats-rb
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -267,6 +283,6 @@ requirements: []
 rubygems_version: 3.3.3
 signing_key:
 specification_version: 4
-summary: Simple analytics backed by Redis, Postgres, MongoDB, Google Analytics, Segment,
-  or whatever.
+summary: Time-series metrics for Ruby backed by Postgres, Redis, MongoDB, MySQL, or
+  SQLite.
 test_files: []