julewire-gcp 1.0.0

data/lib/julewire/gcp/formatter_options.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Julewire
+  module GCP
+    module FormatterOptions
+      ALLOWED_KEYS = %i[
+        label_formatter
+        label_options
+        max_label_key_bytes
+        max_label_value_bytes
+        max_labels
+        span_id_path
+        trace_id_path
+        trace_sampled_path
+      ].freeze
+
+      class << self
+        def validate!(options)
+          Core::Validation.validate_options!(options, ALLOWED_KEYS, name: :formatter)
+        end
+
+        def trace_headers_paths(paths)
+          Array(paths).filter_map { normalize_path(it, min_length: 1) }.freeze
+        end
+
+        def trace_value_path(path)
+          normalize_path(path, min_length: 2)
+        end
+
+        def label_formatter(options)
+          options[:label_formatter] || LabelFormatter.new(**label_options(options))
+        end
+
+        def label_options(options)
+          label_options = options.fetch(:label_options, {}).dup
+          %i[max_labels max_label_key_bytes max_label_value_bytes].each do |key|
+            label_options[key] = options[key] if options.key?(key)
+          end
+          label_options
+        end
+
+        private
+
+        def normalize_path(path, min_length:)
+          return if path.nil?
+
+          normalized = Array(path).map { normalize_path_segment(it) }
+          return if normalized.length < min_length
+
+          normalized.freeze
+        end
+
+        def normalize_path_segment(segment)
+          segment.is_a?(String) ? segment.to_sym : segment
+        end
+      end
+    end
+  end
+end

data/lib/julewire/gcp/http_request_fields.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Julewire
+  module GCP
+    module HttpRequestFields
+      class << self
+        def http_request(record, attributes)
+          values = Core::Integration::Values::Shape
+          request = {}
+          values.append_field(request, "requestMethod", attributes[Core::Fields::AttributeKeys::HTTP_REQUEST_METHOD])
+          values.append_field(
+            request,
+            "requestUrl",
+            attributes[Core::Fields::AttributeKeys::URL_FULL] || attributes[Core::Fields::AttributeKeys::URL_PATH]
+          )
+          values.append_field(request, "status", attributes[Core::Fields::AttributeKeys::HTTP_RESPONSE_STATUS_CODE])
+          values.append_field(request, "userAgent", attributes[Core::Fields::AttributeKeys::USER_AGENT_ORIGINAL])
+          values.append_field(request, "remoteIp", attributes[Core::Fields::AttributeKeys::CLIENT_ADDRESS])
+          values.append_field(
+            request,
+            "responseSize",
+            int64_string(attributes[Core::Fields::AttributeKeys::HTTP_RESPONSE_BODY_SIZE])
+          )
+          return if request.empty?
+
+          latency_value = latency(record)
+          request["latency"] = latency_value if latency_value
+          request
+        end
+
+        private
+
+        def latency(record)
+          duration_ms = record.fetch(:metrics)[:duration_ms]
+          seconds = Float(duration_ms) / 1000
+          "#{format("%.9f", seconds).sub(/0+\z/, "").delete_suffix(".")}s"
+        rescue ArgumentError, TypeError
+          nil
+        end
+
+        def int64_string(value)
+          Integer(value).to_s
+        rescue ArgumentError, TypeError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/julewire/gcp/label_formatter.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Julewire
+  module GCP
+    class LabelFormatter
+      def initialize(max_labels: GCP::DEFAULT_MAX_LABELS,
+                     max_label_key_bytes: GCP::DEFAULT_MAX_LABEL_KEY_BYTES,
+                     max_label_value_bytes: GCP::DEFAULT_MAX_LABEL_VALUE_BYTES)
+        @max_labels = validate_count_limit(max_labels, name: :max_labels)
+        @max_label_key_bytes = validate_byte_limit(max_label_key_bytes, name: :max_label_key_bytes)
+        @max_label_value_bytes = validate_byte_limit(max_label_value_bytes, name: :max_label_value_bytes)
+      end
+
+      def call(labels)
+        return if labels.empty?
+
+        labels.each_with_object({}) do |(key, value), result|
+          break result if @max_labels && result.size >= @max_labels
+
+          label_key = label_key(key)
+          next unless label_key
+
+          result[label_key] = bounded_label_string(value, @max_label_value_bytes)
+        end
+      end
+
+      private
+
+      def label_key(value)
+        key = label_string(value)
+        return key unless @max_label_key_bytes && key.bytesize > @max_label_key_bytes
+
+        nil
+      end
+
+      def bounded_label_string(value, max_bytes)
+        string = label_string(value)
+        return string unless max_bytes && string.bytesize > max_bytes
+
+        label_string(string.byteslice(0, max_bytes))
+      end
+
+      def label_string(value)
+        Core::Serialization::EncodingSanitizer.call(value.to_s)
+      end
+
+      def validate_count_limit(value, name:)
+        return if value.nil?
+
+        Core::Validation.validate_integer_limit!(value, name: name, positive: true)
+      end
+
+      def validate_byte_limit(value, name:)
+        Core::Validation.validate_byte_limit!(value, name: name)
+        value
+      end
+    end
+  end
+end

