pingops 0.0.1

data/lib/pingops/sdk.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require 'opentelemetry-sdk'
+require 'opentelemetry-api'
+
+module Pingops
+  # Main SDK module providing the public API
+  module SDK
+    @initialized = false
+    @config = nil
+    @span_processor = nil
+    @mutex = Mutex.new
+
+    class << self
+      # Initialize the PingOps SDK
+      #
+      # @overload initialize(config)
+      #   @param config [Hash, Core::Configuration] Full processor config object
+      # @overload initialize(config_file_path)
+      #   @param config_file_path [String] Path to a JSON or YAML config file
+      # @overload initialize(config)
+      #   @param config [Hash] Hash with :config_file key pointing to config file
+      #
+      # @raise [Pingops::ConfigurationError] if required fields are missing
+      # @return [void]
+      def initialize_pingops(config)
+        @mutex.synchronize do
+          if @initialized
+            log_debug('SDK already initialized, skipping')
+            return
+          end
+
+          # Resolve configuration
+          resolved_config = resolve_config(config)
+          resolved_config.validate!
+
+          @config = resolved_config
+          log_debug("Configuration resolved: service_name=#{resolved_config.service_name}")
+
+          # Create resource with service.name
+          resource = create_resource(resolved_config)
+
+          # Create span processor
+          @span_processor = Otel::SpanProcessor.new(resolved_config)
+          log_debug('Span processor created')
+
+          # Install instrumentations
+          Instrumentation::Manager.install(resolved_config)
+
+          # Configure OpenTelemetry SDK
+          configure_otel_sdk(resource, @span_processor, resolved_config)
+
+          # Create and register isolated TracerProvider
+          isolated_provider = Otel::TracerProvider.create_isolated(
+            resource: resource,
+            span_processor: @span_processor
+          )
+          Otel::TracerProvider.set(isolated_provider)
+
+          # Register as global provider (after main SDK, so it becomes the default)
+          OpenTelemetry.tracer_provider = isolated_provider
+
+          @initialized = true
+          log_debug('SDK initialized successfully')
+        end
+      end
+
+      # Shutdown the PingOps SDK
+      # Shuts down isolated TracerProvider first, then main OTEL SDK
+      #
+      # @return [void]
+      def shutdown_pingops
+        @mutex.synchronize do
+          return unless @initialized
+
+          log_debug('Shutting down SDK...')
+
+          # 1. Shutdown isolated TracerProvider
+          Otel::TracerProvider.shutdown
+
+          # 2. Shutdown span processor
+          @span_processor&.shutdown
+
+          # 3. Clear instrumentations
+          Instrumentation::Manager.reset!
+
+          # 4. Clear state
+          @initialized = false
+          @config = nil
+          @span_processor = nil
+
+          log_debug('SDK shutdown complete')
+        end
+      end
+
+      # Start a trace with custom attributes
+      #
+      # @param options [Hash, Core::StartTraceOptions] Trace options
+      # @option options [Hash, Core::TraceAttributes] :attributes Custom attributes
+      # @option options [String] :seed Optional seed for deterministic trace ID
+      # @yield Block to execute within the trace
+      # @return [Object] Result of the block
+      #
+      # @example
+      #   Pingops.start_trace(attributes: { user_id: "123" }) do
+      #     # Make HTTP requests here
+      #     Net::HTTP.get(URI("https://api.example.com"))
+      #   end
+      def start_trace(options = {}, &block)
+        raise ArgumentError, 'Block required for start_trace' unless block_given?
+
+        # Auto-initialize if not initialized
+        auto_initialize_if_needed
+
+        opts = options.is_a?(Core::StartTraceOptions) ? options : Core::StartTraceOptions.from_hash(options)
+
+        # Compute trace ID
+        trace_id = compute_trace_id(opts)
+        span_id = Core::IdGenerator.generate_span_id
+
+        # Create span context
+        span_context = OpenTelemetry::Trace::SpanContext.new(
+          trace_id: Core::IdGenerator.trace_id_to_bytes(trace_id),
+          span_id: Core::IdGenerator.span_id_to_bytes(span_id),
+          trace_flags: OpenTelemetry::Trace::TraceFlags::SAMPLED
+        )
+
+        # Get current context and set trace ID
+        context = OpenTelemetry::Context.current
+        context = Core::ContextKeys.set_trace_id(context, trace_id)
+
+        # Set attributes on context if provided
+        context = Core::ContextKeys.set_attributes(context, opts.attributes) if opts.attributes
+
+        # Get tracer from PingOps provider
+        tracer = Otel::TracerProvider.tracer
+
+        # Create a non-recording span to establish the context
+        parent_span = OpenTelemetry::Trace.non_recording_span(span_context)
+        context = OpenTelemetry::Trace.context_with_span(parent_span, parent_context: context)
+
+        # Run the block within the span context
+        OpenTelemetry::Context.with_current(context) do
+          tracer.in_span(
+            Core::Constants::ROOT_SPAN_NAME,
+            kind: :internal,
+            &block
+          )
+        end
+      end
+
+      # Get the active trace ID from the current context
+      #
+      # @return [String, nil] The trace ID or nil if no active span
+      def active_trace_id
+        span = OpenTelemetry::Trace.current_span
+        return nil unless span
+
+        span_context = span.context
+        return nil unless span_context&.valid?
+
+        Core::IdGenerator.bytes_to_trace_id(span_context.trace_id)
+      end
+
+      # Get the active span ID from the current context
+      #
+      # @return [String, nil] The span ID or nil if no active span
+      def active_span_id
+        span = OpenTelemetry::Trace.current_span
+        return nil unless span
+
+        span_context = span.context
+        return nil unless span_context&.valid?
+
+        Core::IdGenerator.bytes_to_span_id(span_context.span_id)
+      end
+
+      # Check if the SDK is initialized
+      #
+      # @return [Boolean]
+      def initialized?
+        @mutex.synchronize do
+          @initialized
+        end
+      end
+
+      # Get the current configuration
+      #
+      # @return [Core::Configuration, nil]
+      def configuration
+        @mutex.synchronize do
+          @config
+        end
+      end
+
+      # Reset SDK state (for testing)
+      # @api private
+      def reset!
+        @mutex.synchronize do
+          Otel::TracerProvider.clear!
+          Otel::ConfigStore.clear!
+          Instrumentation::Manager.reset!
+          @initialized = false
+          @config = nil
+          @span_processor = nil
+        end
+      end
+
+      private
+
+      def resolve_config(config)
+        case config
+        when String
+          # File path
+          Core::Configuration.load_with_env(config)
+        when Hash
+          if config[:config_file] || config['configFile']
+            # Hash with config_file key
+            file_path = config[:config_file] || config['configFile']
+            Core::Configuration.load_with_env(file_path)
+          else
+            # Regular config hash - merge with env
+            base_config = Core::Configuration.from_hash(config)
+            env_config = Core::Configuration.from_env
+            Core::Configuration.merge(base_config, env_config)
+          end
+        when Core::Configuration
+          # Already a Configuration object
+          config
+        else
+          raise ArgumentError, "Invalid config type: #{config.class}"
+        end
+      end
+
+      def create_resource(config)
+        OpenTelemetry::SDK::Resources::Resource.create(
+          'service.name' => config.service_name
+        )
+      end
+
+      def configure_otel_sdk(resource, _span_processor, _config)
+        OpenTelemetry::SDK.configure do |c|
+          c.resource = resource
+
+          # Get instrumentations
+          Instrumentation::Manager.otel_instrumentations.each do |instrumentation|
+            c.use(instrumentation.class.name.split('::').last)
+          rescue StandardError
+            # Ignore if instrumentation can't be used
+          end
+        end
+      end
+
+      def auto_initialize_if_needed
+        return if initialized?
+
+        # Check for required environment variables
+        api_key = ENV.fetch('PINGOPS_API_KEY', nil)
+        base_url = ENV.fetch('PINGOPS_BASE_URL', nil)
+        service_name = ENV.fetch('PINGOPS_SERVICE_NAME', nil)
+
+        missing = []
+        missing << 'PINGOPS_API_KEY' unless api_key
+        missing << 'PINGOPS_BASE_URL' unless base_url
+        missing << 'PINGOPS_SERVICE_NAME' unless service_name
+
+        raise ConfigurationError, "Auto-initialization requires: #{missing.join(', ')}" unless missing.empty?
+
+        # Initialize from environment
+        initialize_pingops(Core::Configuration.from_env)
+      end
+
+      def compute_trace_id(options)
+        # Priority: attributes.traceId > seed > random
+        if options.attributes&.trace_id
+          options.attributes.trace_id
+        elsif options.seed
+          Core::IdGenerator.generate_trace_id(options.seed)
+        else
+          Core::IdGenerator.generate_trace_id
+        end
+      end
+
+      def log_debug(message)
+        return unless @config&.debug
+
+        puts "[Pingops DEBUG] #{message}"
+      end
+    end
+  end
+end

