@@ -41,22 +41,61 @@ Puma::Plugin::Telemetry.configure do |config|
4141end
4242```
4343
44- ### Basic
44+ ### Basic IO Target
4545
46- Output telemetry as JSON to ` STDOUT `
46+ A basic I/O target will emit telemetry data to ` STDOUT ` , formatted in JSON.
4747
4848``` ruby
49- config.add_target :io
49+ config.add_target :io
5050```
5151
52+ #### Options
53+
54+ This target has configurable ` formatter: ` and ` transform: ` options.
55+ The ` formatter: ` options are
56+
57+ * ` :json ` _ (default)_ - Print the logs in JSON.
58+ * ` :logfmt ` - Print the logs in key/value pairs, as per ` logfmt ` .
59+ * ` :noop ` - A NOOP formatter which returns the telemetry ` Hash ` unaltered, passing it directly to the ` io: ` instance.
60+
61+ The ` transform: ` options are
62+
63+ * ` :cloud_watch ` _ (default)_ - Transforms telemetry keys, replacing dots with dashes to support AWS CloudWatch Log Metrics filters.
64+ * ` :logfmt ` - Transforms telemetry keys, prepending ` sample# ` for [ L2Met] [ l2met ] consumption.
65+ * ` :noop ` - A NOOP transform which returns the telemetry ` Hash ` unaltered.
66+
67+ ### Log target
68+
69+ Emitting to ` STDOUT ` via the basic ` IOTarget ` can work for getting telemetry into logs, we also provide an explicit ` LogTarget ` .
70+ This target will defaults to emitting telemetry at the ` INFO ` log level via a [ standard library ` ::Logger ` ] [ logger ] instance.
71+ That default logger will print to ` STDOUT ` in [ the ` logfmt ` format] [ logfmt ] .
72+
73+ ``` ruby
74+ config.add_target :log
75+ ```
76+
77+ You can pass an explicit ` logger: ` option if you wanted to, for example, use the same logger as Rails.
78+
79+ ``` ruby
80+ config.add_target :log , logger: Rails .logger
81+ ```
82+
83+ This target also has configurable ` formatter: ` and ` transform: ` options.
84+ The [ possible options are the same as for the ` IOTarget ` ] ( #options ) , but the defaults are different.
85+ The ` LogTarget ` defaults to ` formatter: :logfmt ` , and ` transform: :noop `
86+
87+ [ l2met ] : https://github.com/ryandotsmith/l2met?tab=readme-ov-file#l2met " l2met - Logs to Metrics "
88+ [ logfmt ] : https://brandur.org/logfmt " logfmt - Structured log format "
89+ [ logger ] : https://rubyapi.org/o/logger " Ruby's Logger, from the stdlib "
90+
5291### Datadog StatsD target
5392
54- Given gem provides built in target for Datadog StatsD client, that uses batch operation to publish metrics.
93+ A target for the Datadog StatsD client, that uses batch operation to publish metrics.
5594
56- ** NOTE** Be sure to have ` dogstatsd ` gem installed.
95+ ** NOTE** Be sure to have the ` dogstatsd ` gem installed.
5796
5897``` ruby
59- config.add_target :dogstatsd , client: Datadog ::Statsd .new
98+ config.add_target :dogstatsd , client: Datadog ::Statsd .new
6099```
61100
62101You 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|
75114 config.socket_parser = :inspect
76115 config.add_target :io , formatter: :json , io: StringIO .new
77116 config.add_target :dogstatsd , client: Datadog ::Statsd .new (tags: { env: ENV [" RAILS_ENV"
117+ config.add_target :log , logger: Rails .logger, formatter: :logfmt , transform: :l2met )
78118end
79119```
80120
@@ -85,8 +125,8 @@ Target is a simple object that implements `call` methods that accepts `telemetry
85125Just be mindful that if the API takes long to call, it will slow down frequency with which telemetry will get reported.
86126
87127``` ruby
88- # Example logfmt to stdout target
89- config.add_target proc { | telemetry | puts telemetry.map { |k , v | " #{ k } =#{ v.inspect } " " "
128+ # Example key/value log to `STDOUT` target
129+ config.add_target -> (telemetry) { puts telemetry.map { |k , v | " #{ k } =#{ v.inspect } " " "
90130```
91131
92132## Extra middleware
0 commit comments