logstash-output-scalyr 0.1.2 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef843ec2b97b5a4f7f1f3005500cdc7e89bcf32a3a7766eb1528f866d4a9c7ee
-  data.tar.gz: ebdd84bc5c603ec0eaaf54467a4dff9cfe94badcaa2f32c172067eeadab8b759
+  metadata.gz: 9a0be59b3c2ecaeb444f9fb76e6c97129ab9e1eeaa4a907976e4f6e62a44a582
+  data.tar.gz: 4ddecf13bd1b7800d6d5bad0a271014257159aedfb7eb332ebc8f1c1dd0dd3c5
 SHA512:
-  metadata.gz: 2803a5befd9d127b23c0fa2a17aa0333d7e4616d6c2976584018b1244bab7d9e55ba205ebb65bfc701dd2fe500c4d0ad549f7d4fd2783b410b99c647827b9c53
-  data.tar.gz: cc745e6249def709126df87c5333469fe44ebbf6c1f6919c804ed1e424f72087c4bd8bc3ca64dfad69f0e2595c14a799dd659ccb4a2dd0b66ce5fc6a81fa7117
+  metadata.gz: 8ed321b57270cf4bc6fbbc3375f516d08df0592d0476fa71d15af40a7afc1ddb4a97634678b65735101f3c4a17422c0d73e3f40524db06444f8c99cfd3f3a375
+  data.tar.gz: 818943ede0fcad23642366f465c63134500cd70fea625d52313dcc628b3bde3f19aecc6739766690f7d5985c9188af78b5c32e63bcfc4e9a1ca60ee0ceac8743

data/CHANGELOG.md

@@ -1,4 +1,12 @@
 # Beta
+## 0.1.7
+ - Tracking of new statistics such as `multi_receive` method duration and batch sizes.
+ - Addition of percentiles for both existing and new stats.
+ - Add ability to define a parser name for status messages using the `status_parser` configuration option.
+
+## 0.1.6
+ - Allow for a customer delimiter when flattening values using the `flatten_nested_values_delimiter` configuration option
+
 ## 0.1.2
  - Remove special treatment of `origin` field in favor of `serverHost`
  - Change concurrency type to `single` to help guarantee one-time ordered delivery in Scalyr

data/Gemfile

@@ -12,3 +12,4 @@ end
 
 gem 'pry'
 gem 'pry-nav'
+gem 'quantile'

data/README.md

