barkibu-kb 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5eb3a704f422c511e2e30d584cd6a80a7d91a090cfa5452dd197e65496b52eee
-  data.tar.gz: 05d766aeca3b869601193bd1a6310ced1c07f96d6f24cd5424c290a33b1edaf9
+  metadata.gz: 9b46793e55bdd7e53d2e98e3e792972ec67a86048074aeec1bc9ffdde8028965
+  data.tar.gz: 44d5748d6fb445709add87f4bea42c9c19516ff9bb81be8b4112b716c17469c9
 SHA512:
-  metadata.gz: 994f4d86e1c2d1aa40a173ed0b77a2fcff39cbfe1e0390c728f92887be3817e3851610f85796c24a61919c05789a718c3939ee965866a1fda2f72ed2e68492b1
-  data.tar.gz: c9de80ede2701f7e58bde7f803b473980383d6ec9ac3d8509f2fe0e74ff15a200e48025ecc2535bc7102b82f1199228806d1e1999de32745ae07123123cb7edd
+  metadata.gz: 38cb22fa193c859a72448aea1cecfbad17671a4deae2dbd5763881c05f3ffa7338ab80b6218de5e041463c1e0575d190bba204fcf6851a6655107b1894eb1ca6
+  data.tar.gz: f66b4353ac4cc0e3432310ecf7d54b212dfe8b1b245ca6f9f95062b49185acc5028ac1b5ab69503f9099de9cfc89f2ff39e3c62df12531e8c4f593a3bef2e034

data/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+jobs:
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      - run: bundle exec rubocop lib spec
+
+  rspec:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      - run: bundle exec rspec

data/CHANGELOG.md

@@ -6,7 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [unreleased]
-- See diff: https://github.com/barkibu/kb-ruby/compare/v1.0.0...HEAD
+- See diff: https://github.com/barkibu/kb-ruby/compare/v1.2.0...HEAD
+
+## [1.2.0]
+- `KB::Client` emits one `request.kb_client` `ActiveSupport::Notifications` event per KB call (`KB::Client::REQUEST_EVENT`), wrapping cache lookup, connect, TLS, write, read and parsing. Payload: `verb`, `path`, `base_url`, `cache_hit` (GET only), `status`, plus ActiveSupport's `exception`/`exception_object` when the call raised. Every public method now goes through one private `perform` seam; no behaviour change (same cache keys, params and error classes).
+- Add an opt-in Datadog subscriber: `require 'kb/instrumentation/datadog'` + `KB::Instrumentation::Datadog.subscribe!` turns each event into a `kb.client.request` APM span, opened on event start and closed on finish so the tracer's Net::HTTP spans nest under it. The span inherits the app's service and stays there (no `span.kind:client`/`peer.service`, so it is not attributed to the knowledge-base service), tags `peer.hostname`, `kb.method`, `kb.cache_hit`, `http.status_code`, and uses low-cardinality resources (`GET /v1/pets/?/contracts`). Motivation: connect timeouts happen before `Net::HTTP#request`, so the Datadog Net::HTTP tracer never sees them and they were invisible on our dashboards. Works with `ddtrace` 1.x and `datadog` 2.x; the tracer stays the app's dependency.
+
+## [1.1.0]
+- Add `read_timeout:` to `KB::Client#request` to raise the read budget for a single call (e.g. `GET /v1/pets/birthdays`, whose server-side work runs for seconds). Connect and write budgets stay global; the override does not leak into later calls on the same connection.
 
 ## [1.0.0]
 - [Breaking changes] Split the single global request timeout into per-phase budgets: `KB.config.request.connect_timeout` (default 1s, bounds TCP connect + TLS handshake), `write_timeout` (default 3s), `read_timeout` (default 5s). `KB.config.request.timeout` is removed — assigning it now raises `NoMethodError` at boot. Migration: a previous global `timeout` maps to `read_timeout` (e.g. `KB_REQUEST_TIMEOUT_SECONDS=12` → `read_timeout = 12`).

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    barkibu-kb (1.0.0)
+    barkibu-kb (1.2.0)
       activemodel (>= 4.0.2)
       activerecord
       activesupport (>= 3.0.0)
@@ -10,8 +10,8 @@ PATH
       faraday-net_http (~> 1.0)
       faraday_middleware
       i18n
-    barkibu-kb-fake (1.0.0)
-      barkibu-kb (= 1.0.0)
+    barkibu-kb-fake (1.2.0)
+      barkibu-kb (= 1.2.0)
       countries
       sinatra
       webmock
@@ -44,12 +44,21 @@ GEM
     base64 (0.3.0)
     bigdecimal (4.1.2)
     byebug (11.1.3)
