tasker-engine 1.0.0

data/lib/tasker/telemetry/plugins/csv_exporter.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'csv'
+require_relative 'base_exporter'
+
+module Tasker
+  module Telemetry
+    module Plugins
+      # CSV format exporter for metrics data
+      #
+      # Exports metrics in CSV format with configurable columns and headers.
+      # Flattens metric labels into separate columns for tabular representation.
+      #
+      # @example Basic Usage
+      #   exporter = Tasker::Telemetry::Plugins::CsvExporter.new
+      #   result = exporter.export(metrics_data, include_headers: true)
+      #
+      # @example With Custom Columns
+      #   exporter = Tasker::Telemetry::Plugins::CsvExporter.new(
+      #     columns: %w[timestamp name type value status]
+      #   )
+      class CsvExporter < BaseExporter
+        VERSION = '1.0.0'
+        DESCRIPTION = 'CSV format exporter with configurable columns and label flattening'
+
+        DEFAULT_COLUMNS = %w[
+          timestamp
+          name
+          type
+          value
+          labels
+        ].freeze
+
+        # @param options [Hash] Configuration options
+        # @option options [Array<String>] :columns Column names to include
+        # @option options [String] :separator CSV field separator
+        # @option options [Boolean] :flatten_labels Flatten labels into separate columns
+        def initialize(options = {})
+          super()
+          @columns = options.fetch(:columns, DEFAULT_COLUMNS)
+          @separator = options.fetch(:separator, ',')
+          @flatten_labels = options.fetch(:flatten_labels, true)
+        end
+
+        # Export metrics data as CSV
+        #
+        # @param metrics_data [Hash] Metrics data from MetricsBackend
+        # @param options [Hash] Export options
+        # @option options [Boolean] :include_headers Include CSV headers
+        # @option options [String] :row_separator Row separator character
+        # @return [Hash] Export result with CSV string
+        def export(metrics_data, options = {})
+          include_headers = options.fetch(:include_headers, true)
+          row_separator = options.fetch(:row_separator, "\n")
+
+          metrics = metrics_data[:metrics] || {}
+          timestamp = metrics_data[:timestamp]
+
+          return empty_export if metrics.empty?
+
+          # Build CSV data
+          csv_data = build_csv_data(metrics, timestamp, include_headers, row_separator)
+
+          {
+            success: true,
+            format: 'csv',
+            data: csv_data,
+            size_bytes: csv_data.bytesize,
+            metrics_count: metrics.size,
+            rows: metrics.size + (include_headers ? 1 : 0)
+          }
+        end
+
+        # Check if format is supported
+        #
+        # @param format [String, Symbol] Format to check
+        # @return [Boolean] True if CSV format is supported
+        def supports_format?(format)
+          %w[csv].include?(format.to_s.downcase)
+        end
+
+        # Get supported formats
+        #
+        # @return [Array<String>] List of supported formats
+        def supported_formats
+          %w[csv]
+        end
+
+        private
+
+        # Build CSV data from metrics
+        def build_csv_data(metrics, timestamp, include_headers, row_separator)
+          # Determine all label keys if flattening
+          all_label_keys = if @flatten_labels
+                             extract_all_label_keys(metrics)
+                           else
+                             []
+                           end
+
+          # Build headers
+          headers = build_headers(all_label_keys)
+
+          # Build rows
+          rows = []
+          rows << headers if include_headers
+
+          metrics.each_value do |metric_data|
+            row = build_metric_row(metric_data, timestamp, all_label_keys)
+            rows << row
+          end
+
+          # Generate CSV
+          CSV.generate(col_sep: @separator, row_sep: row_separator) do |csv|
+            rows.each { |row| csv << row }
+          end
+        end
+
+        # Extract all unique label keys from metrics
+        def extract_all_label_keys(metrics)
+          label_keys = Set.new
+
+          metrics.each_value do |metric_data|
+            labels = metric_data[:labels] || {}
+            label_keys.merge(labels.keys.map(&:to_s))
+          end
+
+          label_keys.to_a.sort
+        end
+
+        # Build CSV headers
+        def build_headers(label_keys)
+          headers = []
+
+          @columns.each do |column|
+            case column
+            when 'labels'
+              if @flatten_labels && label_keys.any?
+                headers.concat(label_keys.map { |key| "label_#{key}" })
+              else
+                headers << 'labels'
+              end
+            else
+              headers << column
+            end
+          end
+
+          headers
+        end
+
+        # Build a single metric row
+        def build_metric_row(metric_data, timestamp, label_keys)
+          row = []
+          labels = metric_data[:labels] || {}
+
+          @columns.each do |column|
+            case column
+            when 'timestamp'
+              row << timestamp
+            when 'name'
+              row << metric_data[:name]
+            when 'type'
+              row << metric_data[:type]
+            when 'value'
+              row << metric_data[:value]
+            when 'labels'
+              if @flatten_labels && label_keys.any?
+                # Add each label as separate column
+                label_keys.each do |key|
+                  row << (labels[key.to_s] || labels[key.to_sym] || '')
+                end
+              else
+                # Add labels as JSON string
+                row << (labels.any? ? labels.to_json : '')
+              end
+            else
+              # Custom column - try to get from metric data
+              row << (metric_data[column.to_sym] || '')
+            end
+          end
+
+          row
+        end
+
+        # Return empty export result
+        def empty_export
+          {
+            success: true,
+            format: 'csv',
+            data: '',
+            size_bytes: 0,
+            metrics_count: 0,
+            rows: 0
+          }
+        end
+      end
+    end
+  end
+end

