pingops 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f2dd00a33589bfeaca93f9755d53075f18e54c02796e1af084584d4400291445
+  data.tar.gz: 54f27e3fc4a35cc93b017f1e226a7a57fe82f61fad8bb79f19f739efd2daca04
+SHA512:
+  metadata.gz: 198fc7dfec12b0edbee02e08d21657321198783328b2ea96fc90d9818bc4506969117e9944b72f90f01c3c17d8f91152326fe516de5ef7e4ecce5e9eb8f3bf97
+  data.tar.gz: ae880a1d85dbb023f70a21bccd140b17377042ea67d4370b751ed975420c2f6634e697d6eef8da579e174d3af1acbb18d9c00a12ef879f1b3906d110ecad3af5

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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).
+
+## [0.0.1] - 2026-02-01
+
+### Added
+
+- Initial release of the PingOps Ruby SDK
+- Automatic HTTP instrumentation for Net::HTTP
+- Manual tracing with `Pingops.start_trace`
+- Configuration via hash, file (JSON/YAML), or environment variables
+- Domain allow/deny list filtering with path matching
+- Header filtering and redaction with multiple strategies
+- Request/response body capture with size limits
+- Batched and immediate export modes
+- OpenTelemetry SDK integration
+- Deterministic trace ID generation from seed
+- Custom trace attributes (userId, sessionId, tags, metadata)
+- Per-trace body capture override
+- Rails integration support
+- Auto-initialization via register pattern
+- Comprehensive test suite

data/README.md

