opentelemetry-logs-sdk 0.1.0

data/lib/opentelemetry/sdk/logs/export/log_record_exporter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      module Export
+        # LogRecordExporter describes a duck type. It is not required to
+        # subclass this class to provide an implementation of LogRecordExporter,
+        # provided the interface is satisfied. LogRecordExporter allows
+        # different tracing services to export log record data in their own format.
+        #
+        # To export data an exporter MUST be registered to the {LoggerProvider}
+        # using a {LogRecordProcessor} implementation.
+        class LogRecordExporter
+          def initialize
+            @stopped = false
+          end
+
+          # Called to export {LogRecordData}s.
+          #
+          # @param [Enumerable<LogRecordData>] log_record_data the list of
+          # {LogRecordData} to be exported.
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          #
+          # @return [Integer] the result of the export.
+          def export(log_record_data, timeout: nil)
+            return SUCCESS unless @stopped
+
+            FAILURE
+          end
+
+          # Called when {LoggerProvider#force_flush} is called, if this exporter is
+          # registered to a {LoggerProvider} object.
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
+          def force_flush(timeout: nil)
+            SUCCESS
+          end
+
+          # Called when {LoggerProvider#shutdown} is called, if this exporter is
+          # registered to a {LoggerProvider} object.
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          def shutdown(timeout: nil)
+            @stopped = true
+            SUCCESS
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/logs/export/simple_log_record_processor.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      module Export
+        # An implementation of {LogRecordProcessor} that converts the LogRecord
+        # into a ReadableLogRecord and passes it to the configured exporter
+        # on emit.
+        #
+        # Typically, the SimpleLogRecordProcessor will be most suitable for use
+        # in testing; it should be used with caution in production. It may be
+        # appropriate for production use in scenarios where creating multiple
+        # threads is not desirable as well as scenarios where different custom
+        # attributes should be added to individual log records based on code
+        # scopes.
+        class SimpleLogRecordProcessor < OpenTelemetry::SDK::Logs::LogRecordProcessor
+          # Returns a new {SimpleLogRecordProcessor} that converts log records
+          # to {ReadableLogRecords} and forwards them to the given
+          # log_record_exporter.
+          #
+          # @param log_record_exporter the LogRecordExporter to push the
+          #   recorded log records.
+          # @return [SimpleLogRecordProcessor]
+          # @raise ArgumentError if the log_record_exporter is invalid or nil.
+          def initialize(log_record_exporter)
+            raise ArgumentError, "exporter #{log_record_exporter.inspect} does not appear to be a valid exporter" unless Common::Utilities.valid_exporter?(log_record_exporter)
+
+            @log_record_exporter = log_record_exporter
+            @stopped = false
+          end
+
+          # Called when a LogRecord is emitted.
+          #
+          # This method is called synchronously on the execution thread. It
+          # should not throw or block the execution thread. It may not be called
+          # after shutdown.
+          #
+          # @param [LogRecord] log_record The emitted {LogRecord}
+          # @param [Context] _context The current {Context}
+          def on_emit(log_record, _context)
+            return if @stopped
+
+            @log_record_exporter&.export([log_record.to_log_record_data])
+          rescue => e # rubocop:disable Style/RescueStandardError
+            OpenTelemetry.handle_error(exception: e, message: 'Unexpected error in Logger#on_emit')
+          end
+
+          # Export all log records to the configured `Exporter` that have not
+          # yet been exported, then call {Exporter#force_flush}.
+          #
+          # This method should only be called in cases where it is absolutely
+          # necessary, such as when using some FaaS providers that may suspend
+          # the process after an invocation, but before the `Processor` exports
+          # the completed log records.
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
+          # TODO: Should a rescue/handle error be added here for non-specific failures?
+          def force_flush(timeout: nil)
+            return if @stopped
+
+            @log_record_exporter&.force_flush(timeout: timeout) || SUCCESS
+          end
+
+          # Called when {LoggerProvider#shutdown} is called.
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
+          # TODO: Should a rescue/handle error be added here for non-specific failures?
+          def shutdown(timeout: nil)
+            return if @stopped
+
+            @log_record_exporter&.shutdown(timeout: timeout) || SUCCESS
+          ensure
+            @stopped = true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/logs/export.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      # The Export module contains the built-in exporters and log record
+      # processors for the OpenTelemetry reference implementation.
+      module Export
+        ExportError = Class.new(OpenTelemetry::Error)
+        # The operation finished successfully.
+        SUCCESS = 0
+
+        # The operation finished with an error.
+        FAILURE = 1
+
+        # The operation timed out.
+        TIMEOUT = 2
+      end
+    end
+  end
+end
+
+require_relative 'export/console_log_record_exporter'
+require_relative 'export/in_memory_log_record_exporter'
+require_relative 'export/log_record_exporter'
+require_relative 'export/simple_log_record_processor'
+require_relative 'export/batch_log_record_processor'