@@ -1,16 +1,16 @@
 
 [![CircleCI](https://circleci.com/gh/scalyr/logstash-output-scalyr.svg?style=svg)](https://circleci.com/gh/scalyr/logstash-output-scalyr)
 
-# [Scalyr output plugin for Logstash (Alpha release)]
+# [Scalyr output plugin for Logstash (Beta release)]
 
 This plugin implements a Logstash output plugin that uploads data to [Scalyr](http://www.scalyr.com).
 
-You can view documentation for this plugin [on the Scalyr website](https://www.scalyr.com/solutions/logstash).
+You can view documentation for this plugin [on the Scalyr website](https://app.scalyr.com/solutions/logstash).
 
 # Quick start
 
 1. Build the gem, run `gem build logstash-output-scalyr.gemspec` 
-2. Install the gem into a Logstash installation, run `/usr/share/logstash/bin/logstash-plugin install logstash-output-scalyr-0.1.2.gem` or follow the latest official instructions on working with plugins from Logstash.
+2. Install the gem into a Logstash installation, run `/usr/share/logstash/bin/logstash-plugin install logstash-output-scalyr-0.1.7.gem` or follow the latest official instructions on working with plugins from Logstash.
 3. Configure the output plugin (e.g. add it to a pipeline .conf)
 4. Restart Logstash 
 
@@ -48,7 +48,7 @@ In the above example, the Logstash pipeline defines a file input that reads from
 
 ---
 
-- If your Scalyr backend is located in other geographies (such as Europe which would use `https://agent.eu.scalyr.com/`), you may need to modify this
+- If you have an EU-based Scalyr account, please use https://eu.scalyr.com/
 
 `config :scalyr_server, :validate => :string, :default => "https://agent.scalyr.com/"`
 
@@ -56,7 +56,7 @@ In the above example, the Logstash pipeline defines a file input that reads from
 
 - Path to SSL bundle file.
 
-`config :ssl_ca_bundle_path, :validate => :string, :default =>  "/etc/ssl/certs/ca-bundle.crt"`
+`config :ssl_ca_bundle_path, :validate => :string, :default => nil`
 
 ---
 
@@ -115,6 +115,12 @@ In the above example, the Logstash pipeline defines a file input that reads from
 
 ---
 
+- If set, this will change the delimiter used when concatenating nested keys
+
+`config :flatten_nested_values_delimiter, :validate => :string, :default => "_"`
+
+---
+
 - If true, the 'tags' field will be flattened into key-values where each key is a tag and each value is set to
  :flat_tag_value
 
@@ -152,7 +158,6 @@ In the above example, the Logstash pipeline defines a file input that reads from
 
 # Conceptual Overview
 
-
 ## Persistence
 
 Logstash itself supports [Persistent Queues](https://www.elastic.co/guide/en/logstash/current/persistent-queues.html) with at-least-once delivery semantics.  It expects output plugins to retry uploads until success or else to write failures into a Dead-Letter Queue (DLQ). Since Logstash offers Persistent Queues, the Scalyr plugin does not perform its own buffering or persistence.  More specifically, invocation of `multi_receive` is synchronously retried until success or written to the DLQ upon failure.  Note: the `multi_receive` interface does not provide a feedback mechanism (outcome codes etc).
@@ -301,7 +306,42 @@ This repo has been configured to run a full-cycle smoketest on CircleCI as follo
 This repo has unit tests that can be run by running:
 
 ```
-bundle exec rspec
+sudo bundle exec rspec
 ```
 
 in the root of the repo.
+
+By default this will run all the tests (including integration ones which require sudo access and
+may not pass everywhere).
+
+If you want to run just the unit tests, you can run the command displayed below.
+
+
+```bash
+bundle exec rspec spec/logstash/outputs/scalyr_spec.rb spec/scalyr/common/util_spec.rb
+```
+
+# Releasing
+
+## Updating version
+
+Currently references to the version need to be manually updated, files to look in for this are `logstash-putput-scalyr.gemspec`,
+ `client.rb`, twice in the CircleCI `Dockerfile`, and under "Quick Start" in this `README.md`.
+
+The changelog should also be updated with the latest version and changes of note.
+
+## Releasing to RubyGems.org
+
+To deploy the current code on your machine run these commands:
+
+```
+bundle check --path vendor/bundle || bundle install --deployment
+curl -u RUBY_USER:RUBY_PASSWORD https://rubygems.org/api/v1/api_key.yaml > ~/.gem/credentials
+chmod 0600 ~/.gem/credentials
+bundle exec rake vendor
+bundle exec rspec
+bundle exec rake publish_gem
+```
+
+`RUBY_USER` and `RUBY_PASSWORD` should be replaced with the username and password to the RubyGems.org account you wish to release to,
+ these credentials should be found in Keeper.

data/lib/logstash/outputs/scalyr.rb

@@ -14,6 +14,7 @@ require 'net/https'
 require 'rbzip2'
 require 'zlib'
 require 'stringio'
+require 'quantile'
 
 require 'scalyr/common/client'
 require "scalyr/common/util"
@@ -33,11 +34,14 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
   # The Scalyr API write token, these are available at https://www.scalyr.com/keys.  This is the only compulsory configuration field required for proper upload
   config :api_write_token, :validate => :string, :required => true
 
-  # If your Scalyr backend is located in other geographies (such as Europe which would use `https://agent.eu.scalyr.com/`), you may need to modify this
+  # If you have an EU-based Scalyr account, please use https://eu.scalyr.com/
   config :scalyr_server, :validate => :string, :default => "https://agent.scalyr.com/"
 
   # Path to SSL bundle file.
-  config :ssl_ca_bundle_path, :validate => :string, :default =>  "/etc/ssl/certs/ca-bundle.crt"
+  config :ssl_ca_bundle_path, :validate => :string, :default => "/etc/ssl/certs/ca-bundle.crt"
+
+  # If we should append our built-in Scalyr cert to the one we find at `ssl_ca_bundle_path`.
+  config :append_builtin_cert, :validate => :boolean, :default => true
 
   # server_attributes is a dictionary of key value pairs that represents/identifies the logstash aggregator server
   # (where this plugin is running).  Keys are arbitrary except for the 'serverHost' key which holds special meaning to
@@ -73,6 +77,7 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
   # If true, nested values will be flattened (which changes keys to delimiter-separated concatenation of all
   # nested keys).
   config :flatten_nested_values, :validate => :boolean, :default => false
+  config :flatten_nested_values_delimiter, :validate => :string, :default => "_" 
 
   # If true, the 'tags' field will be flattened into key-values where each key is a tag and each value is set to
   # :flat_tag_value
@@ -100,6 +105,20 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
   # An int containing the compression level of compression to use, from 1-9. Defaults to 6
   config :compression_level, :validate => :number, :default => 6
 
+  # How often to log and report status metrics to Scalyr. Defaults to every 5
+  # minutes.
+  config :status_report_interval, :validate => :number, :default => 300
+
+  # Whether or not to count status event uploads in the statistics such as request latency etc.
+  config :record_stats_for_status, :validate => :boolean, :default => false
+
+  # Parser to attach to status events
+  config :status_parser, :validate => :string, :default => "logstash_plugin_metrics"
+
+  # Whether or not to create fresh quantile estimators after a status send. Depending on what you want to gather from
+  # these stas this might be wanted or not.
+  config :flush_quantile_estimates_on_status_send, :validate => :boolean, :default => false
+
   def close
     @running = false
     @client_session.close if @client_session
@@ -107,6 +126,7 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
 
   public
   def register
+    @node_hostname = Socket.gethostname
 
     if @log_constants and not @log_constants.all? { |x| x.is_a? String }
       raise LogStash::ConfigurationError, "All elements of 'log_constants' must be strings."
@@ -154,7 +174,7 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
       # Note: Use strings rather than symbols for the key, because keys coming
       # from the config file will be strings
       unless @server_attributes.key? 'serverHost'
-        @server_attributes['serverHost'] = Socket.gethostname
+        @server_attributes['serverHost'] = @node_hostname
       end
     end
 
@@ -171,13 +191,20 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
     @last_status_transmit_time_lock = Mutex.new
     @last_status_transmit_time = nil
     @last_status_ = false
+    
+    # Per-multi-receive statistics
+    @multi_receive_statistics = {
+      :total_multi_receive_secs => 0
+    }
+    @multi_receive_metrics = get_new_multi_receive_metrics
 
     # create a client session for uploading to Scalyr
     @running = true
     @client_session = Scalyr::Common::Client::ClientSession.new(
         @logger, @add_events_uri,
         @compression_type, @compression_level,
-        @ssl_verify_peer, @ssl_ca_bundle_path, @ssl_verify_depth
+        @ssl_verify_peer, @ssl_ca_bundle_path, @ssl_verify_depth,
+        @append_builtin_cert, @record_stats_for_status, @flush_quantile_estimates_on_status_send
     )
 
     @logger.info("Started Scalyr output plugin", :class => self.class.name)
@@ -187,6 +214,13 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
 
   end # def register
 
+  # Convenience method to create a fresh quantile estimator
+  def get_new_multi_receive_metrics
+    return {
+      :multi_receive_duration_secs => Quantile::Estimator.new,
+      :multi_receive_event_count => Quantile::Estimator.new
+    }
+  end
 
   # Receive an array of events and immediately upload them (without buffering).
   # The Logstash framework will call this plugin method whenever there is a list of events to upload to Scalyr.
@@ -200,6 +234,7 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
   #
   public
   def multi_receive(events)
+    start_time = Time.now.to_f
 
     multi_event_request_array = build_multi_event_request_array(events)
     # Loop over all array of multi-event requests, sending each multi-event to Scalyr
@@ -209,18 +244,24 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
     total_batches = multi_event_request_array.length unless multi_event_request_array.nil?
 
     result = []
+    records_count = events.to_a.length
+
     while !multi_event_request_array.to_a.empty?
       begin
         multi_event_request = multi_event_request_array.pop
-        @client_session.post_add_events(multi_event_request[:body])
-        sleep_interval = 0
-        result.push(multi_event_request)
+        # For some reason a retry on the multi_receive may result in the request array containing `nil` elements, we
+        # ignore these.
+        if !multi_event_request.nil?
+          @client_session.post_add_events(multi_event_request[:body], false, multi_event_request[:serialization_duration], multi_event_request[:flatten_nested_values_duration])
+          sleep_interval = 0
+          result.push(multi_event_request)
+        end
 
       rescue OpenSSL::SSL::SSLError => e
         # cannot rely on exception message, so we always log the following warning
-        @logger.error "SSL certificate verification failed.  "
-        "Please make sure your certificate bundle is configured correctly and points to a valid file.  "
-        "You can configure this with the ssl_ca_bundle_path configuration option.  "
+        @logger.error "SSL certificate verification failed.  " +
+        "Please make sure your certificate bundle is configured correctly and points to a valid file.  " +
+        "You can configure this with the ssl_ca_bundle_path configuration option.  " +
         "The current value of ssl_ca_bundle_path is '#{@ssl_ca_bundle_path}'"
         @logger.error e.message
         @logger.error "Discarding buffer chunk without retrying."
@@ -229,7 +270,7 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
         sleep_interval = sleep_for(sleep_interval)
         message = "Error uploading to Scalyr (will backoff-retry)"
         exc_data = {
-            :url => e.url.sanitized.to_s,
+            :url => e.url.to_s,
             :message => e.message,
             :batch_num => batch_num,
             :total_batches => total_batches,
@@ -247,7 +288,7 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
           # all other failed uploads should be errors
           @logger.error(message, exc_data)
         end
-        retry if @running.true?
+        retry if @running
 
       rescue => e
         # Any unexpected errors should be fully logged
@@ -259,10 +300,16 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
         )
         @logger.debug("Failed multi_event_request", :multi_event_request => multi_event_request)
         sleep_interval = sleep_for(sleep_interval)
-        retry if @running.true?
+        retry if @running
       end
     end
 
+    if records_count > 0
+      @multi_receive_statistics[:total_multi_receive_secs] += (Time.now.to_f - start_time)
+      @multi_receive_metrics[:multi_receive_duration_secs].observe(Time.now.to_f - start_time)
+      @multi_receive_metrics[:multi_receive_event_count].observe(records_count)
+    end
+
     send_status
     return result
   end  # def multi_receive
@@ -286,6 +333,9 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
   # Tags are either propagated as a comma-separated string, or optionally transposed into key-values where the keys
   # are tag names and the values are 1 (may be configured.)
   def build_multi_event_request_array(logstash_events)
+    if logstash_events.nil? or logstash_events.empty?
+     return []
+    end
 
     multi_event_request_array = Array.new
     total_bytes = 0
@@ -302,6 +352,8 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
     logs_ids = Hash.new
     next_log_id = 1
 
+    flatten_nested_values_duration = 0
+
     logstash_events.each {|l_event|
 
       record = l_event.to_hash
@@ -328,8 +380,8 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
         if standard_field != renamed_field
           if record.key? renamed_field
             if record.key? standard_field
-              @logger.warn "Overwriting log record field '#{standard_field}'.  You are seeing this warning because in "
-              "your LogStash config file you have configured the '#{renamed_field}' field to be converted to the "
+              @logger.warn "Overwriting log record field '#{standard_field}'.  You are seeing this warning because in " +
+              "your LogStash config file you have configured the '#{renamed_field}' field to be converted to the " +
               "'#{standard_field}' field, but the event already contains a field called '#{standard_field}' and "
               "this is now being overwritten."
             end
@@ -353,16 +405,25 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
 
       # Rename user-specified serverHost field -> 'serverHost'
       rename.call(@serverhost_field, 'serverHost')
-      record.delete(@serverhost_field)
 
       # Rename user-specified logfile field -> 'logfile'
       rename.call(@logfile_field, 'logfile')
-      record.delete(@logfile_field)
+
+      # Set a default parser is none is present in the event
+      if record['parser'].to_s.empty?
+        record['parser'] = "logstashParser"
+      end
+
       # Set logfile field if empty and serverHost is supplied
       if record['logfile'].to_s.empty? and serverHost
         record['logfile'] = "/logstash/#{serverHost}"
       end
 
+      # Set a default if no serverHost value is present.
+      if serverHost.nil?
+        record['serverHost'] = "Logstash"
+      end
+
       log_identifier = nil
       add_log = false
       if serverHost
@@ -407,7 +468,14 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
       end
 
       # flatten record
-      record = Scalyr::Common::Util.flatten(record) if @flatten_nested_values
+      flatten_nested_values_duration = 0
+
+      if @flatten_nested_values
+        start_time = Time.now.to_f
+        record = Scalyr::Common::Util.flatten(record, delimiter=@flatten_nested_values_delimiter) if @flatten_nested_values
+        end_time = Time.now.to_f
+        flatten_nested_values_duration = end_time - start_time
+      end
 
       # Use LogStash event.timestamp as the 'ts' Scalyr timestamp.  Note that this may be overwritten by input
       # filters so may not necessarily reflect the actual originating timestamp.
@@ -458,7 +526,7 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
           scalyr_events << scalyr_event
           append_event = false
         end
-        multi_event_request = self.create_multi_event_request(scalyr_events, current_threads, logs)
+        multi_event_request = self.create_multi_event_request(scalyr_events, current_threads, logs, flatten_nested_values_duration)
         multi_event_request_array << multi_event_request
 
         total_bytes = 0
@@ -478,7 +546,7 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
     }
 
     # create a final request with any left over events
-    multi_event_request = self.create_multi_event_request(scalyr_events, current_threads, logs)
+    multi_event_request = self.create_multi_event_request(scalyr_events, current_threads, logs, flatten_nested_values_duration)
     multi_event_request_array << multi_event_request
     multi_event_request_array
   end
@@ -498,7 +566,7 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
   # A request comprises multiple Scalyr Events.  This function creates a request hash for
   # final upload to Scalyr (from an array of events, and an optional hash of current threads)
   # Note: The request body field will be json-encoded.
-  def create_multi_event_request(scalyr_events, current_threads, current_logs)
+  def create_multi_event_request(scalyr_events, current_threads, current_logs, flatten_nested_values_duration = 0)
 
     body = {
       :session => @session_id,
@@ -529,12 +597,35 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
     # add serverAttributes
     body[:sessionInfo] = @server_attributes if @server_attributes
 
-    { :body => body.to_json, :record_count => scalyr_events.size }
+    # We time serialization to get some insight on how long it takes to serialize the request body
+    start_time = Time.now.to_f
+    serialized_body = body.to_json
+    end_time = Time.now.to_f
+    serialization_duration = end_time - start_time
+    { :body => serialized_body, :record_count => scalyr_events.size, :serialization_duration => serialization_duration,
+      :flatten_nested_values_duration => flatten_nested_values_duration }
 
   end  # def create_multi_event_request
 
 
 
+  def get_batch_stats
+    current_stats = @multi_receive_statistics.clone
+
+    current_stats[:multi_receive_duration_p50] = @multi_receive_metrics[:multi_receive_duration_secs].query(0.5)
+    current_stats[:multi_receive_duration_p90] = @multi_receive_metrics[:multi_receive_duration_secs].query(0.9)
+    current_stats[:multi_receive_duration_p99] = @multi_receive_metrics[:multi_receive_duration_secs].query(0.99)
+    current_stats[:multi_receive_event_count_p50] = @multi_receive_metrics[:multi_receive_event_count].query(0.5)
+    current_stats[:multi_receive_event_count_p90] = @multi_receive_metrics[:multi_receive_event_count].query(0.9)
+    current_stats[:multi_receive_event_count_p99] = @multi_receive_metrics[:multi_receive_event_count].query(0.99)
+
+    if @flush_quantile_estimates_on_status_send
+      @multi_receive_metrics = get_new_multi_receive_metrics
+    end
+    current_stats
+  end
+
+
 
   # Sends a status update to Scalyr by posting a log entry under the special logfile of 'logstash_plugin.log'
   # Instead of creating a separate thread, let this method be invoked once at startup and then every 5 minutes
@@ -554,23 +645,35 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
 
     if !@last_status_transmit_time
       status_event[:attrs]['message'] = "Started Scalyr LogStash output plugin."
+      status_event[:attrs]['serverHost'] = @node_hostname
     else
       cur_time = Time.now()
-      return if (cur_time.to_i - @last_status_transmit_time.to_i) < 300
+      return if (cur_time.to_i - @last_status_transmit_time.to_i) < @status_report_interval
       # echee TODO: get instance stats from session and create a status log line
       msg = 'plugin_status: '
       cnt = 0
       @client_session.get_stats.each do |k, v|
-        val = v.instance_of?(Float) ? sprintf("%.1f", v) : v
+        val = v.instance_of?(Float) ? sprintf("%.3f", v) : v
+        val = val.nil? ? 0 : val
+        msg << ', ' if cnt > 0
+        msg << "#{k.to_s}=#{val}"
+        cnt += 1
+      end
+      get_batch_stats.each do |k, v|
+        val = v.instance_of?(Float) ? sprintf("%.3f", v) : v
+        val = val.nil? ? 0 : val
         msg << ', ' if cnt > 0
         msg << "#{k.to_s}=#{val}"
         cnt += 1
       end
       status_event[:attrs]['message'] = msg
+      status_event[:attrs]['serverHost'] = @node_hostname
+      status_event[:attrs]['parser'] = @status_parser
     end
-    multi_event_request = create_multi_event_request([status_event], nil, nil)
-    @client_session.post_add_events(multi_event_request[:body])
+    multi_event_request = create_multi_event_request([status_event], nil, nil, nil)
+    @client_session.post_add_events(multi_event_request[:body], true, 0, 0)
     @last_status_transmit_time = Time.now()
+    status_event
   end
 
 
@@ -579,19 +682,17 @@ class LogStash::Outputs::Scalyr < LogStash::Outputs::Base
   def should_transmit_status?
     @last_status_transmit_time_lock.synchronize do
       saved_last_time = @last_status_transmit_time
-      if Time.now.to_i - saved_last_time.to_i > 300
+      if Time.now.to_i - saved_last_time.to_i > @status_report_interval
         @last_status_transmit_time = Float::INFINITY
         return saved_last_time
       end
-    ensure
-
     end
   end
 
 
   # Helper method that performs synchronous sleep for a certain time interval
   def sleep_for(sleep_interval)
-    Stud.stoppable_sleep(sleep_interval) { @running.false? }
+    Stud.stoppable_sleep(sleep_interval) { !@running }
     get_sleep_sec(sleep_interval)
   end