data/lib/tasker/telemetry/plugins/json_exporter.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative 'base_exporter'
+
+module Tasker
+  module Telemetry
+    module Plugins
+      # JSON format exporter for metrics data
+      #
+      # Exports metrics in structured JSON format with optional pretty printing
+      # and custom field mapping.
+      #
+      # @example Basic Usage
+      #   exporter = Tasker::Telemetry::Plugins::JsonExporter.new
+      #   result = exporter.export(metrics_data, pretty: true)
+      #
+      # @example With Custom Field Mapping
+      #   exporter = Tasker::Telemetry::Plugins::JsonExporter.new(
+      #     field_mapping: {
+      #       timestamp: 'collected_at',
+      #       metrics: 'data'
+      #     }
+      #   )
+      class JsonExporter < BaseExporter
+        VERSION = '1.0.0'
+        DESCRIPTION = 'JSON format exporter with customizable field mapping'
+
+        # @param options [Hash] Configuration options
+        # @option options [Hash] :field_mapping Custom field name mapping
+        # @option options [Boolean] :include_metadata Include export metadata
+        def initialize(options = {})
+          super()
+          @field_mapping = options.fetch(:field_mapping, {})
+          @include_metadata = options.fetch(:include_metadata, true)
+        end
+
+        # Export metrics data as JSON
+        #
+        # @param metrics_data [Hash] Metrics data from MetricsBackend
+        # @param options [Hash] Export options
+        # @option options [Boolean] :pretty Pretty print JSON output
+        # @option options [Hash] :additional_fields Extra fields to include
+        # @return [Hash] Export result with JSON string
+        def export(metrics_data, options = {})
+          pretty = options.fetch(:pretty, false)
+          additional_fields = options.fetch(:additional_fields, {})
+
+          # Build export data with field mapping
+          export_data = build_export_data(metrics_data, additional_fields)
+
+          # Generate JSON
+          json_output = if pretty
+                          JSON.pretty_generate(export_data)
+                        else
+                          JSON.generate(export_data)
+                        end
+
+          {
+            success: true,
+            format: 'json',
+            data: json_output,
+            size_bytes: json_output.bytesize,
+            metrics_count: metrics_data[:metrics]&.size || 0
+          }
+        end
+
+        # Check if format is supported
+        #
+        # @param format [String, Symbol] Format to check
+        # @return [Boolean] True if JSON format is supported
+        def supports_format?(format)
+          %w[json].include?(format.to_s.downcase)
+        end
+
+        # Get supported formats
+        #
+        # @return [Array<String>] List of supported formats
+        def supported_formats
+          %w[json]
+        end
+
+        private
+
+        # Build export data structure with field mapping
+        def build_export_data(metrics_data, additional_fields)
+          export_data = {}
+
+          # Apply field mapping or use defaults
+          timestamp_field = @field_mapping.fetch(:timestamp, :timestamp)
+          metrics_field = @field_mapping.fetch(:metrics, :metrics)
+          total_metrics_field = @field_mapping.fetch(:total_metrics, :total_metrics)
+
+          # Core data
+          export_data[timestamp_field] = metrics_data[:timestamp]
+          export_data[metrics_field] = format_metrics(metrics_data[:metrics] || {})
+          export_data[total_metrics_field] = metrics_data[:total_metrics] || 0
+
+          # Add metadata if enabled
+          if @include_metadata
+            metadata_field = @field_mapping.fetch(:metadata, :metadata)
+            export_data[metadata_field] = {
+              exporter: 'json',
+              version: VERSION,
+              exported_at: Time.current.iso8601,
+              field_mapping: @field_mapping.any? ? @field_mapping : nil
+            }.compact
+          end
+
+          # Add additional fields
+          export_data.merge!(additional_fields) if additional_fields.any?
+
+          export_data
+        end
+
+        # Format metrics for JSON export
+        def format_metrics(metrics)
+          # Handle malformed input gracefully
+          return {} unless metrics.is_a?(Hash)
+          return {} if metrics.empty?
+
+          formatted = {}
+
+          metrics.each do |metric_name, metric_data|
+            # Ensure metric_data is a hash
+            next unless metric_data.is_a?(Hash)
+
+            formatted[metric_name] = {
+              name: metric_data[:name],
+              type: metric_data[:type],
+              value: metric_data[:value],
+              labels: metric_data[:labels] || {},
+              help: metric_data[:help]
+            }.compact
+          end
+
+          formatted
+        end
+      end
+    end
+  end
+end

