semantic_logger 4.18.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98c3a3e01f125e81eb58559ca0f7931c55bb787102d89d0c10dd9c9a7ea2e221
-  data.tar.gz: 8d82c20b77fe2c98773b72ab2483bdfb2d1267c65f9b8102cb2ffba00c141ee9
+  metadata.gz: f18701015c0b556099814aff1b79e251df13f556c103a8366b58357d9d10fd8c
+  data.tar.gz: cf18f050902946ac09a065a52a6f4cee9841f5c250ef30162d39347977e071d2
 SHA512:
-  metadata.gz: c014af737549553d82d1d65ac1f46fbb09cefae9cb5aca3d5c39a4bbc180587fea4a65fa6756cad87eb031af52806693ddf11b9c2a4564bb140b1b1261b216c7
-  data.tar.gz: f0c050cb59d1a3022fbf2b5ca180b644493c8630103e09498e7a9097bbda97df3cb3a28b84f125331196819123cad128f85a142c7952918d9df376acfd1dff69
+  metadata.gz: f62d59fc517122f6da01702c62cf5a33e47d629605f0dd5e096f953ebdcd7d3e6dbb9bf2e25d166d32f171dbe16ba1470726ebe760343e6e04994cef7b5c6dcd
+  data.tar.gz: 3c741614f72b723e50ed3e3ec2a785de85eb6a026b9ed52d67bb064c1617814d77afeb67e5f8f7f4cb6f20f339affd14f54a82ffe23194e256ba66da9e8aedf0

data/README.md

