fluentd 0.12.40 → 0.14.0

data/lib/fluent/plugin/buf_file.rb

@@ -15,218 +15,137 @@
 #
 
 require 'fileutils'
-require 'uri'
 
-require 'fluent/env'
-require 'fluent/plugin'
-require 'fluent/buffer'
+require 'fluent/plugin/buffer'
+require 'fluent/plugin/buffer/file_chunk'
+require 'fluent/system_config'
 
 module Fluent
-  class FileBufferChunk < BufferChunk
-    def initialize(key, path, unique_id, mode="a+", symlink_path = nil)
-      super(key)
-      @path = path
-      @unique_id = unique_id
-      @file = File.open(@path, mode, DEFAULT_FILE_PERMISSION)
-      @file.sync = true
-      @size = @file.stat.size
-      FileUtils.ln_sf(@path, symlink_path) if symlink_path
-    end
-
-    attr_reader :unique_id, :path
-
-    def <<(data)
-      @file.write(data)
-      @size += data.bytesize
-    end
-
-    def size
-      @size
-    end
+  module Plugin
+    class FileBuffer < Fluent::Plugin::Buffer
+      Plugin.register_buffer('file', self)
 
-    def empty?
-      @size == 0
-    end
-
-    def close
-      stat = @file.stat
-      @file.close
-      if stat.size == 0
-        File.unlink(@path)
-      end
-    end
+      include SystemConfig::Mixin
 
-    def purge
-      @file.close
-      File.unlink(@path) rescue nil  # TODO rescue?
-    end
+      DEFAULT_CHUNK_LIMIT_SIZE = 256 * 1024 * 1024        # 256MB
+      DEFAULT_TOTAL_LIMIT_SIZE =  64 * 1024 * 1024 * 1024 #  64GB, same with v0.12 (TimeSlicedOutput + buf_file)
 
-    def read
-      @file.pos = 0
-      @file.read
-    end
+      DIR_PERMISSION = 0755
 
-    def open(&block)
-      @file.pos = 0
-      yield @file
-    end
+      # TODO: buffer_path based on system config
+      desc 'The path where buffer chunks are stored.'
+      config_param :path, :string
 
-    def mv(path)
-      File.rename(@path, path)
-      @path = path
-    end
-  end
+      config_set_default :chunk_limit_size, DEFAULT_CHUNK_LIMIT_SIZE
+      config_set_default :total_limit_size, DEFAULT_TOTAL_LIMIT_SIZE
 
-  class FileBuffer < BasicBuffer
-    Plugin.register_buffer('file', self)
+      config_param :file_permission, :string, default: nil # '0644'
+      config_param :dir_permission,  :string, default: nil # '0755'
 
-    @@buffer_paths = {}
+      ##TODO: Buffer plugin cannot handle symlinks because new API @stage has many writing buffer chunks
+      ##      re-implement this feature on out_file, w/ enqueue_chunk(or generate_chunk) hook + chunk.path
+      # attr_accessor :symlink_path
 
-    def initialize
-      require 'uri'
-      super
+      @@buffer_paths = {}
 
-      @uri_parser = URI::Parser.new
-    end
+      def initialize
+        super
+        @symlink_path = nil
+      end
 
-    desc 'The path where buffer chunks are stored.'
-    config_param :buffer_path, :string
-    desc 'If true, queued chunks are flushed at shutdown process.'
-    config_param :flush_at_shutdown, :bool, default: false
+      def configure(conf)
+        super
 
-    # 'symlink_path' is currently only for out_file.
-    # That is the reason why this is not config_param, but attr_accessor.
-    # See: https://github.com/fluent/fluentd/pull/181
-    attr_accessor :symlink_path
+        type_of_owner = Plugin.lookup_type_from_class(@_owner.class)
+        if @@buffer_paths.has_key?(@path) && !buffer_path_for_test?
+          type_using_this_path = @@buffer_paths[@path]
+          raise ConfigError, "Other '#{type_using_this_path}' plugin already use same buffer path: type = #{type_of_owner}, buffer path = #{@path}"
+        end
 