data/lib/tasker/telemetry/prometheus_exporter.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Telemetry
+    # Prometheus exporter for converting native metrics to Prometheus format
+    #
+    # This exporter transforms metrics from the MetricsBackend singleton into
+    # standard Prometheus text format for consumption by monitoring systems.
+    #
+    # @example Basic usage
+    #   exporter = PrometheusExporter.new
+    #   prometheus_text = exporter.export
+    #
+    # @example With custom backend
+    #   exporter = PrometheusExporter.new(MetricsBackend.instance)
+    #   prometheus_text = exporter.export
+    class PrometheusExporter
+      # Initialize exporter with optional metrics backend
+      #
+      # @param backend [MetricsBackend] The metrics backend to export from
+      def initialize(backend = nil)
+        @backend = backend || MetricsBackend.instance
+      end
+
+      # Export all metrics in Prometheus text format
+      #
+      # Returns metrics in the standard Prometheus exposition format as specified at:
+      # https://prometheus.io/docs/instrumenting/exposition_formats/
+      #
+      # @return [String] Prometheus format text
+      def export
+        return '' unless telemetry_enabled?
+
+        metrics_data = @backend.export
+        return '' if metrics_data[:metrics].empty?
+
+        output = []
+        output << export_metadata(metrics_data)
+        output << export_metrics(metrics_data[:metrics])
+        "#{output.flatten.compact.join("\n")}\n"
+      rescue StandardError => e
+        # Log error but don't fail the export
+        log_export_error(e)
+        export_error_metric(e)
+      end
+
+      # Export metrics with error handling
+      #
+      # @return [Hash] Export result with success status and data
+      def safe_export
+        {
+          success: true,
+          data: export,
+          timestamp: Time.current.iso8601,
+          total_metrics: @backend.export[:total_metrics] || 0
+        }
+      rescue StandardError => e
+        {
+          success: false,
+          error: e.message,
+          timestamp: Time.current.iso8601,
+          total_metrics: 0
+        }
+      end
+
+      private
+
+      # Export metadata and help text
+      #
+      # @param metadata [Hash] Metrics metadata
+      # @return [Array<String>] Prometheus metadata lines
+      def export_metadata(metadata)
+        lines = []
+        lines << '# Tasker metrics export'
+        lines << "# GENERATED #{metadata[:timestamp]}"
+        lines << "# TOTAL_METRICS #{metadata[:total_metrics]}"
+        lines << ''
+        lines
+      end
+
+      # Export all metrics by type
+      #
+      # @param metrics [Hash] Hash of metric name to metric data
+      # @return [Array<String>] Prometheus metric lines
+      def export_metrics(metrics)
+        lines = []
+
+        # Group metrics by type for better organization
+        counters = metrics.select { |_, data| data[:type] == :counter }
+        gauges = metrics.select { |_, data| data[:type] == :gauge }
+        histograms = metrics.select { |_, data| data[:type] == :histogram }
+
+        lines.concat(export_counters(counters)) if counters.any?
+        lines.concat(export_gauges(gauges)) if gauges.any?
+        lines.concat(export_histograms(histograms)) if histograms.any?
+
+        lines
+      end
+
+      # Export counter metrics
+      #
+      # @param counters [Hash] Counter metrics data
+      # @return [Array<String>] Prometheus counter lines
+      def export_counters(counters)
+        lines = []
+        counters.each do |name, data|
+          lines << ''
+          lines << "# HELP #{name} #{help_text_for(name, :counter)}"
+          lines << "# TYPE #{name} counter"
+          lines << format_metric_line(name, data[:value], data[:labels])
+        end
+        lines
+      end
+
+      # Export gauge metrics
+      #
+      # @param gauges [Hash] Gauge metrics data
+      # @return [Array<String>] Prometheus gauge lines
+      def export_gauges(gauges)
+        lines = []
+        gauges.each do |name, data|
+          lines << ''
+          lines << "# HELP #{name} #{help_text_for(name, :gauge)}"
+          lines << "# TYPE #{name} gauge"
+          lines << format_metric_line(name, data[:value], data[:labels])
+        end
+        lines
+      end
+
+      # Export histogram metrics
+      #
+      # @param histograms [Hash] Histogram metrics data
+      # @return [Array<String>] Prometheus histogram lines
+      def export_histograms(histograms)
+        lines = []
+        histograms.each do |name, data|
+          lines << ''
+          lines << "# HELP #{name} #{help_text_for(name, :histogram)}"
+          lines << "# TYPE #{name} histogram"
+
+          # Export histogram buckets
+          data[:buckets].each do |le, count|
+            bucket_labels = data[:labels].merge(le: le.to_s)
+            lines << format_metric_line("#{name}_bucket", count, bucket_labels)
+          end
+
+          # Export histogram sum and count
+          lines << format_metric_line("#{name}_sum", data[:sum], data[:labels])
+          lines << format_metric_line("#{name}_count", data[:count], data[:labels])
+        end
+        lines
+      end
+
+      # Format a single metric line
+      #
+      # @param name [String] Metric name
+      # @param value [Numeric] Metric value
+      # @param labels [Hash] Metric labels
+      # @return [String] Formatted Prometheus metric line
+      def format_metric_line(name, value, labels = {})
+        if labels.empty?
+          "#{name} #{value}"
+        else
+          label_string = format_labels(labels)
+          "#{name}{#{label_string}} #{value}"
+        end
+      end
+
+      # Format labels for Prometheus
+      #
+      # @param labels [Hash] Labels hash
+      # @return [String] Formatted label string
+      def format_labels(labels)
+        labels.map do |key, value|
+          # Escape backslashes first, then quotes in label values
+          escaped_value = value.to_s.gsub('\\', '\\\\').gsub('"', '\\"')
+          "#{key}=\"#{escaped_value}\""
+        end.join(',')
+      end
+
+      # Generate help text for metrics
+      #
+      # @param name [String] Metric name
+      # @param type [Symbol] Metric type
+      # @return [String] Help text
+      def help_text_for(name, type)
+        case name
+        when /task.*total/
+          'Total number of tasks processed'
+        when /task.*duration/
+          'Task execution duration in seconds'
+        when /step.*total/
+          'Total number of steps executed'
+        when /step.*duration/
+          'Step execution duration in seconds'
+        when /workflow.*total/
+          'Total number of workflow orchestrations'
+        when /event.*total/
+          'Total number of events published'
+        when /error.*total/
+          'Total number of errors encountered'
+        when /queue.*size/
+          'Current queue size'
+        when /active.*connections/
+          'Number of active connections'
+        else
+          "Tasker #{type} metric: #{name}"
+        end
+      end
+
+      # Check if telemetry is enabled
+      #
+      # @return [Boolean] True if telemetry is enabled
+      def telemetry_enabled?
+        return false unless defined?(Tasker.configuration)
+
+        Tasker.configuration.telemetry.metrics_enabled
+      end
+
+      # Log export error with structured logging
+      #
+      # @param error [StandardError] The error that occurred
+      def log_export_error(error)
+        return unless defined?(Rails) && Rails.logger
+
+        Rails.logger.error({
+          message: 'Prometheus export failed',
+          error: error.message,
+          backtrace: error.backtrace&.first(5),
+          timestamp: Time.current.iso8601,
+          component: 'prometheus_exporter'
+        }.to_json)
+      end
+
+      # Export error metric when export fails
+      #
+      # @param error [StandardError] The error that occurred
+      # @return [String] Error metric in Prometheus format
+      def export_error_metric(error)
+        timestamp = Time.current.to_f
+        <<~PROMETHEUS
+          # Export error fallback metric
+          # TYPE tasker_metrics_export_errors_total counter
+          tasker_metrics_export_errors_total{error="#{error.class.name}"} 1 #{timestamp}
+        PROMETHEUS
+      end
+    end
+  end
+end