@@ -0,0 +1,377 @@
+# PingOps Ruby SDK
+
+A production-grade Ruby SDK for PingOps that provides automatic HTTP tracing with OpenTelemetry integration.
+
+## Features
+
+- **Automatic HTTP Instrumentation** - Captures outgoing HTTP requests from `Net::HTTP`, Faraday, and HTTPClient
+- **OpenTelemetry Compatible** - Built on OpenTelemetry API and SDK for seamless integration
+- **Manual Tracing** - Start traces with custom attributes (userId, sessionId, tags, metadata)
+- **Domain Filtering** - Allow/deny lists with path matching
+- **Header Redaction** - Automatic redaction of sensitive headers
+- **Body Capture** - Configurable request/response body capture with size limits
+- **Flexible Configuration** - File-based (JSON/YAML) or programmatic configuration with environment variable support
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pingops'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install pingops
+```
+
+## Quick Start
+
+```ruby
+require 'pingops'
+
+# Initialize the SDK
+Pingops.initialize(
+  api_key: 'your-api-key',
+  base_url: 'https://api.pingops.com',
+  service_name: 'my-service'
+)
+
+# Trace HTTP requests
+Pingops.start_trace(attributes: { user_id: 'user-123' }) do
+  # All HTTP requests in this block are automatically traced
+  response = Net::HTTP.get(URI('https://api.example.com/users'))
+end
+
+# Shutdown when done
+Pingops.shutdown
+```
+
+## Configuration
+
+### Programmatic Configuration
+
+```ruby
+Pingops.initialize(
+  api_key: 'your-api-key',
+  base_url: 'https://api.pingops.com',
+  service_name: 'my-service',
+  debug: false,
+
+  # Body capture settings
+  capture_request_body: true,
+  capture_response_body: true,
+  max_request_body_size: 4096,
+  max_response_body_size: 4096,
+
+  # Domain filtering
+  domain_allow_list: [
+    { domain: 'api.example.com' },
+    { domain: '.mycompany.com', paths: ['/api/', '/v1/'] }
+  ],
+  domain_deny_list: [
+    { domain: 'internal.mycompany.com' }
+  ],
+
+  # Header filtering
+  headers_allow_list: ['content-type', 'accept'],
+  headers_deny_list: ['x-internal-secret'],
+
+  # Header redaction
+  header_redaction: {
+    sensitive_patterns: ['authorization', 'cookie', 'api-key'],
+    strategy: 'replace',  # replace, partial, partial_end, remove
+    redaction_string: '[REDACTED]',
+    visible_chars: 4,
+    enabled: true
+  },
+
+  # Export settings
+  export_mode: 'batched',  # or 'immediate'
+  batch_size: 50,
+  batch_timeout: 5000
+)
+```
+
+### File-Based Configuration
+
+```ruby
+# Load from JSON file
+Pingops.initialize('/path/to/pingops.json')
+
+# Or with config_file key
+Pingops.initialize(config_file: '/path/to/pingops.yaml')
+```
+
+Example `pingops.json`:
+
+```json
+{
+  "apiKey": "your-api-key",
+  "baseUrl": "https://api.pingops.com",
+  "serviceName": "my-service",
+  "debug": false,
+  "captureRequestBody": true,
+  "captureResponseBody": true,
+  "domainAllowList": [
+    { "domain": "api.example.com" }
+  ]
+}
+```
+
+### Environment Variables
+
+Environment variables override file and programmatic configuration:
+
+| Variable | Description |
+|----------|-------------|
+| `PINGOPS_API_KEY` | API key for authentication |
+| `PINGOPS_BASE_URL` | PingOps backend URL |
+| `PINGOPS_SERVICE_NAME` | Service name for traces |
+| `PINGOPS_DEBUG` | Enable debug logging ("true") |
+| `PINGOPS_BATCH_SIZE` | Batch size for export |
+| `PINGOPS_BATCH_TIMEOUT` | Batch timeout in milliseconds |
+| `PINGOPS_EXPORT_MODE` | Export mode (batched/immediate) |
+| `PINGOPS_CONFIG_FILE` | Config file path (for auto-init) |
+
+## API Reference
+
+### `Pingops.initialize(config)`
+
+Initialize the SDK. Idempotent - subsequent calls are no-ops.
+
+```ruby
+# With hash
+Pingops.initialize(api_key: 'key', base_url: 'url', service_name: 'name')
+
+# With file path
+Pingops.initialize('/path/to/config.json')
+
+# With config_file key
+Pingops.initialize(config_file: '/path/to/config.yaml')
+```
+
+### `Pingops.shutdown`
+
+Shutdown the SDK, flushing any pending spans.
+
+```ruby
+Pingops.shutdown
+```
+
+### `Pingops.start_trace(options, &block)`
+
+Start a trace and execute the block within the trace context.
+
+```ruby
+result = Pingops.start_trace(
+  attributes: {
+    user_id: 'user-123',
+    session_id: 'session-456',
+    tags: ['production', 'web'],
+    metadata: { 'request_id' => 'abc123' },
+    capture_request_body: true,
+    capture_response_body: true
+  },
+  seed: 'optional-seed-for-deterministic-trace-id'
+) do
+  # Your code here
+  Net::HTTP.get(URI('https://api.example.com'))
+end
+```
+
+### `Pingops.active_trace_id`
+
+Get the current trace ID (within a trace block).
+
+```ruby
+Pingops.start_trace do
+  trace_id = Pingops.active_trace_id
+  # => "a1b2c3d4e5f6..."
+end
+```
+
+### `Pingops.active_span_id`
+
+Get the current span ID (within a trace block).
+
+```ruby
+Pingops.start_trace do
+  span_id = Pingops.active_span_id
+  # => "a1b2c3d4..."
+end
+```
+
+### `Pingops.initialized?`
+
+Check if the SDK is initialized.
+
+```ruby
+Pingops.initialized?  # => true/false
+```
+
+## Domain Rules
+
+Domain rules support exact and suffix matching:
+
+```ruby
+domain_allow_list: [
+  # Exact match
+  { domain: 'api.example.com' },
+
+  # Suffix match (starts with .)
+  { domain: '.mycompany.com' },  # Matches api.mycompany.com, app.mycompany.com, etc.
+
+  # With path restriction
+  { domain: 'api.example.com', paths: ['/api/', '/v1/'] },
+
+  # With body capture override
+  {
+    domain: 'external-api.com',
+    capture_request_body: true,
+    capture_response_body: false
+  },
+
+  # With header override
+  {
+    domain: 'partner-api.com',
+    headers_allow_list: ['content-type', 'x-partner-id']
+  }
+]
+```
+
+## Header Redaction
+
+Headers matching sensitive patterns are automatically redacted:
+
+```ruby
+header_redaction: {
+  sensitive_patterns: [
+    'authorization',
+    'cookie',
+    'x-api-key'
+  ],
+  strategy: 'replace',      # Entire value replaced
+  # strategy: 'partial',    # First N chars visible: "Bear..."
+  # strategy: 'partial_end', # Last N chars visible: "...oken"
+  # strategy: 'remove',     # Header removed entirely
+  redaction_string: '[REDACTED]',
+  visible_chars: 4,
+  enabled: true
+}
+```
+
+Default sensitive patterns include: authorization, cookie, api-key, token, secret, password, and many more.
+
+## Auto-Initialization
+
+For simple setups, use the register pattern:
+
+```bash
+# Set environment variables
+export PINGOPS_API_KEY=your-key
+export PINGOPS_BASE_URL=https://api.pingops.com
+export PINGOPS_SERVICE_NAME=my-service
+
+# Run with auto-init
+ruby -r pingops/register your_app.rb
+```
+
+Or in your application:
+
+```ruby
+require 'pingops/register'
+
+# SDK is automatically initialized from environment
+Pingops.start_trace { ... }
+```
+
+## Rails Integration
+
+Create `config/initializers/pingops.rb`:
+
+```ruby
+require 'pingops'
+
+if Rails.env.production? || Rails.env.staging?
+  Pingops.initialize(
+    api_key: ENV.fetch('PINGOPS_API_KEY'),
+    base_url: ENV.fetch('PINGOPS_BASE_URL'),
+    service_name: Rails.application.class.module_parent_name,
+    debug: Rails.env.development?
+  )
+end
+
+at_exit { Pingops.shutdown if Pingops.initialized? }
+```
+
+Add tracing to controllers:
+
+```ruby
+class ApplicationController < ActionController::Base
+  around_action :trace_request
+
+  private
+
+  def trace_request
+    Pingops.start_trace(
+      attributes: {
+        user_id: current_user&.id,
+        session_id: session.id,
+        tags: [Rails.env, controller_name],
+        metadata: {
+          'controller' => controller_name,
+          'action' => action_name
+        }
+      }
+    ) { yield }
+  end
+end
+```
+
+## Requirements
+
+- Ruby 3.0+
+- OpenTelemetry SDK 1.4+
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+
+# Generate documentation
+bundle exec yard doc
+```
+
+## Publishing
+
+```bash
+# 1) Bump version (lib/pingops/version.rb) and update CHANGELOG if needed
+
+# 2) Build the gem
+gem build pingops.gemspec
+
+# 3) Authenticate to RubyGems (first time only)
+gem signin
+
+# 4) Push the built gem
+gem push pingops-<version>.gem
+```
+
+## License
+
+MIT License - see LICENSE file for details.

