From cca495445c8a7601c1160ff4858e767c878c2a37 Mon Sep 17 00:00:00 2001
From: Steven Harman <steven@harmanly.com>
Date: Wed, 3 Jul 2024 16:09:13 -0400
Subject: [PATCH] Document new formatter and transform options

---
 CHANGELOG.md | 43 +++++++++++++++++++++++--------------------
 README.md    | 31 ++++++++++++++++++++++---------
 2 files changed, 45 insertions(+), 29 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df8598e..1937db9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,17 +5,21 @@ 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
 
-## [1.1.4]
+### Added
+- Introduce new `formatter:` options: `:json` and `:passthrough`
+- Introduce new `transform:` options: `:cloud_watch` and `:passthrough`
+
+## [1.1.4] 2024-05-29
 
 ### Changed
-- Updated gems in the lockfile
+- Updated gems in the Gemfile.lock
 
-## [1.1.3]
+## [1.1.3] 2024-05-13
 
 ### Changed
-- Updated gems in the lockfile
+- Updated gems in the Gemfile.lock
 
 ### Added
 - Support for Ruby 3.2 and 3.3
@@ -23,14 +27,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.
 
@@ -42,8 +47,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
@@ -56,8 +60,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
@@ -66,32 +69,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
diff --git a/README.md b/README.md
index d0b6f66..5180c69 100644
--- a/README.md
+++ b/README.md
@@ -41,22 +41,35 @@ 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.
+* `:passthrough` - A passthrough 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.
+* `:passthrough` -  A passthrough transform which returns the telemetry `Hash` unaltered.
+
 ### 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.
@@ -73,7 +86,7 @@ Puma::Plugin::Telemetry.configure do |config|
   config.puma_telemetry = %w[workers.requests_count queue.backlog queue.capacity]
   config.socket_telemetry!
   config.socket_parser = :inspect
-  config.add_target :io, formatter: :json, io: StringIO.new
+  config.add_target :io, io: StringIO.new, formatter: :json, transform: :passthrough
   config.add_target :dogstatsd, client: Datadog::Statsd.new(tags: { env: ENV["RAILS_ENV"] })
 end
 ```
@@ -85,8 +98,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