chargebee 2.74.0 → 2.77.0

data/lib/chargebee/telemetry_executor.rb

@@ -0,0 +1,95 @@
+require 'uri'
+
+module ChargeBee
+  class TelemetryExecutor
+    class << self
+      def execute(env, telemetry_resource:, telemetry_operation:, method:, http_url:, request_headers: {})
+        adapter = env.telemetry_adapter
+        if adapter.nil? || telemetry_resource.to_s.empty? || telemetry_operation.to_s.empty?
+          _status, result = yield(nil)
+          return result
+        end
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        headers = {}
+        handle = start_telemetry(
+          env, adapter, telemetry_resource, telemetry_operation, method, http_url, request_headers, headers
+        )
+
+        begin
+          telemetry_headers = headers.empty? ? nil : headers
+          status_code, result = yield(telemetry_headers)
+          end_telemetry_success(adapter, handle, start, status_code)
+          result
+        rescue => err
+          end_telemetry_failure(adapter, handle, start, err)
+          raise
+        end
+      end
+
+      def build_http_url(env, sub_domain, url)
+        path = url.start_with?('/') ? url : "/#{url}"
+        full = env.api_url(path, sub_domain)
+        uri = URI.parse(full)
+        "#{uri.scheme}://#{uri.host}#{uri.path}"
+      end
+
+      private
+
+      def start_telemetry(env, adapter, resource, operation, method, http_url, request_headers, headers)
+        uri = URI.parse(http_url)
+        host = uri.host || ''
+        api_path = "/api/#{Environment::API_VERSION}"
+        context = Telemetry::TelemetrySupport.build_request_telemetry_context(
+          resource,
+          operation,
+          method.to_s.upcase,
+          http_url,
+          host,
+          env.site,
+          Telemetry::TelemetrySupport.resolve_chargebee_api_version(api_path),
+          ChargeBee::VERSION,
+          request_headers,
+        )
+        safe_on_request_start(env, adapter, context, headers)
+      end
+
+      def end_telemetry_success(adapter, handle, start, http_status_code)
+        duration_ms = elapsed_ms(start)
+        result = Telemetry::TelemetrySupport.build_request_telemetry_result(http_status_code, duration_ms, nil)
+        safe_on_request_end(adapter, handle, result)
+      end
+
+      def end_telemetry_failure(adapter, handle, start, err)
+        status_code = Telemetry::TelemetrySupport.extract_http_status_code(err) || 500
+        duration_ms = elapsed_ms(start)
+        telemetry_error = Telemetry::TelemetrySupport.extract_request_telemetry_error(err)
+        result = Telemetry::TelemetrySupport.build_request_telemetry_result(status_code, duration_ms, telemetry_error)
+        safe_on_request_end(adapter, handle, result)
+      end
+
+      def safe_on_request_start(env, adapter, context, headers)
+        adapter.on_request_start(context, headers)
+      rescue => err
+        log_telemetry_error(env, 'on_request_start', err)
+        nil
+      end
+
+      def safe_on_request_end(adapter, handle, result)
+        adapter.on_request_end(handle, result)
+      rescue => err
+        warn "[ChargeBee] Telemetry adapter on_request_end failed: #{err}"
+      end
+
+      def log_telemetry_error(env, phase, err)
+        return unless env.enable_debug_logs
+
+        warn "[ChargeBee] Telemetry adapter #{phase} failed: #{err}. Continuing without telemetry."
+      end
+
+      def elapsed_ms(start)
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+      end
+    end
+  end
+end

data/lib/chargebee.rb

@@ -7,12 +7,22 @@ require File.dirname(__FILE__) + '/chargebee/list_result'
 
 require File.dirname(__FILE__) + '/chargebee/errors'
 
+require File.dirname(__FILE__) + '/chargebee/telemetry/telemetry_attribute_keys'
+require File.dirname(__FILE__) + '/chargebee/telemetry/request_telemetry_context'
+require File.dirname(__FILE__) + '/chargebee/telemetry/request_telemetry_error'
+require File.dirname(__FILE__) + '/chargebee/telemetry/request_telemetry_result'
+require File.dirname(__FILE__) + '/chargebee/telemetry/telemetry_adapter'
+require File.dirname(__FILE__) + '/chargebee/telemetry/telemetry_support'
+require File.dirname(__FILE__) + '/chargebee/telemetry_executor'
+
 require File.dirname(__FILE__) + '/chargebee/models/model'
 require File.dirname(__FILE__) + '/chargebee/models/addon'
 require File.dirname(__FILE__) + '/chargebee/models/address'
 require File.dirname(__FILE__) + '/chargebee/models/advance_invoice_schedule'
 require File.dirname(__FILE__) + '/chargebee/models/alert'
 require File.dirname(__FILE__) + '/chargebee/models/alert_status'