data/lib/opentelemetry/sdk/logs/log_record.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      # Implementation of OpenTelemetry::Logs::LogRecord that records log events.
+      class LogRecord < OpenTelemetry::Logs::LogRecord
+        EMPTY_ATTRIBUTES = {}.freeze
+
+        private_constant :EMPTY_ATTRIBUTES
+
+        attr_accessor :timestamp,
+                      :observed_timestamp,
+                      :severity_text,
+                      :severity_number,
+                      :body,
+                      :attributes,
+                      :trace_id,
+                      :span_id,
+                      :trace_flags,
+                      :resource,
+                      :instrumentation_scope
+
+        # Creates a new {LogRecord}.
+        #
+        # @param [optional Time] timestamp Time when the event occurred.
+        # @param [optional Time] observed_timestamp Time when the event
+        #   was observed by the collection system. If nil, will first attempt
+        #   to set to `timestamp`. If `timestamp` is nil, will set to Time.now.
+        # @param [optional OpenTelemetry::Trace::SpanContext] span_context The
+        #   OpenTelemetry::Trace::SpanContext to associate with the LogRecord.
+        # @param [optional String] severity_text The log severity, also known as
+        #   log level.
+        # @param [optional Integer] severity_number The numerical value of the
+        #   log severity.
+        # @param [optional String, Numeric, Boolean, Array<String, Numeric,
+        #   Boolean>, Hash{String => String, Numeric, Boolean, Array<String,
+        #   Numeric, Boolean>}] body The body of the {LogRecord}.
+        # @param [optional Hash{String => String, Numeric, Boolean,
+        #   Array<String, Numeric, Boolean>}] attributes Attributes to associate
+        #   with the {LogRecord}.
+        # @param [optional String] trace_id The trace ID associated with the
+        #   current context.
+        # @param [optional String] span_id The span ID associated with the
+        #   current context.
+        # @param [optional OpenTelemetry::Trace::TraceFlags] trace_flags The
+        #   trace flags associated with the current context.
+        # @param [optional OpenTelemetry::SDK::Resources::Resource] resource The
+        #   source of the log, desrived from the LoggerProvider.
+        # @param [optional OpenTelemetry::SDK::InstrumentationScope] instrumentation_scope
+        #   The instrumentation scope, derived from the emitting Logger
+        # @param [optional] OpenTelemetry::SDK::LogRecordLimits] log_record_limits
+        #   Attribute limits
+        #
+        #
+        # @return [LogRecord]
+        def initialize(
+          timestamp: nil,
+          observed_timestamp: nil,
+          severity_text: nil,
+          severity_number: nil,
+          body: nil,
+          attributes: nil,
+          trace_id: nil,
+          span_id: nil,
+          trace_flags: nil,
+          resource: nil,
+          instrumentation_scope: nil,
+          log_record_limits: nil
+        )
+          @timestamp = timestamp
+          @observed_timestamp = observed_timestamp || timestamp || Time.now
+          @severity_text = severity_text
+          @severity_number = severity_number
+          @body = body
+          @attributes = attributes.nil? ? nil : Hash[attributes] # We need a mutable copy of attributes
+          @trace_id = trace_id
+          @span_id = span_id
+          @trace_flags = trace_flags
+          @resource = resource
+          @instrumentation_scope = instrumentation_scope
+          @log_record_limits = log_record_limits || LogRecordLimits::DEFAULT
+          @total_recorded_attributes = @attributes&.size || 0
+
+          trim_attributes(@attributes)
+        end
+
+        def to_log_record_data
+          LogRecordData.new(
+            to_integer_nanoseconds(@timestamp),
+            to_integer_nanoseconds(@observed_timestamp),
+            @severity_text,
+            @severity_number,
+            @body,
+            @attributes,
+            @trace_id,
+            @span_id,
+            @trace_flags,
+            @resource,
+            @instrumentation_scope,
+            @total_recorded_attributes
+          )
+        end
+
+        private
+
+        def to_integer_nanoseconds(timestamp)
+          return unless timestamp.is_a?(Time)
+
+          (timestamp.to_r * 10**9).to_i
+        end
+
+        def trim_attributes(attributes)
+          return if attributes.nil?
+
+          # truncate total attributes
+          truncate_attributes(attributes, @log_record_limits.attribute_count_limit)
+
+          # truncate attribute values
+          truncate_attribute_values(attributes, @log_record_limits.attribute_length_limit)
+
+          # validate attributes
+          validate_attributes(attributes)
+
+          nil
+        end
+
+        def truncate_attributes(attributes, attribute_limit)
+          excess = attributes.size - attribute_limit
+          excess.times { attributes.shift } if excess.positive?
+        end
+
+        def validate_attributes(attrs)
+          # Similar to Internal.valid_attributes?, but with different messages
+          # Future refactor opportunity: https://github.com/open-telemetry/opentelemetry-ruby/issues/1739
+          attrs.keep_if do |k, v|
+            if !Internal.valid_key?(k)
+              OpenTelemetry.handle_error(message: "invalid log record attribute key type #{k.class} on record: '#{body}'")
+              return false
+            elsif !Internal.valid_value?(v)
+              OpenTelemetry.handle_error(message: "invalid log record attribute value type #{v.class} for key '#{k}' on record: '#{body}'")
+              return false
+            end
+
+            true
+          end
+        end
+
+        def truncate_attribute_values(attributes, attribute_length_limit)
+          return EMPTY_ATTRIBUTES if attributes.nil?
+          return attributes if attribute_length_limit.nil?
+
+          attributes.transform_values! { |value| OpenTelemetry::Common::Utilities.truncate_attribute_value(value, attribute_length_limit) }
+
+          attributes
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/logs/log_record_data.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      # LogRecordData is a Struct containing {LogRecord} data for export.
+      LogRecordData = Struct.new(:timestamp,                 # optional Integer nanoseconds since Epoch
+                                 :observed_timestamp,        # Integer nanoseconds since Epoch
+                                 :severity_text,             # optional String
+                                 :severity_number,           # optional Integer
+                                 :body,                      # optional String, Numeric, Boolean, Array<String, Numeric, Boolean>, Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}
+                                 :attributes,                # optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}
+                                 :trace_id,                  # optional String (16-byte binary)
+                                 :span_id,                   # optional String (8-byte binary)
+                                 :trace_flags,               # optional Integer (8-bit byte of bit flags)
+                                 :resource,                  # optional OpenTelemetry::SDK::Resources::Resource
+                                 :instrumentation_scope,     # optional OpenTelemetry::SDK::InstrumentationScope
+                                 :total_recorded_attributes) # Integer
+    end
+  end
+end

