diff --git a/CHANGELOG.md b/CHANGELOG.md index 7b7642c..0122ab0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,20 +5,20 @@ 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.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. @@ -30,8 +30,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 @@ -44,8 +43,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 @@ -54,32 +52,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..06ff085 100644 --- a/README.md +++ b/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