+require File.dirname(__FILE__) + '/chargebee/models/async_response'
+require File.dirname(__FILE__) + '/chargebee/models/async_response_list'
 require File.dirname(__FILE__) + '/chargebee/models/attached_item'
 require File.dirname(__FILE__) + '/chargebee/models/attribute'
 require File.dirname(__FILE__) + '/chargebee/models/billing_configuration'
@@ -20,6 +30,7 @@ require File.dirname(__FILE__) + '/chargebee/models/brand'
 require File.dirname(__FILE__) + '/chargebee/models/business_entity'
 require File.dirname(__FILE__) + '/chargebee/models/business_entity_transfer'
 require File.dirname(__FILE__) + '/chargebee/models/card'
+require File.dirname(__FILE__) + '/chargebee/models/column_definition'
 require File.dirname(__FILE__) + '/chargebee/models/comment'
 require File.dirname(__FILE__) + '/chargebee/models/configuration'
 require File.dirname(__FILE__) + '/chargebee/models/contact'
@@ -63,6 +74,8 @@ require File.dirname(__FILE__) + '/chargebee/models/item_price'
 require File.dirname(__FILE__) + '/chargebee/models/ledger_account_balance'
 require File.dirname(__FILE__) + '/chargebee/models/ledger_operation'
 require File.dirname(__FILE__) + '/chargebee/models/metadata'
+require File.dirname(__FILE__) + '/chargebee/models/meter'
+require File.dirname(__FILE__) + '/chargebee/models/metered_feature'
 require File.dirname(__FILE__) + '/chargebee/models/non_subscription'
 require File.dirname(__FILE__) + '/chargebee/models/offer_event'
 require File.dirname(__FILE__) + '/chargebee/models/offer_fulfillment'
@@ -121,7 +134,7 @@ require File.dirname(__FILE__) + '/chargebee/models/webhook_endpoint'
 
 module ChargeBee
 
-  VERSION = '2.74.0'
+  VERSION = '2.77.0'
 
   @@default_env = nil
   @@verify_ca_certs = true

data/spec/chargebee/request_telemetry_spec.rb

@@ -0,0 +1,75 @@
+require 'spec_helper'
+
+describe ChargeBee::Request do
+  class InjectTraceAdapter
+    include ChargeBee::Telemetry::TelemetryAdapter
+
+    def on_request_start(_context, request_headers)
+      request_headers['traceparent'] = '00-test-trace'
+      nil
+    end
+
+    def on_request_end(_handle, _result)
+    end
+  end
+
+  it 'does not mutate caller headers when telemetry injects trace headers' do
+    env = ChargeBee::Environment.new(
+      api_key: 'test_key',
+      site: 'acme',
+      telemetry_adapter: InjectTraceAdapter.new,
+    )
+    original_headers = { 'chargebee-foo' => 'bar' }
+    headers = original_headers.dup
+
+    ChargeBee::NativeRequest.expects(:request).with do |_method, _url, _env, _params, merged_headers, *_rest|
+      expect(merged_headers['traceparent']).to eq('00-test-trace')
+      expect(merged_headers['chargebee-foo']).to eq('bar')
+      true
+    end.returns([{}, {}, '200'])
+
+    ChargeBee::Request.send(
+      'get',
+      '/customers',
+      {},
+      env,
+      headers,
+      nil,
+      false,
+      {},
+      {},
+      telemetry_resource: 'customer',
+      telemetry_operation: 'list',
+    )
+
+    expect(headers).to eq(original_headers)
+    expect(headers).not_to have_key('traceparent')
+  end
+
+  it 'accepts nil headers when telemetry injects trace headers' do
+    env = ChargeBee::Environment.new(
+      api_key: 'test_key',
+      site: 'acme',
+      telemetry_adapter: InjectTraceAdapter.new,
+    )
+
+    ChargeBee::NativeRequest.expects(:request).with do |_method, _url, _env, _params, merged_headers, *_rest|
+      expect(merged_headers['traceparent']).to eq('00-test-trace')
+      true
+    end.returns([{}, {}, '200'])
+
+    ChargeBee::Request.send(
+      'get',
+      '/customers',
+      {},
+      env,
+      nil,
+      nil,
+      false,
+      {},
+      {},
+      'customer',
+      'list',
+    )
+  end
+end

data/spec/chargebee/telemetry_executor_spec.rb