-    def configure(conf)
-      super
+        @@buffer_paths[@path] = type_of_owner
+
+        # TODO: create buffer path with plugin_id, under directory specified by system config
+        if File.exist?(@path)
+          if File.directory?(@path)
+            @path = File.join(@path, 'buffer.*.log')
+          elsif File.basename(@path).include?('.*.')
+            # valid path (buffer.*.log will be ignored)
+          elsif File.basename(@path).end_with?('.*')
+            @path = @path + '.log'
+          else
+            # existing file will be ignored
+            @path = @path + '.*.log'
+          end
+        else # path doesn't exist
+          if File.basename(@path).include?('.*.')
+            # valid path
+          elsif File.basename(@path).end_with?('.*')
+            @path = @path + '.log'
+          else
+            # path is handled as directory, and it will be created at #start
+            @path = File.join(@path, 'buffer.*.log')
+          end
+        end
 
-      if @@buffer_paths.has_key?(@buffer_path)
-        raise ConfigError, "Other '#{@@buffer_paths[@buffer_path]}' plugin already use same buffer_path: type = #{conf['@type'] || conf['type']}, buffer_path = #{@buffer_path}"
-      else
-        @@buffer_paths[@buffer_path] = conf['@type'] || conf['type']
+        unless @dir_permission
+          @dir_permission = system_config.dir_permission || DIR_PERMISSION
+        end
       end
 
-      if pos = @buffer_path.index('*')
-        @buffer_path_prefix = @buffer_path[0, pos]
-        @buffer_path_suffix = @buffer_path[(pos + 1)..-1]
-      else
-        @buffer_path_prefix = @buffer_path + "."
-        @buffer_path_suffix = ".log"
+      def buffer_path_for_test?
+        caller_locations.each do |location|
+          # Thread::Backtrace::Location#path returns base filename or absolute path.
+          # #absolute_path returns absolute_path always.
+          # https://bugs.ruby-lang.org/issues/12159
+          if location.absolute_path =~ /\/test_[^\/]+\.rb$/ # location.path =~ /test_.+\.rb$/
+            return true
+          end
+        end
+        false
       end
 
-    end
-
-    def start
-      FileUtils.mkdir_p File.dirname(@buffer_path_prefix + "path"), mode: DEFAULT_DIR_PERMISSION
-      super
-    end
+      def start
+        FileUtils.mkdir_p File.dirname(@path), mode: @dir_permission
 
-    # Dots are separator for many cases:
-    #   we should have to escape dots in keys...
-    PATH_MATCH = /^([-_.%0-9a-zA-Z]*)\.(b|q)([0-9a-fA-F]{1,32})$/
+        super
+      end
 
-    def new_chunk(key)
-      encoded_key = encode_key(key)
-      path, tsuffix = make_path(encoded_key, "b")
-      unique_id = tsuffix_to_unique_id(tsuffix)
-      FileBufferChunk.new(key, path, unique_id, "a+", @symlink_path)
-    end
+      def persistent?
+        true
+      end
 
-    def resume
-      maps = []
-      queues = []
-
-      Dir.glob("#{@buffer_path_prefix}*#{@buffer_path_suffix}") {|path|
-        identifier_part = chunk_identifier_in_path(path)
-        if m = PATH_MATCH.match(identifier_part)
-          key = decode_key(m[1])
-          bq = m[2]
-          tsuffix = m[3]
-          timestamp = m[3].to_i(16)
-          unique_id = tsuffix_to_unique_id(tsuffix)
-
-          if bq == 'b'
-            chunk = FileBufferChunk.new(key, path, unique_id, "a+")
-            maps << [timestamp, chunk]
-          elsif bq == 'q'
-            chunk = FileBufferChunk.new(key, path, unique_id, "r")
-            queues << [timestamp, chunk]
+      def resume
+        stage = {}
+        queue = []
+
+        Dir.glob(@path) do |path|
+          m = new_metadata() # this metadata will be overwritten by resuming .meta file content
+                             # so it should not added into @metadata_list for now
+          mode = Fluent::Plugin::Buffer::FileChunk.assume_chunk_state(path)
+          chunk = Fluent::Plugin::Buffer::FileChunk.new(m, path, mode) # file chunk resumes contents of metadata
+          case chunk.state
+          when :staged
+            stage[chunk.metadata] = chunk
+          when :queued
+            queue << chunk
+          else
+            raise "BUG: unexpected chunk state '#{chunk.state}' for path '#{path}'"
           end
         end
-      }
-
-      map = {}
-      maps.sort_by {|(timestamp,chunk)|
-        timestamp
-      }.each {|(timestamp,chunk)|
-        map[chunk.key] = chunk
-      }
-
-      queue = queues.sort_by {|(timestamp,chunk)|
-        timestamp
-      }.map {|(timestamp,chunk)|
-        chunk
-      }
-
-      return queue, map
-    end
-
-    def chunk_identifier_in_path(path)
-      pos_after_prefix = @buffer_path_prefix.length
-      pos_before_suffix = @buffer_path_suffix.length + 1 # from tail of path
-
-      path.slice(pos_after_prefix..-pos_before_suffix)
-    end
-
-    def enqueue(chunk)
-      path = chunk.path
-      identifier_part = chunk_identifier_in_path(path)
 
