steno-capi 1.3.4

data/README.md

@@ -0,0 +1,78 @@
+# Steno
+Steno is a lightweight, modular logging library written specifically to support
+Cloud Foundry.
+
+## Concepts
+
+Steno is composed of three main classes: loggers, sinks, and formatters. Loggers
+are the main entry point for Steno. They consume user input, create structured
+records, and forward said records to the configured sinks. Sinks are the
+ultimate destination for log records. They transform a structured record into
+a string via a formatter and then typically write the transformed string to
+another transport.
+
+## Configuration
+
+To use steno, you must configure one or more 'sinks', a 'codec' and a 'context'.
+If you don't provide a codec, steno will encode your logs as JSON.
+
+For example:
+
+    config = Steno::Config.new(
+      :sinks   => [Steno::Sink::IO.new(STDOUT)],
+      :codec   => Steno::Codec::Json.new,
+      :context => Steno::Context::ThreadLocal.new)
+
+### from YAML file
+
+Alternatively, Steno can read its configuration from a YAML file in the following format:
+
+```yaml
+# config.yml
+---
+logging:
+  file: /some/path            # Optional - path a log file
+  max_retries: 3              # Optional - number of times to retry if a file write fails.
+  syslog: some_syslog.id      # Optional - only works on *nix systems
+  eventlog: true              # Optional - only works on Windows
+  fluentd:                    # Optional
+    host: fluentd.host
+    port: 9999
+  level: debug                # Optional - Minimum log level that will be written.
+                              # Defaults to 'info'
+```
+Then, in your code:
+```ruby
+config = Steno::Config.from_file("path/to/config.yml")
+```
+
+With this configuration method, if neither `file`, `syslog` or `fluentd` are provided,
+steno will use its stdout as its sink. Also, note that the top-level field `logging` is required.
+
+### from Hash
+
+As a third option, steno can be configured using a hash with the same structure as the above
+YAML file (without the top-level `logging` key):
+```ruby
+config = Steno::Config.from_hash(config_hash)
+```
+
+## Usage
+
+    Steno.init(config)
+    logger = Steno.logger("test")  
+    logger.info("Hello world!")
+
+### Log levels
+
+    LEVEL	NUMERIC RANKING 
+    off		0
+    fatal	1
+    error	5
+    warn	10
+    info	15
+    debug	16
+    debug1	17
+    debug2	18
+    all		30
+

data/Rakefile

@@ -0,0 +1,15 @@
+#!/usr/bin/env rake
+require "rspec/core/rake_task"
+
+task :default => :spec
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new("spec") do |t|
+  t.rspec_opts = %w[--color --format documentation]
+end
+
+desc "Run all specs and provide output for ci"
+RSpec::Core::RakeTask.new("spec:ci" => "ci:setup:rspec") do |t|
+  t.rspec_opts = %w[--no-color --format documentation]
+end
+

data/bin/steno-prettify

@@ -0,0 +1,99 @@
+#!/usr/bin/env ruby
+
+require "optparse"
+require "yajl"
+
+require "steno/json_prettifier"
+
+Signal.trap("INT") { exit }
+
+def prettify_io(io, prettifier, ignore_parse_error = false)
+  lineno = 1
+  json_regex = '([^{]*)({.*})'
+
+  io.sync = true
+
+  io.each_line do |line|
+    begin
+      match_data = line.match(json_regex) || []
+      prefix = match_data[1]
+      json = match_data[2]
+
+      prettified = prettifier.prettify_line(json)
+      print prefix + prettified
+    rescue Steno::JsonPrettifier::ParseError => e
+      if ignore_parse_error
+        print line
+      else
+        STDERR.puts "steno-prettify: Malformed json at line #{lineno}, '#{line.strip}'"
+      end
+    end
+
+    lineno += 1
+  end
+end
+
+def prettify_file(path, prettifier, ignore_parse_error = false)
+  begin
+    f = File.open(path, "r")
+  rescue => e
+    STDERR.puts "steno-prettify: Failed opening '#{path}', #{e}"
+    return
+  end
+
+  prettify_io(f, prettifier, ignore_parse_error)
+
+ensure
+  f.close if f
+end
+
+excluded_fields = []
+ignore_parse_error = false
+
+option_parser = OptionParser.new do |op|
+  op.banner =<<EOT
+Usage: steno-prettify [OPTS] [FILE...]
+
+Parses json formatted log lines from FILE(s), or stdin,
+and displays a more human friendly version of each line to stdout.
+
+Examples (shamelessly stolen from `man cat`):
+
+  steno-prettify f - g
+    Prettify f's contents, then standard input, then g's contents.
+
+  steno-prettify
+    Prettify contents of stdin.
+
+Options:
+EOT
+
+  op.on("-h", "--help", "Display help") do
+    puts op
+    exit
+  end
+
+  op.on("-a", "--align", "Omit location and data in order to provide well-aligned logs") do
+    excluded_fields = %w[location data]
+  end
+
+  op.on("-s", "--no-messages", "Donot complain about errors in parsing logs") do
+    ignore_parse_error = true
+  end
+end
+
+option_parser.parse!(ARGV)
+
+STDOUT.sync = true
+prettifier = Steno::JsonPrettifier.new(excluded_fields)
+
+inputs = ARGV.dup
+inputs << "-" if inputs.empty?
+
+inputs.each do |path|
+  if path == "-"
+    prettify_io(STDIN, prettifier, ignore_parse_error)
+  else
+    prettify_file(path, prettifier, ignore_parse_error)
+  end
+end