data/lib/pingops/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pingops
+  VERSION = '0.0.1'
+end

data/lib/pingops.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative 'pingops/version'
+require_relative 'pingops/errors'
+
+# Core components (pure logic, no OpenTelemetry dependencies loaded yet)
+require_relative 'pingops/core/constants'
+require_relative 'pingops/core/types'
+require_relative 'pingops/core/configuration'
+require_relative 'pingops/core/id_generator'
+require_relative 'pingops/core/domain_filter'
+require_relative 'pingops/core/header_filter'
+require_relative 'pingops/core/span_eligibility'
+require_relative 'pingops/core/body_capture'
+require_relative 'pingops/core/context_keys'
+
+# OpenTelemetry integration
+require_relative 'pingops/otel/config_store'
+require_relative 'pingops/otel/tracer_provider'
+require_relative 'pingops/otel/span_processor'
+
+# Instrumentation
+require_relative 'pingops/instrumentation/net_http'
+require_relative 'pingops/instrumentation/manager'
+
+# SDK public API
+require_relative 'pingops/sdk'
+
+# Main Pingops module
+# Provides a convenient interface to the PingOps SDK
+module Pingops
+  class << self
+    # Initialize the PingOps SDK
+    #
+    # @overload initialize(config)
+    #   @param config [Hash] Full processor config object
+    # @overload initialize(config_file_path)
+    #   @param config_file_path [String] Path to a JSON or YAML config file
+    #
+    # @example Initialize with a hash
+    #   Pingops.initialize(
+    #     api_key: "your-api-key",
+    #     base_url: "https://api.pingops.com",
+    #     service_name: "my-service"
+    #   )
+    #
+    # @example Initialize with a config file
+    #   Pingops.initialize("/path/to/pingops.json")
+    #
+    # @example Initialize with camelCase keys (compatible with JS/Node)
+    #   Pingops.initialize(
+    #     apiKey: "your-api-key",
+    #     baseUrl: "https://api.pingops.com",
+    #     serviceName: "my-service"
+    #   )
+    #
+    # @raise [Pingops::ConfigurationError] if required fields are missing
+    # @return [void]
+    def initialize(config = nil)
+      if config.nil?
+        # Try to initialize from environment
+        SDK.initialize_pingops(Core::Configuration.from_env)
+      else
+        SDK.initialize_pingops(config)
+      end
+    end
+
+    # Shutdown the PingOps SDK
+    #
+    # @return [void]
+    def shutdown
+      SDK.shutdown_pingops
+    end
+
+    # Start a trace with custom attributes
+    #
+    # @param options [Hash] Trace options
+    # @option options [Hash] :attributes Custom attributes (user_id, session_id, tags, metadata)
+    # @option options [String] :seed Optional seed for deterministic trace ID
+    # @yield Block to execute within the trace
+    # @return [Object] Result of the block
+    #
+    # @example Basic usage
+    #   Pingops.start_trace do
+    #     Net::HTTP.get(URI("https://api.example.com"))
+    #   end
+    #
+    # @example With custom attributes
+    #   Pingops.start_trace(
+    #     attributes: {
+    #       user_id: "user-123",
+    #       session_id: "session-456",
+    #       tags: ["production", "web"],
+    #       metadata: { "request_id" => "abc123" }
+    #     }
+    #   ) do
+    #     # Your code here
+    #   end
+    #
+    # @example With deterministic trace ID
+    #   Pingops.start_trace(seed: "my-unique-seed") do
+    #     # Same seed always produces the same trace ID
+    #   end
+    def start_trace(options = {}, &block)
+      SDK.start_trace(options, &block)
+    end
+
+    # Get the active trace ID from the current context
+    #
+    # @return [String, nil] The trace ID or nil if no active span
+    #
+    # @example
+    #   Pingops.start_trace do
+    #     trace_id = Pingops.active_trace_id
+    #     puts "Current trace ID: #{trace_id}"
+    #   end
+    def active_trace_id
+      SDK.active_trace_id
+    end
+
+    # Get the active span ID from the current context
+    #
+    # @return [String, nil] The span ID or nil if no active span
+    #
+    # @example
+    #   Pingops.start_trace do
+    #     span_id = Pingops.active_span_id
+    #     puts "Current span ID: #{span_id}"
+    #   end
+    def active_span_id
+      SDK.active_span_id
+    end
+
+    # Check if the SDK is initialized
+    #
+    # @return [Boolean]
+    def initialized?
+      SDK.initialized?
+    end
+
+    # Get the current configuration
+    #
+    # @return [Pingops::Core::Configuration, nil]
+    def configuration
+      SDK.configuration
+    end
+
+    # Alias for initialize (follows JS/Node naming convention)
+    alias initialize_pingops initialize
+
+    # Alias for shutdown (follows JS/Node naming convention)
+    alias shutdown_pingops shutdown
+
+    # Alias for active_trace_id (follows JS/Node naming convention)
+    alias get_active_trace_id active_trace_id
+
+    # Alias for active_span_id (follows JS/Node naming convention)
+    alias get_active_span_id active_span_id
+  end
+end