-      m = PATH_MATCH.match(identifier_part)
-      encoded_key = m ? m[1] : ""
-      tsuffix = m[3]
-      npath = "#{@buffer_path_prefix}#{encoded_key}.q#{tsuffix}#{@buffer_path_suffix}"
+        queue.sort_by!{ |chunk| chunk.modified_at }
 
-      chunk.mv(npath)
-    end
+        return stage, queue
+      end
 
-    def before_shutdown(out)
-      if @flush_at_shutdown
-        synchronize do
-          @map.each_key {|key|
-            push(key)
-          }
-          while pop(out)
-          end
+      def generate_chunk(metadata)
+        # FileChunk generates real path with unique_id
+        if @file_permission
+          Fluent::Plugin::Buffer::FileChunk.new(metadata, @path, :create, perm: @file_permission)
+        else
+          Fluent::Plugin::Buffer::FileChunk.new(metadata, @path, :create)
         end
       end
     end
-
-    private
-
-    # Dots are separator for many cases:
-    #   we should have to escape dots in keys...
-    def encode_key(key)
-      @uri_parser.escape(key, /[^-_.a-zA-Z0-9]/n) # //n switch means explicit 'ASCII-8BIT' pattern
-    end
-
-    def decode_key(encoded_key)
-      @uri_parser.unescape(encoded_key)
-    end
-
-    def make_path(encoded_key, bq)
-      now = Time.now.utc
-      timestamp = ((now.to_i * 1000 * 1000 + now.usec) << 12 | rand(0xfff))
-      tsuffix = timestamp.to_s(16)
-      path = "#{@buffer_path_prefix}#{encoded_key}.#{bq}#{tsuffix}#{@buffer_path_suffix}"
-      return path, tsuffix
-    end
-
-    def tsuffix_to_unique_id(tsuffix)
-      # why *2 ? frsyuki said that I forgot why completely.
-      tsuffix.scan(/../).map {|x| x.to_i(16) }.pack('C*') * 2
-    end
   end
 end

data/lib/fluent/plugin/buf_memory.rb

@@ -14,104 +14,21 @@
 #    limitations under the License.
 #
 
-require 'stringio'
-
-require 'fluent/engine'
-require 'fluent/plugin'
-require 'fluent/buffer'
+require 'fluent/plugin/buffer'
+require 'fluent/plugin/buffer/memory_chunk'
 
 module Fluent
-  class MemoryBufferChunk < BufferChunk
-    def initialize(key, data='')
-      @data = data
-      @data.force_encoding('ASCII-8BIT')
-      now = Time.now.utc
-      u1 = ((now.to_i*1000*1000+now.usec) << 12 | rand(0xfff))
-      @unique_id = [u1 >> 32, u1 & 0xffffffff, rand(0xffffffff), rand(0xffffffff)].pack('NNNN')
-      super(key)
-    end
-
-    attr_reader :unique_id
-
-    def <<(data)
-      data.force_encoding('ASCII-8BIT')
-      @data << data
-    end
-
-    def size
-      @data.bytesize
-    end
-
-    def close
-    end
-
-    def purge
-    end
-
-    def read
-      @data
-    end
-
-    def open(&block)
-      StringIO.open(@data, &block)
-    end
-
-    # optimize
-    def write_to(io)
-      io.write @data
-    end
+  module Plugin
+    class MemoryBuffer < Fluent::Plugin::Buffer
+      Plugin.register_buffer('memory', self)
 