+    cgi (0.5.2)
     concurrent-ruby (1.3.7)
     connection_pool (3.0.2)
     countries (5.3.1)
       unaccent (~> 0.3)
     crack (0.4.5)
       rexml
+    datadog (2.43.0)
+      cgi
+      datadog-ruby_core_source (~> 3.5, >= 3.5.5)
+      libdatadog (~> 40.0.0.2.0)
+      libddwaf (~> 1.30.0.0.0)
+      logger
+      msgpack
+    datadog-ruby_core_source (3.5.5)
     diff-lcs (1.4.4)
     docile (1.4.0)
     drb (2.2.3)
@@ -84,14 +93,19 @@ GEM
     faraday-retry (1.0.3)
     faraday_middleware (1.2.0)
       faraday (~> 1.0)
+    ffi (1.17.4)
     hashdiff (1.0.1)
     i18n (1.15.2)
       concurrent-ruby (~> 1.0)
     json (2.20.0)
+    libdatadog (40.0.0.2.0)
+    libddwaf (1.30.0.0.2)
+      ffi (~> 1.0)
     logger (1.7.0)
     minitest (6.0.6)
       drb (~> 2.0)
       prism (~> 1.5)
+    msgpack (1.8.5)
     multipart-post (2.3.0)
     mustermann (3.0.0)
       ruby2_keywords (~> 0.0.1)
@@ -173,6 +187,7 @@ DEPENDENCIES
   bigdecimal
   bundler
   byebug
+  datadog (~> 2.0)
   rake (>= 12.3.3)
   rspec (~> 3.0)
   rubocop

data/README.md

@@ -18,6 +18,15 @@ Or install it yourself as:
 
     $ gem install kb
 
+## Development
+
+Specs and RuboCop run on every pull request (`.github/workflows/ci.yml`) on Ruby 3.4. Locally:
+
+```sh
+docker compose run --rm kb bundle exec rspec
+docker compose run --rm kb bundle exec rubocop lib spec
+```
+
 ## Usage
 
 This gem wraps the Knowledge Base Api and exposes CRUD-_able_ entities into the requiring application.
@@ -57,6 +66,57 @@ KB.config.request.write_timeout = 4   # 3 by default
 KB.config.request.read_timeout = 10   # 5 by default
 ```
 
+The read budget can be raised for a single call through `KB::Client#request`, for
+the few endpoints whose server-side work legitimately runs for seconds. Connect
+and write budgets stay global:
+
+```ruby
+KB::Pet.kb_client.request('birthdays', filters: { month: 9, day: 22, size: 1000 }, read_timeout: 30)
+```
+
+#### Instrumentation
+
+Every KB call emits one `request.kb_client` event through
+`ActiveSupport::Notifications`, wrapping the whole call: cache lookup, TCP
+connect, TLS, write, read and JSON parsing. The payload carries `verb`, `path`,
+`base_url`, `cache_hit` (GET calls only), `status` (when a response arrived) and
+ActiveSupport's `exception` / `exception_object` when the call raised. Subscribe
+to it for logging, metrics or anything else:
+
+```ruby
+ActiveSupport::Notifications.subscribe(KB::Client::REQUEST_EVENT) do |event|
+  Rails.logger.info("KB #{event.payload[:verb]} #{event.payload[:path]} #{event.duration.round}ms")
+end
+```
+
+##### Datadog
+
+A ready-made subscriber turns each event into a `kb.client.request` APM span.
+Opt in from the app's Datadog initializer, after `Datadog.configure`. Works with
+both `ddtrace` 1.x and `datadog` 2.x; the tracer gem is the app's dependency.
+
+```ruby
+# config/initializers/datadog_tracer.rb
+Datadog.configure { |c| ... }
+
+require 'kb/instrumentation/datadog'
+KB::Instrumentation::Datadog.subscribe!
+```
+
+The span opens when the event starts and closes when it finishes, so the
+tracer's own Net::HTTP spans nest under it. It inherits the app's service
+(`c.service`), so nothing new appears in the APM service list, and it carries no
+`span.kind:client` or `peer.service`, so Datadog does not attribute it to the
+knowledge-base service either: it measures the client's whole call, not a KB
+operation. Resources are low-cardinality (`GET /v1/pets/birthdays`,
+`GET /v1/pets/?/contracts`). Tags: `peer.hostname` (the KB host used),
+`kb.method`, `kb.cache_hit` (GET calls only), `http.status_code`, plus the
+standard `error.type`/`error.message` when the call raises.
+
+Why not rely on the Net::HTTP tracer alone: faraday-net_http opens the socket
+before `Net::HTTP#request`, the method that tracer patches, so a connect timeout
+produces no http span at all. This span sees every phase.
+
 ### Exposed Entities
 
 #### Pet Parent 🧍🏾