data/lib/steno.rb

@@ -0,0 +1,133 @@
+require "thread"
+
+require "steno/codec"
+require "steno/config"
+require "steno/context"
+require "steno/errors"
+require "steno/log_level"
+require "steno/logger"
+require "steno/tagged_logger"
+require "steno/record"
+require "steno/sink"
+require "steno/version"
+
+module Steno
+  class << self
+
+    attr_reader :config
+    attr_reader :logger_regexp
+
+    # Initializes the logging system. This must be called exactly once before
+    # attempting to use any Steno class methods.
+    #
+    # @param [Steno::Config]
+    #
+    # @return [nil]
+    def init(config)
+      @config = config
+
+      @loggers = {}
+      @loggers_lock = Mutex.new
+
+      @logger_regexp = nil
+      @logger_regexp_level = nil
+
+      nil
+    end
+
+    # Returns (and memoizes) the logger identified by name.
+    #
+    # @param [String] name
+    #
+    # @return [Steno::Logger]
+    def logger(name)
+      @loggers_lock.synchronize do
+        logger = @loggers[name]
+
+        if logger.nil?
+          level = compute_level(name)
+
+          logger = Steno::Logger.new(name, @config.sinks,
+                                     :level => level,
+                                     :context => @config.context)
+
+          @loggers[name] = logger
+        end
+
+        logger
+      end
+    end
+
+    # Sets all loggers whose name matches _regexp_ to _level_. Resets any
+    # loggers whose name matches the previous regexp but not the supplied regexp.
+    #
+    # @param [Regexp] regexp
+    # @param [Symbol] level
+    #
+    # @return [nil]
+    def set_logger_regexp(regexp, level)
+      @loggers_lock.synchronize do
+        @loggers.each do |name, logger|
+          if name =~ regexp
+            logger.level = level
+          elsif @logger_regexp && (name =~ @logger_regexp)
+            # Reset loggers affected by the old regexp but not by the new
+            logger.level = @config.default_log_level
+          end
+        end
+
+        @logger_regexp = regexp
+        @logger_regexp_level = level
+
+        nil
+      end
+    end
+
+    # Clears the logger regexp, if set. Resets the level of any loggers matching
+    # the regex to the default log level.
+    #
+    # @return [nil]
+    def clear_logger_regexp
+      @loggers_lock.synchronize do
+        return if @logger_regexp.nil?
+
+        @loggers.each do |name, logger|
+          if name =~ @logger_regexp
+            logger.level = @config.default_log_level
+          end
+        end
+
+        @logger_regexp = nil
+        @logger_regexp_level = nil
+      end
+
+      nil
+    end
+
+
+    # @return [Hash] Map of logger name => level
+    def logger_level_snapshot
+      @loggers_lock.synchronize do
+        snapshot = {}
+
+        @loggers.each { |name, logger| snapshot[name] = logger.level }
+
+        snapshot
+      end
+    end
+
+    private
+
+    def compute_level(name)
+      if @logger_regexp && name =~ @logger_regexp
+        @logger_regexp_level
+      else
+        @config.default_log_level
+      end
+    end
+  end
+end
+
+# Initialize with an empty config. All log records will swallowed until Steno
+# is re-initialized with sinks.
+Steno.init(Steno::Config.new)

data/lib/steno/codec.rb

@@ -0,0 +1,2 @@
+require "steno/codec/base"
+require "steno/codec/json"

data/lib/steno/codec/base.rb

@@ -0,0 +1,34 @@
+module Steno
+  module Codec
+  end
+end
+
+class Steno::Codec::Base
+  # Encodes the supplied record as a string.
+  #
+  # @param [Hash] record
+  #
+  # @return [String]
+  def encode_record(record)
+    raise NotImplementedError
+  end
+
+  private
+
+  # Hex encodes non-printable ascii characters.
+  #
+  # @param [String] data
+  #
+  # @return [String]
+  def escape_nonprintable_ascii(data)
+    data.chars.map do |c|
+      ord_val = c.ord
+
+      if (ord_val > 31) && (ord_val < 127)
+        c
+      else
+        "\\x%02x" % [ord_val]
+      end
+    end.join
+  end
+end