-    # optimize
-    def msgpack_each(&block)
-      u = Fluent::Engine.msgpack_factory.unpacker
-      u.feed_each(@data, &block)
-    end
-  end
-
-
-  class MemoryBuffer < BasicBuffer
-    Plugin.register_buffer('memory', self)
-
-    def initialize
-      super
-    end
-
-    desc 'If true, queued chunks are flushed at shutdown process. Otherwise queued chunks are discarded'
-    config_param :flush_at_shutdown, :bool, default: true
-    # Overwrite default BasicBuffer#buffer_queue_limit
-    # to limit total memory usage upto 512MB.
-    config_set_default :buffer_queue_limit, 64
-
-    def configure(conf)
-      super
-
-      unless @flush_at_shutdown
-        $log.warn "When flush_at_shutdown is false, buf_memory discards buffered chunks at shutdown."
-        $log.warn "Please confirm 'flush_at_shutdown false' configuration is correct or not."
+      def resume
+        return {}, []
       end
-    end
 
-    def before_shutdown(out)
-      if @flush_at_shutdown
-        synchronize do
-          @map.each_key {|key|
-            push(key)
-          }
-          while pop(out)
-          end
-        end
+      def generate_chunk(metadata)
+        Fluent::Plugin::Buffer::MemoryChunk.new(metadata)
       end
     end
-
-    def new_chunk(key)
-      MemoryBufferChunk.new(key)
-    end
-
-    def resume
-      return [], {}
-    end
-
-    def enqueue(chunk)
-    end
   end
 end

data/lib/fluent/plugin/buffer.rb