data/barkibu-kb.gemspec

@@ -39,6 +39,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'dry-configurable', '~> 0.9'
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'byebug'
+  spec.add_development_dependency 'datadog', '~> 2.0'
   spec.add_development_dependency 'rake', '>= 12.3.3'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop'

data/lib/kb/client.rb

@@ -1,5 +1,10 @@
 module KB
   class Client
+    # Emitted once per KB call, wrapping cache lookup and the HTTP request.
+    # Payload: verb, path, base_url, cache_hit (GET only), status (when a response arrived),
+    # plus ActiveSupport's exception/exception_object when the call raised.
+    REQUEST_EVENT = 'request.kb_client'.freeze
+
     attr_reader :api_key, :base_url
 
     def initialize(base_url, api_key: ENV['KB_API_KEY'])
@@ -7,47 +12,42 @@ module KB
       @base_url = base_url
     end
 
-    def request(sub_path, filters: nil, method: :get)
-      return connection.public_send(method, sub_path, attributes_to_json(filters)).body if method != :get
+    # `read_timeout` overrides KB.config.request.read_timeout for this one call only,
+    # for the few endpoints whose server-side work legitimately runs for seconds
+    # (e.g. GET /v1/pets/birthdays). Connect and write budgets stay global.
+    def request(sub_path, filters: nil, method: :get, read_timeout: nil)
+      return perform(method, sub_path, attributes_to_json(filters), read_timeout: read_timeout) if method != :get
 
       cache_key = "#{@base_url}/#{sub_path}/#{(filters || {}).sort.to_h}"
-      KB::Cache.fetch(cache_key) do
-        connection.public_send(method, sub_path, filters).body
-      end
+      perform(:get, sub_path, filters, cache_key: cache_key, read_timeout: read_timeout)
     end
 
     def all(filters = {})
-      cache_key = "#{@base_url}/#{filters.sort.to_h}"
-
-      KB::Cache.fetch(cache_key) do
-        connection.get('', attributes_case_transform(filters)).body
-      end
+      perform(:get, '', attributes_case_transform(filters), cache_key: "#{@base_url}/#{filters.sort.to_h}")
     end
 
     def find(key, params = {})
       raise Faraday::ResourceNotFound, {} if key.blank?
 
-      KB::Cache.fetch("#{@base_url}/#{key}") do
-        connection.get(key, attributes_case_transform(params)).body
-      end
+      perform(:get, key, attributes_case_transform(params), cache_key: "#{@base_url}/#{key}")
     end
 
     def create(attributes)
-      connection.post('', attributes_to_json(attributes)).body
+      perform(:post, '', attributes_to_json(attributes))
     end
 
     def update(key, attributes)
       clear_cache_for(key)
-      connection.patch(key.to_s, attributes_to_json(attributes)).body
+      perform(:patch, key.to_s, attributes_to_json(attributes))
     end
 
     def destroy(key)
       clear_cache_for(key)
-      connection.delete(key.to_s).body
+      perform(:delete, key.to_s)
     end
 
     def upsert(attributes)
-      connection.put('', attributes_to_json(attributes)).body
+      perform(:put, '', attributes_to_json(attributes))
     end
 
     def clear_cache_for(key)
@@ -56,6 +56,32 @@ module KB
 
     private
 