data/lib/opentelemetry/sdk/logs/log_record_limits.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      # Class that holds log record attribute limit parameters.
+      class LogRecordLimits
+        # The global default max number of attributes per {LogRecord}.
+        attr_reader :attribute_count_limit
+
+        # The global default max length of attribute value per {LogRecord}.
+        attr_reader :attribute_length_limit
+
+        # Returns a {LogRecordLimits} with the desired values.
+        #
+        # @return [LogRecordLimits] with the desired values.
+        # @raise [ArgumentError] if any of the max numbers are not positive.
+        def initialize(attribute_count_limit: Integer(OpenTelemetry::Common::Utilities.config_opt(
+                                                        'OTEL_LOG_RECORD_ATTRIBUTE_COUNT_LIMIT',
+                                                        'OTEL_ATTRIBUTE_COUNT_LIMIT',
+                                                        default: 128
+                                                      )),
+                       attribute_length_limit: OpenTelemetry::Common::Utilities.config_opt(
+                         'OTEL_LOG_RECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT',
+                         'OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT'
+                       ))
+          raise ArgumentError, 'attribute_count_limit must be positive' unless attribute_count_limit.positive?
+          raise ArgumentError, 'attribute_length_limit must not be less than 32' unless attribute_length_limit.nil? || Integer(attribute_length_limit) >= 32
+
+          @attribute_count_limit = attribute_count_limit
+          @attribute_length_limit = attribute_length_limit.nil? ? nil : Integer(attribute_length_limit)
+        end
+
+        # The default {LogRecordLimits}.
+        DEFAULT = new
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/logs/log_record_processor.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      # LogRecordProcessor describes a duck type and provides a synchronous no-op hook for when a
+      # {LogRecord} is emitted. It is not required to subclass this
+      # class to provide an implementation of LogRecordProcessor, provided the interface is
+      # satisfied.
+      class LogRecordProcessor
+        # Called when a {LogRecord} is emitted. Subsequent calls are not
+        # permitted after shutdown is called.
+        # @param [LogRecord] log_record The emitted {LogRecord}
+        # @param [Context] context The {Context}
+        def on_emit(log_record, context); end
+
+        # Export all log records to the configured `Exporter` that have not yet
+        # been exported.
+        #
+        # This method should only be called in cases where it is absolutely
+        # necessary, such as when using some FaaS providers that may suspend
+        # the process after an invocation, but before the `Processor` exports
+        # the completed spans.
+        #
+        # @param [optional Numeric] timeout An optional timeout in seconds.
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def force_flush(timeout: nil)
+          Export::SUCCESS
+        end
+
+        # Called when {LoggerProvider#shutdown} is called.
+        #
+        # @param [optional Numeric] timeout An optional timeout in seconds.
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def shutdown(timeout: nil)
+          Export::SUCCESS
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/logs/logger.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      # The SDK implementation of OpenTelemetry::Logs::Logger
+      class Logger < OpenTelemetry::Logs::Logger
+        # @api private
+        #
+        # Returns a new {OpenTelemetry::SDK::Logs::Logger} instance. This should
+        # not be called directly. New loggers should be created using
+        # {LoggerProvider#logger}.
+        #
+        # @param [String] name Instrumentation package name
+        # @param [String] version Instrumentation package version
+        # @param [LoggerProvider] logger_provider The {LoggerProvider} that
+        #   initialized the logger
+        #
+        # @return [OpenTelemetry::SDK::Logs::Logger]
+        def initialize(name, version, logger_provider)
+          @instrumentation_scope = InstrumentationScope.new(name, version)
+          @logger_provider = logger_provider
+        end
+
+        # Emit a {LogRecord} to the processing pipeline.
+        #
+        # @param [optional Time] timestamp Time when the event occurred.
+        # @param [optional Time] observed_timestamp Time when the event was
+        #   observed by the collection system.
+        # @param [optional OpenTelemetry::Trace::SpanContext] span_context The
+        #   OpenTelemetry::Trace::SpanContext to associate with the
+        #   {LogRecord}.
+        # @param [optional String] severity_text Original string representation of
+        #   the severity as it is known at the source. Also known as log level.
+        # @param severity_number [optional Integer] Numerical value of the
+        #   severity. Smaller numerical values correspond to less severe events
+        #   (such as debug events), larger numerical values correspond to more
+        #   severe events (such as errors and critical events).
+        # @param [optional String, Numeric, Boolean, Array<String, Numeric,
+        #   Boolean>, Hash{String => String, Numeric, Boolean, Array<String,
+        #   Numeric, Boolean>}] body A value containing the body of the log record.
+        # @param [optional Hash{String => String, Numeric, Boolean,
+        #   Array<String, Numeric, Boolean>}] attributes Additional information
+        #   about the event.
+        # @param [optional String (16-byte binary)] trace_id Request trace id as
+        #   defined in {https://www.w3.org/TR/trace-context/#trace-id W3C Trace Context}.
+        #   Can be set for logs that are part of request processing and have an
+        #   assigned trace id.
+        # @param [optional String (8-byte binary)] span_id Span id. Can be set
+        #   for logs that are part of a particular processing span. If span_id
+        #   is present trace_id should also be present.
+        # @param [optional Integer (8-bit byte of bit flags)] trace_flags Trace
+        #   flag as defined in {https://www.w3.org/TR/trace-context/#trace-flags W3C Trace Context}
+        #   specification. At the time of writing the specification defines one
+        #   flag - the SAMPLED flag.
+        # @param [optional OpenTelemetry::Context] context The OpenTelemetry::Context
+        #   to associate with the {LogRecord}.
+        #
+        # @api public
+        def on_emit(timestamp: nil,
+                    observed_timestamp: Time.now,
+                    severity_text: nil,
+                    severity_number: nil,
+                    body: nil,
+                    attributes: nil,
+                    trace_id: nil,
+                    span_id: nil,
+                    trace_flags: nil,
+                    context: OpenTelemetry::Context.current)
+          current_span = OpenTelemetry::Trace.current_span(context)
+          span_context = current_span.context unless current_span == OpenTelemetry::Trace::Span::INVALID
+
+          @logger_provider.on_emit(timestamp: timestamp,
+                                   observed_timestamp: observed_timestamp,
+                                   severity_text: severity_text,
+                                   severity_number: severity_number,
+                                   body: body,
+                                   attributes: attributes,
+                                   trace_id: trace_id || span_context&.trace_id,
+                                   span_id: span_id || span_context&.span_id,
+                                   trace_flags: trace_flags || span_context&.trace_flags,
+                                   instrumentation_scope: @instrumentation_scope,
+                                   context: context)
+        end
+      end
+    end
+  end
+end