data/lib/pingops/core/body_capture.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Pingops
+  module Core
+    # Body capture utilities for request/response bodies
+    module BodyCapture
+      class << self
+        # Determine if request body should be captured for a span
+        # Priority: Context > Domain rule > Global config
+        #
+        # @param context [OpenTelemetry::Context] Current context
+        # @param domain_rule [DomainRule, nil] Matching domain rule
+        # @param global_config [Configuration] Global configuration
+        # @return [Boolean]
+        def should_capture_request_body?(context, domain_rule, global_config)
+          # 1. Check context first
+          context_value = ContextKeys.capture_request_body?(context)
+          return context_value unless context_value.nil?
+
+          # 2. Check domain rule
+          return domain_rule.capture_request_body if domain_rule && !domain_rule.capture_request_body.nil?
+
+          # 3. Fall back to global config
+          global_config.capture_request_body
+        end
+
+        # Determine if response body should be captured for a span
+        # Priority: Context > Domain rule > Global config
+        #
+        # @param context [OpenTelemetry::Context] Current context
+        # @param domain_rule [DomainRule, nil] Matching domain rule
+        # @param global_config [Configuration] Global configuration
+        # @return [Boolean]
+        def should_capture_response_body?(context, domain_rule, global_config)
+          # 1. Check context first
+          context_value = ContextKeys.capture_response_body?(context)
+          return context_value unless context_value.nil?
+
+          # 2. Check domain rule
+          return domain_rule.capture_response_body if domain_rule && !domain_rule.capture_response_body.nil?
+
+          # 3. Fall back to global config
+          global_config.capture_response_body
+        end
+
+        # Truncate body if it exceeds max size
+        # @param body [String] The body content
+        # @param max_size [Integer] Maximum size in bytes
+        # @return [String, nil] The body or nil if empty
+        def truncate_body(body, max_size)
+          return nil if body.nil? || body.empty?
+
+          if body.bytesize > max_size
+            "#{body.byteslice(0, max_size)}... [truncated, #{body.bytesize} bytes total]"
+          else
+            body
+          end
+        end
+
+        # Check if content encoding indicates compression
+        # @param encoding [String, nil] Content-Encoding header value
+        # @return [Boolean]
+        def compressed?(encoding)
+          return false if encoding.nil? || encoding.empty?
+
+          Constants::COMPRESSED_ENCODINGS.any? { |e| encoding.downcase.include?(e) }
+        end
+
+        # Encode compressed body as base64
+        # @param body [String] Raw body bytes
+        # @param max_size [Integer] Maximum size in bytes
+        # @return [String, nil] Base64 encoded body or nil
+        def encode_compressed_body(body, max_size)
+          return nil if body.nil? || body.empty?
+          return nil if body.bytesize > max_size
+
+          Base64.strict_encode64(body)
+        end
+
+        # Filter body attributes from span based on capture settings
+        # @param attributes [Hash] Span attributes
+        # @param capture_request [Boolean] Whether to keep request body
+        # @param capture_response [Boolean] Whether to keep response body
+        # @return [Hash] Filtered attributes
+        def filter_body_attributes(attributes, capture_request:, capture_response:)
+          result = attributes.dup
+
+          result.delete(Constants::ATTR_HTTP_REQUEST_BODY) unless capture_request
+
+          unless capture_response
+            result.delete(Constants::ATTR_HTTP_RESPONSE_BODY)
+            result.delete(Constants::ATTR_HTTP_RESPONSE_CONTENT_ENCODING)
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/pingops/core/configuration.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Pingops
+  module Core
+    # Main configuration class for the PingOps SDK
+    class Configuration
+      attr_accessor :api_key, :base_url, :service_name, :debug,
+                    :headers_allow_list, :headers_deny_list,
+                    :capture_request_body, :capture_response_body,
+                    :max_request_body_size, :max_response_body_size,
+                    :domain_allow_list, :domain_deny_list,
+                    :header_redaction, :batch_size, :batch_timeout, :export_mode
+
+      def initialize(options = {})
+        @api_key = options[:api_key]
+        @base_url = options[:base_url]
+        @service_name = options[:service_name]
+        @debug = options[:debug] || false
+        @headers_allow_list = options[:headers_allow_list]&.map { |h| h.to_s.downcase }
+        @headers_deny_list = options[:headers_deny_list]&.map { |h| h.to_s.downcase }
+        @capture_request_body = options[:capture_request_body] || false
+        @capture_response_body = options[:capture_response_body] || false
+        @max_request_body_size = options[:max_request_body_size] || Constants::DEFAULT_MAX_REQUEST_BODY_SIZE
+        @max_response_body_size = options[:max_response_body_size] || Constants::DEFAULT_MAX_RESPONSE_BODY_SIZE
+        @batch_size = options[:batch_size] || Constants::DEFAULT_BATCH_SIZE
+        @batch_timeout = options[:batch_timeout] || Constants::DEFAULT_BATCH_TIMEOUT
+        @export_mode = options[:export_mode] || Constants::EXPORT_MODE_BATCHED
+
+        # Parse domain rules
+        @domain_allow_list = parse_domain_rules(options[:domain_allow_list])
+        @domain_deny_list = parse_domain_rules(options[:domain_deny_list])
+
+        # Parse header redaction config
+        @header_redaction = parse_header_redaction(options[:header_redaction])
+      end
+
+      # Check if configuration is valid (has required fields)
+      # @return [Boolean]
+      def valid?
+        !@base_url.nil? && !@base_url.empty? &&
+          !@service_name.nil? && !@service_name.empty?
+      end
+
+      # Validate and raise if invalid
+      # @raise [Pingops::ConfigurationError] if required fields are missing
+      def validate!
+        missing = []
+        missing << 'baseUrl (or PINGOPS_BASE_URL)' if @base_url.nil? || @base_url.empty?
+        missing << 'serviceName (or PINGOPS_SERVICE_NAME)' if @service_name.nil? || @service_name.empty?
+
+        return if missing.empty?
+
+        raise Pingops::ConfigurationError, "Missing required configuration: #{missing.join(', ')}"
+      end
+
+      # Create configuration from a file path
+      # @param file_path [String] Path to JSON or YAML config file
+      # @return [Configuration]
+      def self.from_file(file_path)
+        content = File.read(file_path)
+        data = if file_path.end_with?('.yaml', '.yml')
+                 require 'yaml'
+                 YAML.safe_load(content, symbolize_names: true)
+               else
+                 JSON.parse(content, symbolize_names: true)
+               end
+
+        from_hash(data)
+      end
+
+      # Create configuration from a hash
+      # @param hash [Hash] Configuration hash
+      # @return [Configuration]
+      def self.from_hash(hash)
+        return hash if hash.is_a?(Configuration)
+
+        new(
+          api_key: hash[:api_key] || hash[:apiKey] || hash['apiKey'],
+          base_url: hash[:base_url] || hash[:baseUrl] || hash['baseUrl'],
+          service_name: hash[:service_name] || hash[:serviceName] || hash['serviceName'],
+          debug: hash[:debug] || hash['debug'],
+          headers_allow_list: hash[:headers_allow_list] || hash[:headersAllowList] || hash['headersAllowList'],
+          headers_deny_list: hash[:headers_deny_list] || hash[:headersDenyList] || hash['headersDenyList'],
+          capture_request_body: hash[:capture_request_body] || hash[:captureRequestBody] || hash['captureRequestBody'],
+          capture_response_body: hash[:capture_response_body] || hash[:captureResponseBody] ||
+                                 hash['captureResponseBody'],
+          max_request_body_size: hash[:max_request_body_size] || hash[:maxRequestBodySize] ||
+                                 hash['maxRequestBodySize'],
+          max_response_body_size: hash[:max_response_body_size] || hash[:maxResponseBodySize] ||
+                                  hash['maxResponseBodySize'],
+          domain_allow_list: hash[:domain_allow_list] || hash[:domainAllowList] || hash['domainAllowList'],
+          domain_deny_list: hash[:domain_deny_list] || hash[:domainDenyList] || hash['domainDenyList'],
+          header_redaction: hash[:header_redaction] || hash[:headerRedaction] || hash['headerRedaction'],
+          batch_size: hash[:batch_size] || hash[:batchSize] || hash['batchSize'],
+          batch_timeout: hash[:batch_timeout] || hash[:batchTimeout] || hash['batchTimeout'],
+          export_mode: hash[:export_mode] || hash[:exportMode] || hash['exportMode']
+        )
+      end
+
+      # Create configuration from environment variables only
+      # @return [Configuration]
+      def self.from_env
+        new(
+          api_key: ENV.fetch('PINGOPS_API_KEY', nil),
+          base_url: ENV.fetch('PINGOPS_BASE_URL', nil),
+          service_name: ENV.fetch('PINGOPS_SERVICE_NAME', nil),
+          debug: ENV.fetch('PINGOPS_DEBUG', nil) == 'true',
+          batch_size: env_int('PINGOPS_BATCH_SIZE'),
+          batch_timeout: env_int('PINGOPS_BATCH_TIMEOUT'),
+          export_mode: ENV.fetch('PINGOPS_EXPORT_MODE', nil)
+        )
+      end
+
+      # Load from file and merge with environment variables (env wins)
+      # @param file_path [String] Path to config file
+      # @return [Configuration]
+      def self.load_with_env(file_path)
+        file_config = from_file(file_path)
+        env_config = from_env
+
+        merge(file_config, env_config)
+      end
+
+      # Merge two configurations (second wins for non-nil values)
+      # @param base [Configuration] Base configuration
+      # @param override [Configuration] Override configuration
+      # @return [Configuration]
+      def self.merge(base, override)
+        new(
+          api_key: override.api_key || base.api_key,
+          base_url: override.base_url || base.base_url,
+          service_name: override.service_name || base.service_name,
+          debug: override.debug || base.debug,
+          headers_allow_list: override.headers_allow_list || base.headers_allow_list,
+          headers_deny_list: override.headers_deny_list || base.headers_deny_list,
+          capture_request_body: override.capture_request_body || base.capture_request_body,
+          capture_response_body: override.capture_response_body || base.capture_response_body,
+          max_request_body_size: non_default_or(override.max_request_body_size, base.max_request_body_size,
+                                                Constants::DEFAULT_MAX_REQUEST_BODY_SIZE),
+          max_response_body_size: non_default_or(override.max_response_body_size, base.max_response_body_size,
+                                                 Constants::DEFAULT_MAX_RESPONSE_BODY_SIZE),
+          domain_allow_list: override.domain_allow_list&.any? ? override.domain_allow_list : base.domain_allow_list,
+          domain_deny_list: override.domain_deny_list&.any? ? override.domain_deny_list : base.domain_deny_list,
+          header_redaction: override.header_redaction || base.header_redaction,
+          batch_size: non_default_or(override.batch_size, base.batch_size, Constants::DEFAULT_BATCH_SIZE),
+          batch_timeout: non_default_or(override.batch_timeout, base.batch_timeout, Constants::DEFAULT_BATCH_TIMEOUT),
+          export_mode: non_default_or(override.export_mode, base.export_mode, Constants::EXPORT_MODE_BATCHED)
+        )
+      end
+
+      private
+
+      def parse_domain_rules(rules)
+        return nil if rules.nil?
+
+        rules.map { |rule| DomainRule.from_hash(rule) }
+      end
+
+      def parse_header_redaction(config)
+        HeaderRedactionConfig.from_hash(config)
+      end
+
+      class << self
+        private
+
+        def env_int(name)
+          value = ENV.fetch(name, nil)
+          value&.to_i
+        end
+
+        def non_default_or(override, base, default)
+          return override if override && override != default
+
+          base
+        end
+      end
+    end
+  end
+end