data/pingops.gemspec

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'lib/pingops/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'pingops'
+  spec.version = Pingops::VERSION
+  spec.authors = ['PingOps']
+  spec.email = ['support@pingops.com']
+
+  spec.summary = 'PingOps SDK for Ruby - OpenTelemetry-based HTTP tracing'
+  spec.description = 'Instruments outgoing HTTP requests, exports spans to PingOps backend via OTLP, ' \
+                     'and supports manual tracing with custom attributes, domain filtering, and header redaction.'
+  spec.homepage = 'https://github.com/pingops/pingops-rb'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.glob('{lib,exe}/**/*') + %w[
+    README.md
+    CHANGELOG.md
+    pingops.gemspec
+  ]
+
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # OpenTelemetry dependencies
+  spec.add_dependency 'opentelemetry-api', '~> 1.2'
+  spec.add_dependency 'opentelemetry-exporter-otlp', '~> 0.28'
+  spec.add_dependency 'opentelemetry-instrumentation-faraday', '~> 0.24'
+  spec.add_dependency 'opentelemetry-instrumentation-http_client', '~> 0.22'
+  spec.add_dependency 'opentelemetry-instrumentation-net_http', '~> 0.22'
+  spec.add_dependency 'opentelemetry-sdk', '~> 1.4'
+
+  # Configuration
+  spec.add_dependency 'base64', '~> 0.2'
+  spec.add_dependency 'json', '~> 2.0'
+
+  # Development dependencies
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'rubocop', '~> 1.50'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.20'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'webmock', '~> 3.18'
+  spec.add_development_dependency 'yard', '~> 0.9'
+end