@@ -0,0 +1,147 @@
+require 'spec_helper'
+
+module ChargeBee
+  class RecordingTelemetryAdapter
+    include Telemetry::TelemetryAdapter
+
+    attr_reader :events, :start_context, :end_result
+
+    def initialize
+      @events = []
+    end
+
+    def on_request_start(context, request_headers)
+      @events << 'start'
+      @start_context = context
+      request_headers['traceparent'] = '00-test-trace'
+      'span-1'
+    end
+
+    def on_request_end(handle, result)
+      @events << 'end'
+      @end_result = result
+    end
+  end
+end
+
+describe ChargeBee::TelemetryExecutor do
+  let(:env) do
+    ChargeBee::Environment.new(api_key: 'test_key', site: 'acme')
+  end
+
+  it 'skips telemetry when no adapter is configured' do
+    result = ChargeBee::TelemetryExecutor.execute(
+      env,
+      telemetry_resource: 'customer',
+      telemetry_operation: 'list',
+      method: 'get',
+      http_url: 'https://acme.chargebee.com/api/v2/customers',
+    ) do |headers|
+      expect(headers).to be_nil
+      [200, :ok]
+    end
+
+    expect(result).to eq(:ok)
+  end
+
+  it 'skips telemetry when resource or operation metadata is missing' do
+    adapter = ChargeBee::RecordingTelemetryAdapter.new
+    env.telemetry_adapter = adapter
+
+    result = ChargeBee::TelemetryExecutor.execute(
+      env,
+      telemetry_resource: '',
+      telemetry_operation: 'list',
+      method: 'get',
+      http_url: 'https://acme.chargebee.com/api/v2/customers',
+    ) do |_headers|
+      [200, :ok]
+    end
+
+    expect(result).to eq(:ok)
+    expect(adapter.events).to be_empty
+  end
+
+  it 'calls adapter once per request and injects trace headers' do
+    adapter = ChargeBee::RecordingTelemetryAdapter.new
+    env.telemetry_adapter = adapter
+
+    result = ChargeBee::TelemetryExecutor.execute(
+      env,
+      telemetry_resource: 'customer',
+      telemetry_operation: 'list',
+      method: 'get',
+      http_url: 'https://acme.chargebee.com/api/v2/customers',
+    ) do |headers|
+      expect(headers['traceparent']).to eq('00-test-trace')
+      [200, :ok]
+    end
+
+    expect(result).to eq(:ok)
+    expect(adapter.events).to eq(%w[start end])
+    expect(adapter.start_context.span_name).to eq('chargebee.customer.list')
+    expect(adapter.end_result.http_status_code).to eq(200)
+  end
+
+  it 'captures chargebee-* request headers and excludes the PII origin family' do
+    adapter = ChargeBee::RecordingTelemetryAdapter.new
+    env.telemetry_adapter = adapter
+    request_headers = {
+      'chargebee-foo' => 'bar',
+      'Chargebee-Idempotency-Key' => 'idem-key-1',
+      'Authorization' => 'Basic super-secret',
+      'chargebee-request-origin-ip' => '202.170.207.70',
+    }
+
+    ChargeBee::TelemetryExecutor.execute(
+      env,
+      telemetry_resource: 'customer',
+      telemetry_operation: 'list',
+      method: 'get',
+      http_url: 'https://acme.chargebee.com/api/v2/customers',
+      request_headers: request_headers,
+    ) do |_headers|
+      [200, :ok]
+    end
+
+    attrs = adapter.start_context.start_attributes
+    expect(attrs['http.request.header.chargebee-foo']).to eq('bar')
+    expect(attrs['http.request.header.chargebee-idempotency-key']).to eq('idem-key-1')
+    expect(attrs['http.request.header.authorization']).to be_nil
+    expect(attrs['http.request.header.chargebee-request-origin-ip']).to be_nil
+    expect(attrs.to_s).not_to include('202.170.207.70')
+  end
+
+  it 'records chargebee API errors on failure' do
+    adapter = ChargeBee::RecordingTelemetryAdapter.new
+    env.telemetry_adapter = adapter
+    api_error = ChargeBee::InvalidRequestError.new(
+      404,
+      {
+        message: 'Not found',
+        type: 'invalid_request',
+        api_error_code: 'resource_not_found',
+        param: 'customer_id',
+      },
+    )
+
+    expect do
+      ChargeBee::TelemetryExecutor.execute(
+        env,
+        telemetry_resource: 'customer',
+        telemetry_operation: 'retrieve',
+        method: 'get',
+        http_url: 'https://acme.chargebee.com/api/v2/customers/1',
+      ) do |_headers|
+        raise api_error
+      end
+    end.to raise_error(api_error)
+
+    expect(adapter.events).to eq(%w[start end])
+    expect(adapter.end_result.http_status_code).to eq(404)
+    expect(adapter.end_result.error.chargebee_error_code).to eq('resource_not_found')
+    expect(adapter.end_result.end_attributes['error.type']).to eq('invalid_request')
+    expect(adapter.end_result.end_attributes['chargebee.error.type']).to eq('invalid_request')
+    expect(adapter.end_result.end_attributes['error.type']).not_to eq('404')
+  end
+end