@@ -0,0 +1,473 @@
+#
+# Fluentd
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+#
+
+require 'fluent/plugin/base'
+require 'fluent/plugin/owned_by_mixin'
+require 'fluent/unique_id'
+
+require 'monitor'
+
+module Fluent
+  module Plugin
+    class Buffer < Base
+      include OwnedByMixin
+      include UniqueId::Mixin
+      include MonitorMixin
+
+      class BufferError < StandardError; end
+      class BufferOverflowError < BufferError; end
+      class BufferChunkOverflowError < BufferError; end # A record size is larger than chunk size limit
+
+      MINIMUM_APPEND_ATTEMPT_RECORDS = 10
+
+      DEFAULT_CHUNK_LIMIT_SIZE =   8 * 1024 * 1024 # 8MB
+      DEFAULT_TOTAL_LIMIT_SIZE = 512 * 1024 * 1024 # 512MB, same with v0.12 (BufferedOutput + buf_memory: 64 x 8MB)
+
+      DEFAULT_CHUNK_FULL_THRESHOLD = 0.95
+
+      configured_in :buffer
+
+      # TODO: system total buffer limit size in bytes by SystemConfig
+
+      config_param :chunk_limit_size, :size, default: DEFAULT_CHUNK_LIMIT_SIZE
+      config_param :total_limit_size, :size, default: DEFAULT_TOTAL_LIMIT_SIZE
+
+      # If user specify this value and (chunk_size * queue_length) is smaller than total_size,
+      # then total_size is automatically configured to that value
+      config_param :queue_length_limit, :integer, default: nil
+
+      # optional new limitations
+      config_param :chunk_records_limit, :integer, default: nil
+
+      # if chunk size (or records) is 95% or more after #write, then that chunk will be enqueued
+      config_param :chunk_full_threshold, :float, default: DEFAULT_CHUNK_FULL_THRESHOLD
+
+      Metadata = Struct.new(:timekey, :tag, :variables)
+
+      # for tests
+      attr_accessor :stage_size, :queue_size
+      attr_reader :stage, :queue, :dequeued, :queued_num
+
+      def initialize
+        super
+
+        @chunk_limit_size = nil
+        @total_limit_size = nil
+        @queue_length_limit = nil
+        @chunk_records_limit = nil
+
+        @stage = {}    #=> Hash (metadata -> chunk) : not flushed yet
+        @queue = []    #=> Array (chunks)           : already flushed (not written)
+        @dequeued = {} #=> Hash (unique_id -> chunk): already written (not purged)
+        @queued_num = {} # metadata => int (number of queued chunks)
+
+        @stage_size = @queue_size = 0
+        @metadata_list = [] # keys of @stage
+      end
+
+      def persistent?
+        false
+      end
+
+      def configure(conf)
+        super
+
+        unless @queue_length_limit.nil?
+          @total_limit_size = @chunk_limit_size * @queue_length_limit
+        end
+      end
+
+      def start
+        super
+
+        @stage, @queue = resume
+        @stage.each_pair do |metadata, chunk|
+          @metadata_list << metadata unless @metadata_list.include?(metadata)
+          @stage_size += chunk.bytesize
+        end
+        @queue.each do |chunk|
+          @metadata_list << chunk.metadata unless @metadata_list.include?(chunk.metadata)
+          @queued_num[chunk.metadata] ||= 0
+          @queued_num[chunk.metadata] += 1
+          @queue_size += chunk.bytesize
+        end
+      end
+
+      def close
+        super
+        synchronize do
+          @dequeued.each_pair do |chunk_id, chunk|
+            chunk.close
+          end
+          until @queue.empty?
+            @queue.shift.close
+          end
+          @stage.each_pair do |metadata, chunk|
+            chunk.close
+          end
+        end
+      end
+
+      def terminate
+        super
+        @dequeued = @stage = @queue = @queued_num = @metadata_list = nil
+        @stage_size = @queue_size = 0
+      end
+
+      def storable?
+        @total_limit_size > @stage_size + @queue_size
+      end
+
+      ## TODO: for back pressure feature
+      # def used?(ratio)
+      #   @total_size_limit * ratio > @stage_size + @queue_size
+      # end
+
+      def resume
+        # return {}, []
+        raise NotImplementedError, "Implement this method in child class"
+      end
+
+      def generate_chunk(metadata)
+        raise NotImplementedError, "Implement this method in child class"
+      end
+
+      def metadata_list
+        synchronize do
+          @metadata_list.dup
+        end
+      end
+
+      def new_metadata(timekey: nil, tag: nil, variables: nil)
+        Metadata.new(timekey, tag, variables)
+      end
+
+      def add_metadata(metadata)
+        synchronize do
+          if i = @metadata_list.index(metadata)
+            @metadata_list[i]
+          else
+            @metadata_list << metadata
+            metadata
+          end
+        end
+      end
+
+      def metadata(timekey: nil, tag: nil, variables: nil)
+        meta = new_metadata(timekey: timekey, tag: tag, variables: variables)
+        add_metadata(meta)
+      end
+
+      # metadata MUST have consistent object_id for each variation
+      # data MUST be Array of serialized events
+      # metadata_and_data MUST be a hash of { metadata => data }
+      def write(metadata_and_data, bulk: false, enqueue: false)
+        return if metadata_and_data.size < 1
+        raise BufferOverflowError, "buffer space has too many data" unless storable?
+
+        staged_bytesize = 0
+        operated_chunks = []
+
+        begin
+          metadata_and_data.each do |metadata, data|
+            write_once(metadata, data, bulk: bulk) do |chunk, adding_bytesize|
+              chunk.mon_enter # add lock to prevent to be committed/rollbacked from other threads
+              operated_chunks << chunk
+              staged_bytesize += adding_bytesize
+            end
+          end
+
+          return if operated_chunks.empty?
+
+          first_chunk = operated_chunks.shift
+          # Following commits for other chunks also can finish successfully if the first commit operation
+          # finishes without any exceptions.
+          # In most cases, #commit just requires very small disk spaces, so major failure reason are
+          # permission errors, disk failures and other permanent(fatal) errors.
+          begin
+            first_chunk.commit
+            enqueue_chunk(first_chunk.metadata) if enqueue || chunk_size_full?(first_chunk)
+            first_chunk.mon_exit
+          rescue
+            operated_chunks.unshift(first_chunk)
+            raise
+          end
+
+          errors = []
+          # Buffer plugin estimates there's no serious error cause: will commit for all chunks eigher way
+          operated_chunks.each do |chunk|
+            begin
+              chunk.commit
+              enqueue_chunk(chunk.metadata) if enqueue || chunk_size_full?(chunk)
+              chunk.mon_exit
+            rescue => e
+              chunk.rollback
+              chunk.mon_exit
+              errors << e
+            end
+          end
+          operated_chunks.clear if errors.empty?
+
+          @stage_size += staged_bytesize
+
+          if errors.size > 0
+            log.warn "error occurs in committing chunks: only first one raised", errors: errors.map(&:class)
+            raise errors.first
+          end
+        ensure
+          operated_chunks.each do |chunk|
+            chunk.rollback rescue nil # nothing possible to do for #rollback failure
+            chunk.mon_exit rescue nil # this may raise ThreadError for chunks already committed
+          end
+        end
+      end
+
+      def queued_records
+        synchronize { @queue.reduce(0){|r, chunk| r + chunk.size } }
+      end
+
+      def queued?(metadata=nil)
+        synchronize do
+          if metadata
+            n = @queued_num[metadata]
+            n && n.nonzero?
+          else
+            !@queue.empty?
+          end
+        end
+      end
+
+      def enqueue_chunk(metadata)
+        synchronize do
+          chunk = @stage.delete(metadata)
+          return nil unless chunk
+
+          chunk.synchronize do
+            if chunk.empty?
+              chunk.close
+            else
+              @queue << chunk
+              @queued_num[metadata] = @queued_num.fetch(metadata, 0) + 1
+              chunk.enqueued! if chunk.respond_to?(:enqueued!)
+            end
+          end
+          bytesize = chunk.bytesize
+          @stage_size -= bytesize
+          @queue_size += bytesize
+        end
+        nil
+      end
+
+      def enqueue_all
+        synchronize do
+          if block_given?
+            @stage.keys.each do |metadata|
+              chunk = @stage[metadata]
+              v = yield metadata, chunk
+              enqueue_chunk(metadata) if v
+            end
+          else
+            @stage.keys.each do |metadata|
+              enqueue_chunk(metadata)
+            end
+          end
+        end
+      end
+
+      def dequeue_chunk
+        return nil if @queue.empty?
+        synchronize do
+          chunk = @queue.shift
+
+          # this buffer is dequeued by other thread just before "synchronize" in this thread
+          return nil unless chunk
+
+          @dequeued[chunk.unique_id] = chunk
+          @queued_num[chunk.metadata] -= 1 # BUG if nil, 0 or subzero
+          chunk
+        end
+      end
+
+      def takeback_chunk(chunk_id)
+        synchronize do
+          chunk = @dequeued.delete(chunk_id)
+          return false unless chunk # already purged by other thread
+          @queue.unshift(chunk)
+          @queued_num[chunk.metadata] += 1 # BUG if nil
+        end
+        true
+      end
+
+      def purge_chunk(chunk_id)
+        synchronize do
+          chunk = @dequeued.delete(chunk_id)
+          return nil unless chunk # purged by other threads
+
+          metadata = chunk.metadata
+          begin
+            bytesize = chunk.bytesize
+            chunk.purge
+            @queue_size -= bytesize
+          rescue => e
+            log.error "failed to purge buffer chunk", chunk_id: dump_unique_id_hex(chunk_id), error_class: e.class, error: e
+          end
+
+          if metadata && !@stage[metadata] && (!@queued_num[metadata] || @queued_num[metadata] < 1)
+            @metadata_list.delete(metadata)
+          end
+        end
+        nil
+      end
+
+      def clear_queue!
+        synchronize do
+          until @queue.empty?
+            begin
+              q = @queue.shift
+              log.debug("purging a chunk in queue"){ {id: dump_unique_id_hex(chunk.unique_id), bytesize: chunk.bytesize, size: chunk.size} }
+              q.purge
+            rescue => e
+              log.error "unexpected error while clearing buffer queue", error_class: e.class, error: e
+            end
+          end
+          @queue_size = 0
+        end
+      end
+
+      def chunk_size_over?(chunk)
+        chunk.bytesize > @chunk_limit_size || (@chunk_records_limit && chunk.size > @chunk_records_limit)
+      end
+
+      def chunk_size_full?(chunk)
+        chunk.bytesize >= @chunk_limit_size * @chunk_full_threshold || (@chunk_records_limit && chunk.size >= @chunk_records_limit * @chunk_full_threshold)
+      end
+
+      class ShouldRetry < StandardError; end
+
+      def write_once(metadata, data, bulk: false, &block)
+        return if !bulk && (data.nil? || data.empty?)
+        return if bulk && (data.empty? || data.first.nil? || data.first.empty?)
+
+        stored = false
+        adding_bytesize = nil
+
+        chunk = synchronize { @stage[metadata] ||= generate_chunk(metadata) }
+        enqueue_list = []
+
+        chunk.synchronize do
+          # retry this method if chunk is already queued (between getting chunk and entering critical section)
+          raise ShouldRetry unless chunk.staged?
+
+          empty_chunk = chunk.empty?
+
+          original_bytesize = chunk.bytesize
+          begin
+            if bulk
+              content, size = data
+              chunk.concat(content, size)
+            else
+              chunk.append(data)
+            end
+            adding_bytesize = chunk.bytesize - original_bytesize
+
+            if chunk_size_over?(chunk)
+              if empty_chunk && bulk
+                log.warn "chunk bytes limit exceeds for a bulk event stream: #{bulk.bytesize}bytes"
+                stored = true
+              else
+                chunk.rollback
+              end
+            else
+              stored = true
+            end
+          rescue
+            chunk.rollback
+            raise
+          end
+
+          if stored
+            block.call(chunk, adding_bytesize)
+          elsif bulk
+            # this metadata might be enqueued already by other threads
+            # but #enqueue_chunk does nothing in such case
+            enqueue_list << metadata
+            raise ShouldRetry
+          end
+        end
+
+        unless stored
+          # try step-by-step appending if data can't be stored into existing a chunk in non-bulk mode
+          write_step_by_step(metadata, data, data.size / 3, &block)
+        end
+      rescue ShouldRetry
+        enqueue_list.each do |metadata|
+          enqueue_chunk(metadata)
+        end
+        retry
+      end
+
+      def write_step_by_step(metadata, data, attempt_records, &block)
+        while data.size > 0
+          if attempt_records < MINIMUM_APPEND_ATTEMPT_RECORDS
+            attempt_records = MINIMUM_APPEND_ATTEMPT_RECORDS
+          end
+
+          chunk = synchronize{ @stage[metadata] ||= generate_chunk(metadata) }
+          chunk.synchronize do # critical section for chunk (chunk append/commit/rollback)
+            raise ShouldRetry unless chunk.staged?
+            begin
+              empty_chunk = chunk.empty?
+              original_bytesize = chunk.bytesize
+
+              attempt = data.slice(0, attempt_records)
+              chunk.append(attempt)
+              adding_bytesize = (chunk.bytesize - original_bytesize)
+
+              if chunk_size_over?(chunk)
+                chunk.rollback
+
+                if attempt_records <= MINIMUM_APPEND_ATTEMPT_RECORDS
+                  if empty_chunk # record is too large even for empty chunk
+                    raise BufferChunkOverflowError, "minimum append butch exceeds chunk bytes limit"
+                  end
+                  # no more records for this chunk -> enqueue -> to be flushed
+                  enqueue_chunk(metadata) # `chunk` will be removed from stage
+                  attempt_records = data.size # fresh chunk may have enough space
+                else
+                  # whole data can be processed by twice operation
+                  #  ( by using apttempt /= 2, 3 operations required for odd numbers of data)
+                  attempt_records = (attempt_records / 2) + 1
+                end
+
+                next
+              end
+
+              block.call(chunk, adding_bytesize)
+              data.slice!(0, attempt_records)
+              # same attempt size
+              nil # discard return value of data.slice!() immediately
+            rescue
+              chunk.rollback
+              raise
+            end
+          end
+        end
+      rescue ShouldRetry
+        retry
+      end # write_step_by_step
+    end
+  end
+end