Document the new LogTarget

CHANGELOG.md

@@ -5,13 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [Unreleased] TBD
 
+### Added
 - Add new `LogTarget`
 - Introduce new `formatter:` options: `:json`, `:logfmt`, and `:noop`
 - Introduce new `transform:` options: `:cloud_watch`, `:l2met`, and `:noop`
 
-## [1.1.3]
+## [1.1.3] 2024-05-13
 
 ### Changed
 - Updated gems in the lockfile
@@ -22,14 +23,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Dropped
 - Check for support for 'ubuntu-18.04'
 
-## [1.1.2]
+## [1.1.2] 2022-12-28
 
 - Add Puma 6 compatibility
-## [1.1.1]
+
+## [1.1.1] 2022-06-22
 
 Public release.
 
-## [1.1.0]
+## [1.1.0] 2022-06-22
 
 Out of beta testing, reading for usage. Following is a recap from Alpha & Beta releases.
 
@@ -41,8 +43,7 @@ Out of beta testing, reading for usage. Following is a recap from Alpha & Beta r
 - `config.socket_parser` option to allow custom parser implementation as needed
 - Datadog widgets examples under `docs/examples.md`
 
-## [1.1.0 Beta]
-
+## [1.1.0 Beta] ???
 ### Added
 
 Different ways to parse `Socket::Option`. Mainly due to the fact that `#inspect` can't
@@ -55,8 +56,7 @@ struct, so it should more or less stay stable.
 You can configure it by passing in `config.socket_parser = :inspect` or
 `config.socket_parser = ->(opt) { your implementation }`.
 
-## [1.1.0 Alpha]
-
+## [1.1.0 Alpha] ???
 ### Added
 
 Socket telemetry, and to be more precise new metric: `sockets.backlog`. If enabled it will
@@ -65,32 +65,32 @@ be acknowledged by Puma). It will be exposed under `sockets-backlog` metric.
 
 You can enable and test it via `config.sockets_telemetry!` option.
 
-## [1.0.0] - 2021-09-08
+## [1.0.0] 2021-09-08
 ### Added
-- Release to Github Packages
-- Explicitly flush datadog metrics after publishing them
+- Release to GitHub Packages
+- Explicitly flush Datadog metrics after publishing them
 - Middleware for measuring and tracking request queue time
 
 ### Changed
-- Replace `statsd.batch` with direct calls, as it aggregates metrics interally by default now.
+- Replace `statsd.batch` with direct calls, as it aggregates metrics internally by default now.
   Also `#batch` method is deprecated and will be removed in version 6 of Datadog Statsd client.
 
-## [0.3.1] - 2021-03-26
+## [0.3.1] 2021-03-26
 ### Changed
 - IO target replaces dots in telemetry keys with dashes for better integration with AWS CloudWatch
 
-## [0.3.0] - 2020-12-21
+## [0.3.0] 2020-12-21
 ### Added
 - Datadog Target integration tests
 
 ### Fixed
 - Datadog Target
 
-## [0.2.0] - 2020-12-21
+## [0.2.0] 2020-12-21
 ### Fixed
 - Removed debugging information
 
-## [0.1.0] - 2020-12-18
+## [0.1.0] 2020-12-18
 ### Added
 - Core Plugin
 - Telemetry generation

README.md

@@ -41,22 +41,61 @@ Puma::Plugin::Telemetry.configure do |config|
 end
 ```
 
-### Basic
+### Basic IO Target
 
-Output telemetry as JSON to `STDOUT`
+A basic I/O target will emit telemetry data to `STDOUT`, formatted in JSON.
 
 ```ruby
-  config.add_target :io
+config.add_target :io
 ```
 
+#### Options
+
+This target has configurable `formatter:` and `transform:` options.
+The `formatter:` options are
+
+* `:json` _(default)_ - Print the logs in JSON.
+* `:logfmt` - Print the logs in key/value pairs, as per `logfmt`.
+* `:noop` - A NOOP formatter which returns the telemetry `Hash` unaltered, passing it directly to the `io:` instance.
+
+The `transform:` options are
+
+* `:cloud_watch` _(default)_ - Transforms telemetry keys, replacing dots with dashes to support AWS CloudWatch Log Metrics filters.
+* `:logfmt` - Transforms telemetry keys, prepending `sample#` for [L2Met][l2met] consumption.
+* `:noop` -  A NOOP transform which returns the telemetry `Hash` unaltered.
+
+### Log target
+
+Emitting to `STDOUT` via the basic `IOTarget` can work for getting telemetry into logs, we also provide an explicit `LogTarget`.
+This target will defaults to emitting telemetry at the `INFO` log level via a [standard library `::Logger`][logger] instance.
+That default logger will print to `STDOUT` in [the `logfmt` format][logfmt].
+
+```ruby
+config.add_target :log
+```
+
+You can pass an explicit `logger:` option if you wanted to, for example, use the same logger as Rails.
+
+```ruby
+config.add_target :log, logger: Rails.logger
+```
+
+This target also has configurable `formatter:` and `transform:` options.
+The [possible options are the same as for the `IOTarget`](#options), but the defaults are different.
+The `LogTarget` defaults to `formatter: :logfmt`, and `transform: :noop`
+
+[l2met]: https://github.com/ryandotsmith/l2met?tab=readme-ov-file#l2met "l2met - Logs to Metrics"
+[logfmt]: https://brandur.org/logfmt "logfmt - Structured log format"
+[logger]: https://rubyapi.org/o/logger "Ruby's Logger, from the stdlib"
+
 ### Datadog StatsD target
 
-Given gem provides built in target for Datadog StatsD client, that uses batch operation to publish metrics.
+A target for the Datadog StatsD client, that uses batch operation to publish metrics.
 
-**NOTE** Be sure to have `dogstatsd` gem installed.
+**NOTE** Be sure to have the `dogstatsd` gem installed.
 
 ```ruby
-  config.add_target :dogstatsd, client: Datadog::Statsd.new
+config.add_target :dogstatsd, client: Datadog::Statsd.new
 ```
 
 You can provide all the tags, namespaces, and other configuration options as always to `Datadog::Statsd.new` method.
@@ -75,6 +114,7 @@ Puma::Plugin::Telemetry.configure do |config|
   config.socket_parser = :inspect
   config.add_target :io, formatter: :json, io: StringIO.new
   config.add_target :dogstatsd, client: Datadog::Statsd.new(tags: { env: ENV["RAILS_ENV"] })
+  config.add_target :log, logger: Rails.logger, formatter: :logfmt, transform: :l2met)
 end
 ```
 
@@ -85,8 +125,8 @@ Target is a simple object that implements `call` methods that accepts `telemetry
 Just be mindful that if the API takes long to call, it will slow down frequency with which telemetry will get reported.
 
 ```ruby
-  # Example logfmt to stdout target
-  config.add_target proc { |telemetry| puts telemetry.map { |k, v| "#{k}=#{v.inspect}" }.join(" ") }
+  # Example key/value log to `STDOUT` target
+  config.add_target ->(telemetry) { puts telemetry.map { |k, v| "#{k}=#{v.inspect}" }.join(" ") }
 ```
 
 ## Extra middleware