data/lib/julewire/gcp/log_decoder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Julewire
+  module GCP
+    module LogDecoder
+      RecordDecoder = Core::CLI::LogFormats::RecordDecoder
+      private_constant :RecordDecoder
+
+      JULEWIRE_SECTION_KEYS = {
+        execution: "execution",
+        context: "context",
+        metrics: "metrics"
+      }.freeze
+      PAYLOAD_SECTION_KEYS = {
+        attributes: "attributes",
+        labels: "logging.googleapis.com/labels",
+        payload: "payload"
+      }.freeze
+      private_constant :JULEWIRE_SECTION_KEYS, :PAYLOAD_SECTION_KEYS
+
+      class << self
+        def match?(payload)
+          payload[JULEWIRE_PAYLOAD_FIELD].is_a?(Hash)
+        end
+
+        def call(payload)
+          julewire = payload.fetch(JULEWIRE_PAYLOAD_FIELD)
+          record_base(payload, julewire).merge(
+            record_sections(payload, julewire),
+            error: RecordDecoder.error(julewire["error"])
+          )
+        end
+
+        private
+
+        def record_base(payload, julewire)
+          {
+            timestamp: payload["time"] || payload["timestamp"],
+            severity: Julewire::Core::Records::Severity.normalize(payload["severity"] || :info),
+            kind: RecordDecoder.kind(julewire["kind"] || :point),
+            event: julewire["event"],
+            message: payload["message"],
+            logger: julewire["logger"],
+            source: julewire["source"]
+          }
+        end
+
+        def record_sections(payload, julewire)
+          RecordDecoder.sections(payload) do |section, _source|
+            gcp_section_value(section, payload, julewire)
+          end
+        end
+
+        def gcp_section_value(section, payload, julewire)
+          if (key = JULEWIRE_SECTION_KEYS[section])
+            julewire[key]
+          elsif (key = PAYLOAD_SECTION_KEYS[section])
+            payload[key]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/gcp/log_encoder.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Julewire
+  module GCP
+    module LogEncoder
+      class << self
+        def call(record)
+          json_encoder.call(formatter.call(record))
+        end
+
+        private
+
+        def formatter = @formatter ||= Formatter.new
+
+        def json_encoder = @json_encoder ||= JsonEncoder.new
+      end
+    end
+  end
+end