+    # Every public method ends up here, so this is the one place a KB call is
+    # observable as a whole: cache lookup, connect, TLS, write, read, parse.
+    def perform(verb, path, payload = nil, cache_key: nil, read_timeout: nil)
+      event = { verb: verb, path: path, base_url: base_url }
+      ActiveSupport::Notifications.instrument(REQUEST_EVENT, event) do
+        if cache_key
+          event[:cache_hit] = true
+          KB::Cache.fetch(cache_key) do
+            event[:cache_hit] = false
+            http(event, payload, read_timeout)
+          end
+        else
+          http(event, payload, read_timeout)
+        end
+      end
+    end
+
+    def http(event, payload, read_timeout)
+      response = connection.public_send(event[:verb], event[:path], payload, &request_options(read_timeout))
+      event[:status] = response.status
+      response.body
+    rescue Faraday::ClientError, Faraday::ServerError => e
+      event[:status] = e.response && e.response[:status]
+      raise
+    end
+
     def headers
       {
         'Content-Type': 'application/json',
@@ -86,6 +112,12 @@ module KB
       end
     end
 
+    def request_options(read_timeout)
+      return nil if read_timeout.nil?
+
+      ->(req) { req.options.read_timeout = read_timeout }
+    end
+
     def request_timeouts
       {
         open_timeout: KB.config.request.connect_timeout,

data/lib/kb/instrumentation/datadog.rb

@@ -0,0 +1,81 @@
+require 'uri'
+require 'active_support/notifications'
+
+module KB
+  module Instrumentation
+    # Opt-in Datadog APM tracing for every KB call, as a subscriber to the
+    # client's `request.kb_client` notification.
+    #
+    #   # config/initializers/datadog_tracer.rb, after Datadog.configure
+    #   require 'kb/instrumentation/datadog'
+    #   KB::Instrumentation::Datadog.subscribe!
+    #
+    # One `kb.client.request` span per call, opened when the event starts and
+    # closed when it finishes, so it wraps cache lookup, TCP connect, TLS,
+    # write, read and JSON parsing, and the tracer's own Net::HTTP spans nest
+    # under it. No service is given, so the span inherits the app's, and it stays
+    # there: the KB host is a plain `peer.hostname` tag, with no `span.kind:client`
+    # or `peer.service` that would attribute it to KB. Works with
+    # `ddtrace` 1.x and `datadog` 2.x; the tracer gem is the app's dependency.
+    module Datadog
+      OPERATION = 'kb.client.request'.freeze
+      # Path segments that are identifiers, collapsed to `?` so resources stay
+      # low-cardinality: `GET /v1/pets/?/contracts` rather than one per pet.
+      IDENTIFIER_SEGMENT = /\A(?:\h{8}-\h{4}-\h{4}-\h{4}-\h{12}|\d+)\z/.freeze
+      SPAN_KEY = :datadog_span
+
+      class TracerMissing < StandardError; end
+
+      class << self
+        def subscribe!
+          unless defined?(::Datadog::Tracing)
+            raise TracerMissing, "Datadog tracing is not loaded; require 'ddtrace' or 'datadog' first"
+          end
+
+          return @subscriber if @subscriber
+
+          @subscriber = ActiveSupport::Notifications.subscribe(KB::Client::REQUEST_EVENT, Subscriber.new)
+        end
+
+        def unsubscribe!
+          ActiveSupport::Notifications.unsubscribe(@subscriber) if @subscriber
+          @subscriber = nil
+        end
+
+        def subscribed?
+          !@subscriber.nil?
+        end
+
+        def resource_for(base_url, verb, path)
+          segments = (URI(base_url).path.split('/') + path.to_s.split('/')).reject(&:empty?)
+          template = segments.map { |segment| segment.match?(IDENTIFIER_SEGMENT) ? '?' : segment }
+          "#{verb.to_s.upcase} /#{template.join('/')}"
+        end
+      end
+
+      class Subscriber
+        def start(_name, _id, payload)
+          span = ::Datadog::Tracing.trace(OPERATION, type: 'http',
+                                                     resource: Datadog.resource_for(payload[:base_url], payload[:verb],
+                                                                                    payload[:path]))
+          # No span.kind:client / peer.service on purpose: the span covers the
+          # client's whole call (cache lookup, connect, parse), so it must not be
+          # inferred onto the knowledge-base service page as one of KB's operations.
+          span.set_tag('peer.hostname', URI(payload[:base_url]).host)
+          span.set_tag('kb.method', payload[:verb].to_s.upcase)
+          payload[SPAN_KEY] = span
+        end
+
+        def finish(_name, _id, payload)
+          span = payload.delete(SPAN_KEY)
+          return unless span
+
+          span.set_tag('kb.cache_hit', payload[:cache_hit].to_s) if payload.key?(:cache_hit)
+          span.set_tag('http.status_code', payload[:status].to_s) if payload[:status]
+          span.set_error(payload[:exception_object]) if payload[:exception_object]
+          span.finish
+        end
+      end
+    end
+  end
+end

data/lib/kb/version.rb

@@ -1,3 +1,3 @@
 module KB
-  VERSION = '1.0.0'.freeze
+  VERSION = '1.2.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: barkibu-kb
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Léo Figea
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: datadog
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -271,6 +285,7 @@ extra_rdoc_files: []
 files:
 - ".env.example"
 - ".github/pull_request_template.md"
+- ".github/workflows/ci.yml"
 - ".github/workflows/release.yaml"
 - ".gitignore"
 - ".rspec"
@@ -312,6 +327,7 @@ files:
 - lib/kb/fake/bounded_context/pet_family/products.rb
 - lib/kb/fake/bounded_context/rest_resource.rb
 - lib/kb/inflections.rb
+- lib/kb/instrumentation/datadog.rb
 - lib/kb/models.rb
 - lib/kb/models/assessment.rb
 - lib/kb/models/base_model.rb