data/lib/steno/codec/json.rb

@@ -0,0 +1,49 @@
+require "yajl"
+
+require "steno/codec/base"
+
+module Steno
+  module Codec
+  end
+end
+
+class Steno::Codec::Json < Steno::Codec::Base
+
+  def initialize(opts = {})
+    @iso8601_timestamps = opts[:iso8601_timestamps] || false
+  end
+
+  def encode_record(record)
+    msg =
+      if record.message.valid_encoding?
+        record.message
+      else
+        # Treat the message as an arbitrary sequence of bytes.
+        escape_nonprintable_ascii(record.message.dup.force_encoding("BINARY"))
+      end
+
+    h = {
+      "timestamp"  => record.timestamp.to_f,
+      "message"    => msg,
+      "log_level"  => record.log_level.to_s,
+      "source"     => record.source,
+      "data"       => record.data,
+      "thread_id"  => record.thread_id,
+      "fiber_id"   => record.fiber_id,
+      "process_id" => record.process_id,
+      "file"       => record.file,
+      "lineno"     => record.lineno,
+      "method"     => record.method,
+    }
+
+    if iso8601_timestamps?
+      h["timestamp"] = Time.at(record.timestamp).utc.iso8601(6)
+    end
+
+     Yajl::Encoder.encode(h) + "\n"
+  end
+
+  def iso8601_timestamps?
+    @iso8601_timestamps
+  end
+end

data/lib/steno/config.rb

@@ -0,0 +1,101 @@
+require "yaml"
+
+require "steno/codec"
+require "steno/context"
+require "steno/logger"
+require "steno/sink"
+
+module Steno
+end
+
+class Steno::Config
+  class << self
+    # Creates a config given a yaml file of the following form:
+    #
+    #     logging:
+    #       level:  <info, debug, etc>
+    #       file:   </path/to/logfile>
+    #       syslog: <syslog name>
+    #
+    # @param [String] path  Path to yaml config
+    # @param [Hash] overrides
+    #
+    # @return [Steno::Config]
+    def from_file(path, overrides = {})
+      h = YAML.load_file(path)
+      h = h["logging"] || {}
+      new(to_config_hash(h).merge(overrides))
+    end
+
+    def from_hash(hash)
+      new(to_config_hash(hash))
+    end
+
+    def to_config_hash(hash)
+      hash ||= {}
+      hash = symbolize_keys(hash)
+
+      level = hash[:level] || hash[:default_log_level]
+      opts = {
+        :sinks => [],
+        :default_log_level => level.nil? ? :info : level.to_sym
+      }
+
+      if hash[:iso8601_timestamps]
+        opts[:codec] = Steno::Codec::Json.new(:iso8601_timestamps => true)
+      end
+
+      if hash[:file]
+        max_retries = hash[:max_retries]
+        opts[:sinks] << Steno::Sink::IO.for_file(hash[:file], :max_retries => max_retries)
+      end
+
+      if Steno::Sink::WINDOWS
+        if hash[:eventlog]
+          Steno::Sink::Eventlog.instance.open(hash[:eventlog])
+          opts[:sinks] << Steno::Sink::Eventlog.instance
+        end
+      else
+        if hash[:syslog]
+          Steno::Sink::Syslog.instance.open(hash[:syslog])
+          opts[:sinks] << Steno::Sink::Syslog.instance
+        end
+      end
+
+      if hash[:fluentd]
+        opts[:sinks] << Steno::Sink::Fluentd.new(hash[:fluentd])
+      end
+
+      if opts[:sinks].empty?
+        opts[:sinks] << Steno::Sink::IO.new(STDOUT)
+      end
+
+      opts
+    end
+
+    def symbolize_keys(hash)
+      Hash[hash.each_pair.map { |k, v| [k.to_sym, v] }]
+    end
+  end
+
+  attr_reader :sinks
+  attr_reader :codec
+  attr_reader :context
+  attr_reader :default_log_level
+
+  def initialize(opts = {})
+    @sinks             = opts[:sinks] || []
+    @codec             = opts[:codec] || Steno::Codec::Json.new
+    @context           = opts[:context] ||Steno::Context::Null.new
+
+    @sinks.each { |sink| sink.codec = @codec }
+
+    if opts[:default_log_level]
+      @default_log_level = opts[:default_log_level].to_sym
+    else
+      @default_log_level = :info
+    end
+  end
+
+  private_class_method :symbolize_keys
+end