data/spec/chargebee/telemetry_support_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+describe ChargeBee::Telemetry::TelemetrySupport do
+  describe '.build_request_end_span_attributes' do
+    it 'uses chargebee error type for error.type' do
+      error = ChargeBee::Telemetry::RequestTelemetryError.new(
+        message: 'Not found',
+        chargebee_error_code: 'resource_not_found',
+        chargebee_api_error_type: 'invalid_request',
+      )
+
+      attributes = described_class.build_request_end_span_attributes(404, error)
+
+      expect(attributes[ChargeBee::Telemetry::TelemetryAttributeKeys::HTTP_RESPONSE_STATUS_CODE]).to eq(404)
+      expect(attributes[ChargeBee::Telemetry::TelemetryAttributeKeys::ERROR_TYPE]).to eq('invalid_request')
+      expect(attributes[ChargeBee::Telemetry::TelemetryAttributeKeys::CHARGEBEE_ERROR_TYPE]).to eq('invalid_request')
+    end
+
+    it 'omits error.type when chargebee error classification is unavailable' do
+      error = ChargeBee::Telemetry::RequestTelemetryError.new(message: 'request failed')
+
+      attributes = described_class.build_request_end_span_attributes(500, error)
+
+      expect(attributes[ChargeBee::Telemetry::TelemetryAttributeKeys::HTTP_RESPONSE_STATUS_CODE]).to eq(500)
+      expect(attributes).not_to have_key(ChargeBee::Telemetry::TelemetryAttributeKeys::ERROR_TYPE)
+      expect(attributes).not_to have_key(ChargeBee::Telemetry::TelemetryAttributeKeys::CHARGEBEE_ERROR_TYPE)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chargebee
 version: !ruby/object:Gem::Version
-  version: 2.74.0
+  version: 2.77.0
 platform: ruby
 authors:
 - Rajaraman S
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-18 00:00:00.000000000 Z
+date: 2026-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi
@@ -88,6 +88,8 @@ files:
 - lib/chargebee/models/advance_invoice_schedule.rb
 - lib/chargebee/models/alert.rb
 - lib/chargebee/models/alert_status.rb
+- lib/chargebee/models/async_response.rb
+- lib/chargebee/models/async_response_list.rb
 - lib/chargebee/models/attached_item.rb
 - lib/chargebee/models/attribute.rb
 - lib/chargebee/models/billing_configuration.rb
@@ -95,6 +97,7 @@ files:
 - lib/chargebee/models/business_entity.rb
 - lib/chargebee/models/business_entity_transfer.rb
 - lib/chargebee/models/card.rb
+- lib/chargebee/models/column_definition.rb
 - lib/chargebee/models/comment.rb
 - lib/chargebee/models/configuration.rb
 - lib/chargebee/models/contact.rb
@@ -139,6 +142,8 @@ files:
 - lib/chargebee/models/ledger_account_balance.rb
 - lib/chargebee/models/ledger_operation.rb
 - lib/chargebee/models/metadata.rb
+- lib/chargebee/models/meter.rb
+- lib/chargebee/models/metered_feature.rb
 - lib/chargebee/models/model.rb
 - lib/chargebee/models/non_subscription.rb
 - lib/chargebee/models/offer_event.rb
@@ -200,10 +205,20 @@ files:
 - lib/chargebee/request.rb
 - lib/chargebee/rest.rb
 - lib/chargebee/result.rb
+- lib/chargebee/telemetry/request_telemetry_context.rb
+- lib/chargebee/telemetry/request_telemetry_error.rb
+- lib/chargebee/telemetry/request_telemetry_result.rb
+- lib/chargebee/telemetry/telemetry_adapter.rb
+- lib/chargebee/telemetry/telemetry_attribute_keys.rb
+- lib/chargebee/telemetry/telemetry_support.rb
+- lib/chargebee/telemetry_executor.rb
 - lib/chargebee/util.rb
 - lib/ssl/ca-certs.crt
 - spec/chargebee/list_result_spec.rb
 - spec/chargebee/native_request_spec.rb
+- spec/chargebee/request_telemetry_spec.rb
+- spec/chargebee/telemetry_executor_spec.rb
+- spec/chargebee/telemetry_support_spec.rb
 - spec/chargebee_spec.rb
 - spec/errors_spec.rb
 - spec/sample_response.rb
@@ -236,6 +251,9 @@ summary: Ruby client for Chargebee API.
 test_files:
 - spec/chargebee/list_result_spec.rb
 - spec/chargebee/native_request_spec.rb
+- spec/chargebee/request_telemetry_spec.rb
+- spec/chargebee/telemetry_executor_spec.rb
+- spec/chargebee/telemetry_support_spec.rb
 - spec/chargebee_spec.rb
 - spec/errors_spec.rb
 - spec/sample_response.rb