data/lib/julewire/gcp/source_location.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Julewire
+  module GCP
+    module SourceLocation
+      BACKTRACE_PATTERN = /\A(?<file>.+?):(?<line>\d+)(?::in (?:[`'](?<quoted>.*)[`']|(?<plain>.*)))?\z/
+      private_constant :BACKTRACE_PATTERN
+
+      class << self
+        def call(options)
+          values = Core::Integration::Values::Shape
+          location = {}
+          values.append_field(location, "file", string_value(options[:file]))
+          values.append_field(location, "line", line_value(options[:line]))
+          values.append_field(location, "function", string_value(options[:function]))
+          location unless location.empty?
+        end
+
+        def from_error(error)
+          return unless error.is_a?(Hash)
+
+          Array(error[:backtrace]).each do |line|
+            location = from_backtrace_line(line)
+            return location if location
+          end
+          nil
+        end
+
+        def from_backtrace_line(line)
+          match = BACKTRACE_PATTERN.match(line.to_s)
+          return unless match
+
+          call(
+            file: match[:file],
+            line: match[:line],
+            function: match[:quoted] || match[:plain]
+          )
+        end
+
+        def string_value(value)
+          return if Core::Integration::Values::Read.blank?(value)
+
+          value.to_s
+        end
+
+        def line_value(value)
+          string = value.to_s
+          string if string.match?(/\A\d+\z/)
+        end
+      end
+    end
+  end
+end

data/lib/julewire/gcp/source_location_options.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Julewire
+  module GCP
+    module SourceLocationOptions
+      EMPTY_HASH = {}.freeze
+      private_constant :EMPTY_HASH
+
+      class << self
+        def call(record, neutral_attributes)
+          options = record.dig(:payload, :gcp, :source_location)
+          return options if options.is_a?(Hash)
+
+          from_neutral_attributes(neutral_attributes)
+        end
+
+        def from_neutral_attributes(neutral_attributes)
+          file = neutral_attributes[Core::Fields::AttributeKeys::CODE_FILE_PATH]
+          line = neutral_attributes[Core::Fields::AttributeKeys::CODE_LINE_NUMBER]
+          function = neutral_attributes[Core::Fields::AttributeKeys::CODE_FUNCTION_NAME]
+          return EMPTY_HASH if file.nil? && line.nil? && function.nil?
+
+          values = Core::Integration::Values::Shape
+          options = {}
+          values.append_field(options, :file, file)
+          values.append_field(options, :line, line)
+          values.append_field(options, :function, function)
+          options
+        end
+      end
+    end
+  end
+end

data/lib/julewire/gcp/stack_trace.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Julewire
+  module GCP
+    module StackTrace
+      class << self
+        def call(error)
+          return unless error.is_a?(Hash)
+
+          lines = lines(error)
+          lines.join("\n") unless lines.empty?
+        end
+
+        def remove_backtraces(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, item), copy|
+              next if key == :backtrace
+
+              copy[key] = remove_backtraces(item)
+            end
+          when Array
+            value.map { remove_backtraces(it) }
+          else
+            value
+          end
+        end
+
+        private
+
+        def lines(error)
+          backtrace = Array(error[:backtrace])
+          cause = error[:cause]
+          cause_lines = cause.is_a?(Hash) ? lines(cause) : []
+          return [] if backtrace.empty? && cause_lines.empty?
+
+          summary = Core::Records::DisplayMessage.error_summary(error)
+          [summary, *backtrace, *prefixed_cause_lines(cause_lines)].compact
+        end
+
+        def prefixed_cause_lines(lines)
+          lines.map.with_index { |line, index| index.zero? ? "Caused by: #{line}" : line }
+        end
+      end
+    end
+  end
+end

data/lib/julewire/gcp/trace_context/traceparent.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Julewire
+  module GCP
+    module TraceContext
+      module Traceparent
+        TRACEPARENT_PATTERN =
+          /\A[[:xdigit:]]{2}-[[:xdigit:]]{32}-[[:xdigit:]]{16}-[[:xdigit:]]{2}(?:-.*)?\z/
+        MIN_BYTES = 55
+        TRACE_ID_OFFSET = 3
+        TRACE_ID_BYTES = 32
+        SPAN_ID_OFFSET = 36
+        SPAN_ID_BYTES = 16
+        TRACE_FLAGS_OFFSET = 53
+        private_constant :TRACEPARENT_PATTERN,
+                         :MIN_BYTES,
+                         :TRACE_ID_OFFSET,
+                         :TRACE_ID_BYTES,
+                         :SPAN_ID_OFFSET,
+                         :SPAN_ID_BYTES,
+                         :TRACE_FLAGS_OFFSET
+
+        class << self
+          def call(value)
+            value = value.to_s.scrub.strip
+            return unless TRACEPARENT_PATTERN.match?(value)
+
+            parse_value(value)
+          end
+
+          private
+
+          def parse_value(value)
+            version = value.byteslice(0, 2).downcase
+            return if version == "ff"
+            return if version == "00" && value.byteslice(MIN_BYTES)
+
+            trace_id = value.byteslice(TRACE_ID_OFFSET, TRACE_ID_BYTES)
+            span_id = value.byteslice(SPAN_ID_OFFSET, SPAN_ID_BYTES)
+            trace_id.downcase!
+            span_id.downcase!
+            return if Hex.zero?(trace_id) || Hex.zero?(span_id)
+
+            context(trace_id, span_id, trace_flags(value).allbits?(1))
+          end
+
+          def context(trace_id, span_id, sampled)
+            {
+              trace_id: trace_id,
+              span_id: span_id,
+              trace_sampled: sampled
+            }
+          end
+
+          def trace_flags(value)
+            Integer(value.byteslice(TRACE_FLAGS_OFFSET, 2), 16)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/gcp/trace_context.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Julewire
+  module GCP
+    module TraceContext
+      X_CLOUD_TRACE_PATTERN = %r{\A([[:xdigit:]]{32})(?:/(\d+))?(?:;o=(\d+))?\z}
+      TRACEPARENT_HEADER = "traceparent"
+      X_CLOUD_TRACE_CONTEXT_HEADER = "x-cloud-trace-context"
+      X_CLOUD_TRACE_CONTEXT_UNDERSCORE_HEADER = "x_cloud_trace_context"
+      MAX_SPAN_ID = (2**64) - 1
+      DIRECT_HEADER_KEYS = {
+        traceparent: [:traceparent, TRACEPARENT_HEADER],
+        x_cloud_trace_context: [
+          :x_cloud_trace_context,
+          X_CLOUD_TRACE_CONTEXT_UNDERSCORE_HEADER,
+          X_CLOUD_TRACE_CONTEXT_HEADER
+        ]
+      }.freeze
+      CANONICAL_HEADER_NAMES = {
+        traceparent: TRACEPARENT_HEADER,
+        x_cloud_trace_context: X_CLOUD_TRACE_CONTEXT_HEADER
+      }.freeze
+      private_constant :DIRECT_HEADER_KEYS, :CANONICAL_HEADER_NAMES
+
+      module Hex
+        class << self
+          def zero?(value)
+            offset = 0
+            while offset < value.bytesize
+              return false unless value.getbyte(offset) == 48
+
+              offset += 1
+            end
+            true
+          end
+        end
+      end
+      private_constant :Hex
+
+      class << self
+        def extract(headers)
+          return {} unless headers.respond_to?(:[])
+
+          parse_traceparent(fetch_header(headers, :traceparent)) ||
+            parse_x_cloud_trace_context(fetch_header(headers, :x_cloud_trace_context)) ||
+            {}
+        end
+
+        def parse_traceparent(value)
+          Traceparent.call(value)
+        end
+
+        def parse_x_cloud_trace_context(value)
+          match = X_CLOUD_TRACE_PATTERN.match(value.to_s.scrub.strip)
+          return unless match
+
+          trace_id = match[1].downcase
+          return if Hex.zero?(trace_id)
+
+          context = { trace_id: trace_id }
+          if match[2]
+            span_id = decimal_span_to_hex(match[2])
+            context[:span_id] = span_id if span_id
+          end
+          context[:trace_sampled] = Integer(match[3], 10).allbits?(1) if match[3]
+          context
+        end
+
+        private
+
+        def fetch_header(headers, key)
+          DIRECT_HEADER_KEYS.fetch(key).each do |header_key|
+            value = headers[header_key]
+            return value unless value.nil?
+          end
+          return unless headers.respond_to?(:each)
+
+          canonical_name = CANONICAL_HEADER_NAMES.fetch(key)
+          headers.each do |name, value|
+            return value if normalize_header_name(name) == canonical_name
+          end
+          nil
+        end
+
+        def normalize_header_name(name)
+          normalized = name.to_s.dup
+          normalized.tr!("_", "-")
+          normalized.downcase!
+          normalized
+        end
+
+        def decimal_span_to_hex(value)
+          integer = Integer(value, 10)
+          return if integer > MAX_SPAN_ID
+
+          span_id = integer.to_s(16).rjust(16, "0")
+          return if Hex.zero?(span_id)
+
+          span_id
+        end
+      end
+    end
+  end
+end

data/lib/julewire/gcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Julewire
+  module GCP
+    VERSION = "1.0.0"
+  end
+end

data/lib/julewire/gcp.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "julewire/core"
+
+module Julewire
+  module GCP
+    CARRY_REQUEST_HEADERS = %w[
+      traceparent
+      tracestate
+      x-cloud-trace-context
+    ].freeze
+    RECOMMENDED_MAX_RECORD_BYTES = 256 * 1024
+    DEFAULT_MAX_RECORD_BYTES = RECOMMENDED_MAX_RECORD_BYTES
+    DEFAULT_MAX_LABELS = 64
+    DEFAULT_MAX_LABEL_KEY_BYTES = 512
+    DEFAULT_MAX_LABEL_VALUE_BYTES = 64 * 1024
+    JULEWIRE_PAYLOAD_FIELD = "julewire"
+
+    class << self
+      def operation(id: nil, producer: nil, first: nil, last: nil)
+        values = Core::Integration::Values::Shape
+        operation = {}
+        values.append_field(operation, :id, id)
+        values.append_field(operation, :producer, producer)
+        values.append_field(operation, :first, first)
+        values.append_field(operation, :last, last)
+        {
+          gcp: {
+            operation: operation
+          }
+        }
+      end
+
+      def source_location(file: nil, line: nil, function: nil)
+        values = Core::Integration::Values::Shape
+        source_location = {}
+        values.append_field(source_location, :file, file)
+        values.append_field(source_location, :line, line)
+        values.append_field(source_location, :function, function)
+        {
+          gcp: {
+            source_location: source_location
+          }
+        }
+      end
+    end
+  end
+
+  loader = Zeitwerk::Loader.for_gem_extension(self)
+  loader.inflector.inflect("gcp" => "GCP")
+  loader.setup
+  Core::Destinations.register(:gcp) { |name:, **options| GCP::Destination.new(name: name, **options) }
+  Core::CLI::LogFormats.register(:gcp, decoder: GCP::LogDecoder, encoder: GCP::LogEncoder, priority: 100)
+end

data/lib/julewire-gcp.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "julewire/gcp"