@@ -1,13 +1,50 @@
 # Semantic Logger
 [![Gem Version](https://img.shields.io/gem/v/semantic_logger.svg)](https://rubygems.org/gems/semantic_logger) [![Build Status](https://github.com/reidmorrison/semantic_logger/workflows/build/badge.svg)](https://github.com/reidmorrison/semantic_logger/actions?query=workflow%3Abuild) [![Downloads](https://img.shields.io/gem/dt/semantic_logger.svg)](https://rubygems.org/gems/semantic_logger) [![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg)](http://opensource.org/licenses/Apache-2.0) ![](https://img.shields.io/badge/status-Production%20Ready-blue.svg)
 
-Semantic Logger is a feature rich logging framework, and replacement for existing Ruby & Rails loggers.
+Semantic Logger is a high-performance, asynchronous structured logging framework for Ruby
+and Rails.
 
-* https://logger.rocketjob.io/
+It differs from ordinary loggers in two important ways:
+
+1. **It logs structured data, not just strings.** Along with the text message, each log entry can
+   carry a payload (any Hash), an exception, a duration, metrics, and tags. That data is preserved
+   all the way to the destination, so it stays searchable instead of being flattened into text.
+2. **It logs asynchronously.** Log events are pushed onto an in-memory queue and written to their
+   destinations by a separate background thread, so your application is not blocked while logs are
+   written. Semantic Logger can log thousands of lines per second without slowing the application
+   down.
+
+```ruby
+require "semantic_logger"
+
+SemanticLogger.default_level = :info
+SemanticLogger.add_appender(io: $stdout, formatter: :color)
+
+logger = SemanticLogger["MyApp"]
+
+# A plain message, plus structured data that stays searchable
+logger.info("Queried users table", duration: 54, result: :ok, table: "users")
+
+# Log an exception with its full backtrace, plus context
+logger.error("Failed to process order", exception: exception, order_id: 42)
+
+# Measure and log how long a block takes to run
+logger.measure_info("Reindexing users") { reindex_users }
+```
+
+When running Rails, use
+[rails_semantic_logger](https://github.com/reidmorrison/rails_semantic_logger) instead, since it
+replaces the Rails default logger with Semantic Logger automatically.
 
 ## Documentation
 
-[Semantic Logger Guide](https://logger.rocketjob.io/)
+Start with the [Introduction](https://logger.rocketjob.io/), then the
+[Programmer's Guide](https://logger.rocketjob.io/api.html).
+
+* Full guide: [https://logger.rocketjob.io/](https://logger.rocketjob.io/)
+* For AI assistants: [llms.txt](https://logger.rocketjob.io/llms.txt) (documentation index) and
+  [llms-full.txt](https://logger.rocketjob.io/llms-full.txt) (complete documentation in one file).
+  The same pages are also included as markdown in the installed gem, under `docs/`.
 
 ## Logging Destinations
 
@@ -28,6 +65,7 @@ Logging to the following destinations are all supported "out-of-the-box":
 * UDP
 * Syslog
 * CloudWatch Logs
+* OpenTelemetry
 * Add any existing Ruby logger as another destination.
 * Roll-your-own
 
@@ -63,89 +101,16 @@ and are therefore not automatically included by this gem:
 - Syslog Appender to a remote syslogng server over TCP or UDP: gem 'net_tcp_client'
 - Splunk Appender: gem 'splunk-sdk-ruby'
 - Elasticsearch Appender: gem 'elasticsearch'
+- OpenSearch Appender: gem 'opensearch-ruby'
 - Kafka Appender: gem 'ruby-kafka'
 - Legacy Sentry Appender: gem 'sentry-raven' (deprecated)
 - Sentry Appender: gem 'sentry-ruby'
+- OpenTelemetry Appender: gem 'opentelemetry-logs-sdk' (plus an exporter, e.g. 'opentelemetry-exporter-otlp-logs')
 
-## Upgrading to Semantic Logger v4.9
-
-These changes should not be noticeable by the majority of users of Semantic Logger, since
-they are to the internal API. It is possible that advanced users may be using these internal
-API's directly.
-
-This does not affect any calls to the public api `SemanticLogger.add_appender`.
-
-File and IO are now separate appenders. When creating the File appender explicitly, its arguments
-have changed. For example, when requesting an IO stream, it needs to be changed from:
-
-~~~ruby
-SemanticLogger::Appender::File.new(io: $stderr)
-~~~
-to:
-~~~ruby
-SemanticLogger::Appender::IO.new($stderr)
-~~~
+## Upgrading
 
-Additionally, this needs to be changed from:
-~~~ruby
-SemanticLogger::Appender::File.new(file_name: "file.log")
-~~~
-to:
-~~~ruby
-SemanticLogger::Appender::File.new("file.log")
-~~~
-
-Rails Semantic Logger, if used, needs to be upgraded to v4.9 when upgrading to Semantic Logger v4.9.
-
-## Upgrading to Semantic Logger v4.4
-
-With some forking frameworks it is necessary to call `reopen` after the fork. With v4.4 the
-workaround for Ruby 2.5 crashes is no longer needed.
-I.e. Please remove the following line if being called anywhere:
-
-~~~ruby
-SemanticLogger::Processor.instance.instance_variable_set(:@queue, Queue.new)
-~~~
-
-## Upgrading to Semantic Logger v4.0
-
-The following changes need to be made when upgrading to V4:
-- Ruby V2.3 / JRuby V9.1 is now the minimum runtime version.
-- Replace calls to Logger#with_payload with SemanticLogger.named_tagged.
-- Replace calls to Logger#payload with SemanticLogger.named_tags.
-- MongoDB Appender requires Mongo Ruby Client V2 or greater.
-- Appenders now write payload data in a seperate :payload tag instead of mixing them
-  directly into the root elements to avoid name clashes.
-
-As a result any calls like the following:
-
-~~~ruby
-logger.debug foo: 'foo', bar: 'bar'
-~~~
-
-Must be replaced with the following in v4:
-
-~~~ruby
-logger.debug payload: {foo: 'foo', bar: 'bar'}
-~~~
-
-Similarly, for measure blocks:
-
-~~~ruby
-logger.measure_info('How long is the sleep', foo: 'foo', bar: 'bar') { sleep 1 }
-~~~
-
-Must be replaced with the following in v4:
-
-~~~ruby
-logger.measure_info('How long is the sleep', payload: {foo: 'foo', bar: 'bar'}) { sleep 1 }
-~~~
-
-The common log call has not changed, and the payload is still logged directly:
-
-~~~ruby
-logger.debug('log this', foo: 'foo', bar: 'bar')
-~~~
+See the [Upgrading Guide](https://logger.rocketjob.io/upgrading.html) for instructions on
+upgrading between major versions.
 
 ## Install
 
@@ -165,6 +130,11 @@ SemanticLogger.add_appender(file_name: 'development.log', formatter: :color)
 
 If running rails, see: [Semantic Logger Rails](https://logger.rocketjob.io/rails.html)
 
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up the project, run the
+tests, and an overview of the architecture, including a class diagram.
+
 ## Author
 
 [Reid Morrison](https://github.com/reidmorrison)

data/Rakefile

@@ -4,21 +4,57 @@ require "rake/testtask"
 $LOAD_PATH.unshift File.expand_path("lib", __dir__)
 require "semantic_logger/version"
 
+desc "Build the semantic_logger gem"
 task :gem do
   system "gem build semantic_logger.gemspec"
 end
 
+desc "Tag and push the release, then publish the gem to RubyGems"
 task publish: :gem do
-  # system "git tag -a v#{SemanticLogger::VERSION} -m 'Tagging #{SemanticLogger::VERSION}'"
-  # system "git push --tags"
+  system "git tag -a v#{SemanticLogger::VERSION} -m 'Tagging #{SemanticLogger::VERSION}'"
+  system "git push --tags"
   system "gem push semantic_logger-#{SemanticLogger::VERSION}.gem"
   system "rm semantic_logger-#{SemanticLogger::VERSION}.gem"
 end
 
+desc "Regenerate docs/llms-full.txt from the docs markdown pages"
+task :llms_full do
+  pages  = %w[index api config appenders log metrics rails testing operations security upgrading]
+  header = <<~HEADER
+    # Semantic Logger - Complete Documentation
+
+    > Semantic Logger is a high-performance, asynchronous structured logging framework for Ruby and Rails.
+
+    This file concatenates every page of https://logger.rocketjob.io for consumption by AI assistants.
+    It is generated from the markdown sources in docs/ by `bundle exec rake llms_full`; do not edit it directly.
+    A per-page index is available at https://logger.rocketjob.io/llms.txt
+  HEADER
+
+  sections = pages.map do |page|
+    text = File.read("docs/#{page}.md").
+           sub(/\A---\n.*?\n---\n/m, ""). # Jekyll front matter
+           gsub(/^\{:.*\}\n/, "").        # kramdown attribute lines ({:toc}, {:.no_toc}, ...)
+           gsub(/^\* TOC\n/, "").
+           gsub(/^\*\*Contents\*\*\n/, "").
+           gsub(/^!\[.*\n/, "")           # images (relative paths, useless in plain text)
+    "<!-- source: docs/#{page}.md -->\n\n#{text.strip}\n"
+  end
+
+  File.write("docs/llms-full.txt", ([header] + sections).join("\n\n---\n\n"))
+  puts "Wrote docs/llms-full.txt (#{File.size('docs/llms-full.txt')} bytes)"
+end
+
 Rake::TestTask.new(:test) do |t|
   t.pattern = "test/**/*_test.rb"
   t.verbose = true
   t.warning = false
 end
 
-task default: :test
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+  # RSpec is only available in the test/development environment.
+end
+
+task default: %i[test spec]