semantic_logger 5.2.0 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. checksums.yaml +4 -4
  2. data/docs/api.md +160 -9
  3. data/docs/appenders.md +461 -34
  4. data/docs/config.md +543 -36
  5. data/docs/log.md +38 -7
  6. data/docs/metrics.md +139 -28
  7. data/docs/operations.md +293 -24
  8. data/docs/rails.md +319 -5
  9. data/docs/security.md +135 -107
  10. data/docs/testing.md +23 -0
  11. data/docs/upgrading.md +644 -1
  12. data/lib/semantic_logger/appender/async.rb +29 -11
  13. data/lib/semantic_logger/appender/bugsnag.rb +7 -2
  14. data/lib/semantic_logger/appender/cloudwatch_logs.rb +46 -6
  15. data/lib/semantic_logger/appender/elasticsearch_base.rb +197 -29
  16. data/lib/semantic_logger/appender/elasticsearch_http.rb +22 -5
  17. data/lib/semantic_logger/appender/file.rb +29 -14
  18. data/lib/semantic_logger/appender/graylog.rb +81 -7
  19. data/lib/semantic_logger/appender/honeybadger.rb +7 -1
  20. data/lib/semantic_logger/appender/honeybadger_insights.rb +8 -2
  21. data/lib/semantic_logger/appender/http.rb +244 -41
  22. data/lib/semantic_logger/appender/io.rb +11 -6
  23. data/lib/semantic_logger/appender/kafka.rb +192 -46
  24. data/lib/semantic_logger/appender/loki.rb +42 -6
  25. data/lib/semantic_logger/appender/mongodb.rb +94 -9
  26. data/lib/semantic_logger/appender/new_relic.rb +2 -3
  27. data/lib/semantic_logger/appender/new_relic_logs.rb +30 -8
  28. data/lib/semantic_logger/appender/open_telemetry.rb +37 -35
  29. data/lib/semantic_logger/appender/rabbitmq.rb +241 -17
  30. data/lib/semantic_logger/appender/sentry.rb +2 -3
  31. data/lib/semantic_logger/appender/sentry_ruby.rb +82 -15
  32. data/lib/semantic_logger/appender/splunk.rb +4 -4
  33. data/lib/semantic_logger/appender/splunk_http.rb +92 -1
  34. data/lib/semantic_logger/appender/syslog.rb +89 -10
  35. data/lib/semantic_logger/appender/tcp.rb +68 -98
  36. data/lib/semantic_logger/appender/text_output.rb +65 -0
  37. data/lib/semantic_logger/appender/udp.rb +130 -18
  38. data/lib/semantic_logger/appender/wrapper.rb +10 -7
  39. data/lib/semantic_logger/appender.rb +115 -10
  40. data/lib/semantic_logger/appenders.rb +136 -4
  41. data/lib/semantic_logger/backtrace_cleaning.rb +77 -0
  42. data/lib/semantic_logger/base.rb +53 -71
  43. data/lib/semantic_logger/call_site.rb +235 -0
  44. data/lib/semantic_logger/context.rb +222 -0
  45. data/lib/semantic_logger/core_ext/process.rb +20 -5
  46. data/lib/semantic_logger/core_ext/warning.rb +70 -0
  47. data/lib/semantic_logger/deprecation.rb +139 -0
  48. data/lib/semantic_logger/exception_details.rb +4 -3
  49. data/lib/semantic_logger/formatters/base.rb +139 -19
  50. data/lib/semantic_logger/formatters/color.rb +3 -4
  51. data/lib/semantic_logger/formatters/default.rb +35 -7
  52. data/lib/semantic_logger/formatters/ecs.rb +9 -4
  53. data/lib/semantic_logger/formatters/json.rb +9 -0
  54. data/lib/semantic_logger/formatters/logfmt.rb +9 -7
  55. data/lib/semantic_logger/formatters/loki/labels.rb +282 -0
  56. data/lib/semantic_logger/formatters/loki.rb +412 -24
  57. data/lib/semantic_logger/formatters/new_relic_logs.rb +15 -13
  58. data/lib/semantic_logger/formatters/one_line.rb +44 -10
  59. data/lib/semantic_logger/formatters/open_telemetry.rb +186 -29
  60. data/lib/semantic_logger/formatters/pattern.rb +60 -8
  61. data/lib/semantic_logger/formatters/raw.rb +38 -8
  62. data/lib/semantic_logger/formatters/signalfx.rb +55 -15
  63. data/lib/semantic_logger/formatters/syslog.rb +4 -2
  64. data/lib/semantic_logger/formatters/syslog_cee.rb +10 -4
  65. data/lib/semantic_logger/formatters/syslog_header.rb +49 -0
  66. data/lib/semantic_logger/formatters.rb +1 -0
  67. data/lib/semantic_logger/log.rb +236 -80
  68. data/lib/semantic_logger/loggable.rb +55 -95
  69. data/lib/semantic_logger/logger.rb +31 -5
  70. data/lib/semantic_logger/metric/new_relic.rb +32 -17
  71. data/lib/semantic_logger/metric/signalfx.rb +21 -12
  72. data/lib/semantic_logger/metric/statsd.rb +26 -8
  73. data/lib/semantic_logger/processor.rb +194 -5
  74. data/lib/semantic_logger/queue_processor/backoff.rb +140 -0
  75. data/lib/semantic_logger/queue_processor/batch_failure.rb +69 -0
  76. data/lib/semantic_logger/queue_processor/held_write.rb +62 -0
  77. data/lib/semantic_logger/queue_processor/inbox.rb +97 -0
  78. data/lib/semantic_logger/queue_processor/reopener.rb +56 -0
  79. data/lib/semantic_logger/queue_processor/reporter.rb +113 -0
  80. data/lib/semantic_logger/queue_processor/request.rb +48 -10
  81. data/lib/semantic_logger/queue_processor/throttled_counter.rb +60 -17
  82. data/lib/semantic_logger/queue_processor.rb +426 -176
  83. data/lib/semantic_logger/ractor_copy.rb +120 -0
  84. data/lib/semantic_logger/ractor_processor.rb +82 -0
  85. data/lib/semantic_logger/ractor_receiver.rb +282 -0
  86. data/lib/semantic_logger/ractor_support.rb +28 -0
  87. data/lib/semantic_logger/redactor.rb +310 -0
  88. data/lib/semantic_logger/semantic_logger.rb +313 -79
  89. data/lib/semantic_logger/subscriber.rb +169 -15
  90. data/lib/semantic_logger/sync_processor.rb +226 -26
  91. data/lib/semantic_logger/test/capture_log_events.rb +20 -2
  92. data/lib/semantic_logger/test/minitest.rb +2 -1
  93. data/lib/semantic_logger/test/rspec.rb +1 -1
  94. data/lib/semantic_logger/trap_safe.rb +113 -0
  95. data/lib/semantic_logger/utils.rb +266 -79
  96. data/lib/semantic_logger/version.rb +1 -1
  97. data/lib/semantic_logger.rb +35 -2
  98. metadata +22 -2
data/docs/security.md CHANGED
@@ -28,6 +28,10 @@ characters in that data can be abused:
28
28
  record into two at a collector that frames records with a separator.
29
29
  * An ANSI escape sequence can spoof or hide terminal output when the log is viewed in
30
30
  a terminal.
31
+ * A Unicode line or paragraph separator (U+2028, U+2029) starts a new line in editors,
32
+ browsers, and some log viewers, and a bidirectional control, such as the right-to-left
33
+ override (U+202E), can make a forged entry, such as `user=admin`, read in another order
34
+ than it was written.
31
35
 
32
36
  The structured formatters, such as `:json`, are **not** affected, because JSON encoding
33
37
  always escapes control characters. They are the recommended choice when forwarding logs
@@ -37,7 +41,7 @@ By design the human readable text formatters (`:default` and `:color`) preserve
37
41
  newlines and ANSI color codes, since multi-line and colorized output is useful when
38
42
  reading logs locally. When the text output may contain untrusted data, enable the
39
43
  `escape_control_chars` option to replace control characters with a printable, escaped
40
- form (for example a newline becomes `\n`):
44
+ form (for example a newline becomes `\n`, and the right-to-left override `\u202e`):
41
45
 
42
46
  ~~~ruby
43
47
  SemanticLogger.add_appender(file_name: "production.log", formatter: {default: {escape_control_chars: true}})
@@ -67,6 +71,10 @@ Semantic Logger only uses such a key as an argument when its value is valid for
67
71
  `duration` must be a finite real number, `backtrace` an Array of Strings, and `on_exception_level` a
68
72
  valid level. Any other value stays in the payload as data, and a `nil` value is ignored, so an
69
73
  untrusted hash passed to a level method such as `info` can never make the logging call raise.
74
+ A valid `backtrace` also sets where the entry is recorded as logged: its file name, line number, and,
75
+ with [`call_site_level`](config.html#recording-where-each-entry-was-logged), its method. A
76
+ `call_site` key can only leave out the recorded call site, with `false`: the values that set one are
77
+ Ruby objects that parsed data cannot hold.
70
78
 
71
79
  To make sure none of its keys are treated as arguments, pass it as the explicit `payload:`. Any other
72
80
  keys supplied alongside an explicit `payload:` are merged into it, and win over the explicit
@@ -96,126 +104,146 @@ raises unless it is given a valid `:duration`.
96
104
 
97
105
  ### Redacting sensitive data
98
106
 
99
- Semantic Logger does not automatically redact secrets or personal information; it logs
100
- the message and payload it is given. Avoid logging passwords, tokens, full credit card
101
- numbers, and similar values in the first place.
107
+ Semantic Logger logs the message and payload it is given. Avoid logging passwords, tokens, full
108
+ credit card numbers, and similar values in the first place.
102
109
 
103
- When sensitive values can reach the logs indirectly, redact them. A global `on_log`
104
- subscriber runs inline, once per log event, before the event is handed to any appender,
105
- so it can scrub the payload for every destination. The example below matches keys at any depth,
106
- whether they are Strings, as in parsed JSON and Rails params, or Symbols, in any case and style,
107
- such as `api_key`, `apiKey`, or `X-Api-Key`. It builds a new payload rather than changing the logged
108
- one, which can be the application's own Hash. It fails closed: a payload that it cannot redact is
109
- replaced, never written as it is.
110
+ When sensitive values can still reach the logs, for example in request headers or parameters that
111
+ are logged as they are, name the sensitive keys once. The value of every matching key is replaced
112
+ with `[FILTERED]` in every log entry, before any appender writes it:
110
113
 
111
114
  ~~~ruby
112
- module LogRedaction
113
- # Matched against each key in lower case with "_" between its words, see sensitive_key?.
114
- SENSITIVE_KEY = Regexp.union(
115
- # Anywhere in the key, like the default filter_parameters of Rails.
116
- /passw|passphrase|secret|token|_key|apikey|credential|authorization|cookie|crypt|certificate|email/,
117
- # Only as a whole word, so that "otp" does not match "footprint", nor "ssn" "business_name".
118
- /(?<![a-z])(?:auth|pwd|otp|ssn|salt|cvv|cvc)(?![a-z])/
119
- )
120
- REDACTED = "[REDACTED]".freeze
121
- MAX_DEPTH = 32
122
-
123
- # Returns a copy of the value with the value of every sensitive key replaced, at any depth.
124
- #
125
- # copies maps each structure already walked to its copy, so that a structure held more than once
126
- # is walked only once, and one that holds itself is cut off.
127
- def self.redact(value, copies = {}.compare_by_identity, depth = 0)
128
- return copies[value] || "[REDACTED: circular]" if copies.key?(value)
129
-
130
- members = members(value)
131
- return value if members.nil?
132
- return "[REDACTED: nested too deeply]" if depth >= MAX_DEPTH
133
-
134
- copies[value] = nil # Until its copy is complete.
135
- copies[value] =
136
- if members.is_a?(Hash)
137
- members.each_with_object({}) do |(key, val), copy|
138
- copy[key] = sensitive_key?(key) ? REDACTED : redact(val, copies, depth + 1)
139
- end
140
- else
141
- members.map { |val| redact(val, copies, depth + 1) }
142
- end
143
- end
144
-
145
- def self.sensitive_key?(key)
146
- # As valid UTF-8, since a key with invalid bytes, as from a query string, makes a match raise.
147
- name = key.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
148
- # "apiKey", "API_KEY", and "X-Api-Key" become "api_key", "api_key", and "x_api_key".
149
- name = name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.gsub(/[^a-z\d]+/, "_")
150
- SENSITIVE_KEY.match?(name)
151
- end
152
-
153
- # Returns the members of a Hash, Array, Struct, Data, Set, OpenStruct, or
154
- # ActionController::Parameters, as a Hash or an Array. Returns nil for any other value.
155
- def self.members(value)
156
- case value
157
- when Hash, Array then value
158
- when Struct, Data then value.to_h
159
- when Set then value.to_a
160
- else
161
- if defined?(OpenStruct) && value.is_a?(OpenStruct)
162
- value.to_h
163
- elsif value.respond_to?(:to_unsafe_h) # ActionController::Parameters
164
- value.to_unsafe_h
165
- end
166
- end
167
- end
168
- end
115
+ SemanticLogger.sensitive_keys = %i[passw secret token _key authorization cookie]
116
+ ~~~
169
117
 
170
- # Register it before any other on_log subscriber.
171
- SemanticLogger.on_log do |log|
172
- log.payload = LogRedaction.redact(log.payload) unless log.payload.nil?
173
- rescue Exception => e
174
- # Fail closed. Any Exception, since Semantic Logger rescues whatever an on_log subscriber raises
175
- # and goes on to write the entry.
176
- log.payload = {redaction_failed: e.class.name}
177
- end
118
+ ~~~ruby
119
+ logger.info("Calling API", headers: {"Authorization" => "Bearer abc123", "Accept" => "application/json"})
120
+ # Written with: headers: {"Authorization" => "[FILTERED]", "Accept" => "application/json"}
178
121
  ~~~
179
122
 
180
- `SENSITIVE_KEY` is a starting point: adapt it to the keys that your application logs. Like the
181
- default `filter_parameters` of Rails, it also matches some keys that are not secret, such as
182
- `max_tokens` or `cache_key`.
123
+ Rails applications that use [rails_semantic_logger](https://github.com/reidmorrison/rails_semantic_logger)
124
+ get this from `config.filter_parameters`; see [With Rails](#with-rails) below.
125
+
126
+ #### Naming the sensitive keys
183
127
 
184
- The example looks inside Hashes and Arrays, and inside the Struct, Data, Set, and OpenStruct values
185
- that the JSON formatters write as objects and arrays, which it replaces with Hashes and Arrays. It
186
- reads `ActionController::Parameters` with `to_unsafe_h`. Any other object is left as it is, and is
187
- written the way the formatter writes it, which for some objects includes all of their attributes:
188
- for example a JSON formatter writes an Active Record model with `as_json`. Log a Hash of the values
189
- you need instead.
128
+ | Value | Sensitive keys |
129
+ |-------|----------------|
130
+ | An Array | Each Symbol or String matches any key whose name contains it, ignoring case, as in Rails' `config.filter_parameters`. Each Regexp matches as written. |
131
+ | A Regexp | Keys whose names it matches. |
132
+ | An `ActiveSupport::ParameterFilter` | Keys for which `filter_param(name, nil)` returns a value, which replaces the key's value, so a custom `mask:` is kept. Any object that responds to `#filter_param` works the same way. |
133
+ | A Proc, or any object that responds to `#call` | Keys for which it returns true, given the key's name. |
134
+ | `nil` | None: nothing is redacted. The default. |
190
135
 
191
- Register it before any other `on_log` subscriber that reads the payload. Subscribers run in the
192
- order they were registered, so one registered before it, such as the [Rollbar](appenders.html#rollbar)
193
- integration that sends `log.to_h`, receives the payload before it is redacted.
136
+ Keys are matched by name: the name of a Symbol key or a String key, both as written and in
137
+ snake_case, which is lower case. So `:_key` above also matches `"X-Api-Key"` as `"x_api_key"`,
138
+ `"apiKey"` and `"APIKey"` as `"api_key"`, and `"HTTP_X_API_KEY"` as `"http_x_api_key"`.
139
+
140
+ Like the default `filter_parameters` of Rails, a name matches wherever it appears in a key, so it
141
+ also matches some keys that are not secret: `:token` matches `max_tokens`, and `:_key` matches
142
+ `cache_key`. To match whole words only, use a Regexp:
143
+
144
+ ~~~ruby
145
+ SemanticLogger.sensitive_keys = [
146
+ # Anywhere in the key.
147
+ :passw, :secret, :token, :_key, :credential, :authorization, :cookie, :crypt, :certificate,
148
+ # Only as a whole word, so that "otp" does not match "footprint", nor "ssn" "business_name".
149
+ /(?<![a-z])(?:auth|pwd|otp|ssn|salt|cvv|cvc)(?![a-z])/
150
+ ]
151
+ ~~~
194
152
 
195
- It only redacts the payload. The message, the tags and named tags, the message of the exception and
196
- those of its causes, the context that `on_log` subscribers add, and metric dimensions are written
197
- as they are, so keep secrets out of them. That includes a value other than a Hash passed after the
198
- message, such as `logger.info("Login", user)`, which is added to the message: pass it as
199
- `payload: user` instead.
153
+ The keys are read when they are assigned, so adding to the Array afterwards has no effect: assign
154
+ the whole list again. The answer for each key name is remembered, so a Proc or object must always
155
+ give the same answer for the same name. It is called on the thread that writes the entries, so it
156
+ must be thread safe.
200
157
 
201
- It copies the payload of every entry that is logged, even when there is nothing to redact, on the
202
- thread that logs it, so its cost grows with the size of the payloads.
158
+ #### What is redacted
203
159
 
204
- A `filter` on a logger instance can redact the same way for that logger's entries; see
205
- [Filtering](config.html#filtering). Do not redact in an appender's `filter`: every appender writes
160
+ The payload, the named tags, the context that `on_log` subscribers add with `log.set_context`, and
161
+ metric dimensions, at any depth: inside each Hash, including a key that is itself a Hash, and inside
162
+ each Array, Set, Struct, Data, OpenStruct, and `ActionController::Parameters`. The value of a
163
+ sensitive key is replaced whole, even when it is a Hash. A Struct, Data, or OpenStruct that holds a
164
+ sensitive key is written as a Hash, and a Set as an Array, as the JSON formatters write them. A
165
+ structure that holds itself is cut off with `[FILTERED: circular]`, and one nested more than 32
166
+ levels deep is replaced with `[FILTERED: nested too deeply]`.
167
+
168
+ The application's own Hashes are never changed: the entry is given a copy, and only when it holds a
169
+ sensitive key, or a structure that holds itself or is nested too deeply. Other entries are written
170
+ as they are.
171
+
172
+ These are written as they are, so keep secrets out of them:
173
+
174
+ * The message, and a value other than a Hash passed after it, such as `logger.info("Login", user)`,
175
+ which is added to the message: pass it as `payload: user` instead.
176
+ * The tags, the message of the exception, and those of the exceptions that caused it.
177
+ * Any other object, which is written the way the formatter writes it. For some objects that
178
+ includes all of their attributes: for example a JSON formatter writes an Active Record model with
179
+ `as_json`. Log a Hash of the values you need instead.
180
+
181
+ To change text in messages, rewrite the message in a logger's `filter` or in an `on_log` subscriber;
182
+ see [Filtering](config.html#filtering). Do not redact in an appender's `filter`: every appender writes
206
183
  the same log entry, so that only protects the appenders added after it, while the ones added before
207
184
  it have already written the secret.
208
185
 
209
- Rails applications should use the sister gem
210
- [rails_semantic_logger](https://github.com/reidmorrison/rails_semantic_logger), which
211
- honours `config.filter_parameters` so that parameters Rails already considers sensitive
212
- are filtered out of the logs. To match the payload's keys against the same list, `sensitive_key?`
213
- can return `!filter.filter_param(name, nil).nil?`, where `filter` is
214
- `ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)`, created once the
215
- application has initialized, since one created from an incomplete list filters less. Proc filters
216
- in the list are not applied this way. Do not call its `#filter` in place of `redact`: it only looks
217
- inside Hashes and Arrays, raises for a key with invalid UTF-8, and has no protection against a Hash
218
- that holds itself or is held more than once.
186
+ #### When it runs
187
+
188
+ Each entry is redacted once, on the thread that writes entries to the appenders (the background
189
+ thread, or with [synchronous logging](operations.html#synchronous-operation) the thread that logs),
190
+ before any appender writes it or its `filter` reads it. That includes the appenders that send
191
+ entries to error services, such as Sentry, Bugsnag, and Honeybadger, and appenders of your own. It
192
+ costs a few microseconds for a typical payload, off the application's own threads.
193
+
194
+ `on_log` subscribers and logger filters run earlier, on the thread that logs the entry, and receive it
195
+ as it was logged. The [Rollbar](appenders.html#rollbar) integration is one: it sends `log.to_h`, so
196
+ its entries are not redacted. So do the [testing helpers](testing.html), which capture entries as they
197
+ were logged.
198
+
199
+ When an entry cannot be redacted, for example because a Proc raises an error, the field is replaced
200
+ with `{redaction_failed: "ErrorClass"}`, never written as it is. The error's class, and where it was
201
+ raised, are reported to the internal logger, but not its message, which could hold the value.
202
+
203
+ #### With Rails
204
+
205
+ [rails_semantic_logger](https://github.com/reidmorrison/rails_semantic_logger) sets
206
+ `SemanticLogger.sensitive_keys` from `config.filter_parameters` once the application has initialized,
207
+ so that the keys Rails filters out of request parameters are filtered out of every log entry. To
208
+ turn it off:
209
+
210
+ ~~~ruby
211
+ config.rails_semantic_logger.redact_filter_parameters = false
212
+ ~~~
213
+
214
+ To use other keys instead, set them in `config/application.rb`, and they are kept:
215
+
216
+ ~~~ruby
217
+ config.semantic_logger.sensitive_keys = %i[passw secret token _key authorization cookie]
218
+ ~~~
219
+
220
+ Setting `config.semantic_logger.sensitive_keys = nil` does not turn it off, since that cannot be told
221
+ apart from never setting it; use `redact_filter_parameters = false`.
222
+
223
+ Notes:
224
+
225
+ * The default list of a new Rails application, in `config/initializers/filter_parameter_logging.rb`,
226
+ does not match the `Authorization` or `Cookie` header. Add them:
227
+ `Rails.application.config.filter_parameters += %i[authorization cookie]`.
228
+ * That list includes `:email`, so an email address is filtered, including the `user_email` named tag
229
+ that the [Sentry](appenders.html#sentry) appender sends as the user's email. It also matches keys
230
+ that are not secret, such as `max_tokens` (`:token`) and `cache_key` (`:_key`).
231
+ * A Proc in the list is left out, since it changes a value rather than naming a key. A dotted
232
+ filter, such as `"credit_card.code"`, only matches a key with that whole name, not `code` inside
233
+ `credit_card`.
234
+ * Active Job `arguments` and Action Mailer `args` are logged as JSON text, which is not redacted. For
235
+ a job that takes a secret, leave its arguments out of the log with `self.log_arguments = false`.
236
+ * Entries logged while the application starts, before the list is complete, may not be redacted.
237
+
238
+ To set it yourself, for example without rails_semantic_logger, do the same once the application has
239
+ initialized:
240
+
241
+ ~~~ruby
242
+ Rails.application.config.after_initialize do
243
+ filters = Rails.application.config.filter_parameters.reject { |filter| filter.respond_to?(:call) }
244
+ SemanticLogger.sensitive_keys = ActiveSupport::ParameterFilter.new(filters)
245
+ end
246
+ ~~~
219
247
 
220
248
  ### Transport encryption
221
249
 
data/docs/testing.md CHANGED
@@ -52,6 +52,16 @@ messages = semantic_logger_events(ApiClient) do
52
52
  end
53
53
  ~~~
54
54
 
55
+ Passing a class replaces that class's `logger` while the block runs, so it captures only the log calls
56
+ made through that logger. Capture without a class instead when:
57
+
58
+ - the code under test logs through a logger it got some other way, such as `SemanticLogger["Name"]`
59
+ or a logger handed to it by a framework;
60
+ - an instance of the class called `logger` before the block, since each instance keeps the first
61
+ logger it is given; or
62
+ - you need to assert on `name`: events captured through a class are named
63
+ `SemanticLogger::Test::CaptureLogEvents`, not after the class.
64
+
55
65
  ### Step 3: assert on the events
56
66
 
57
67
  Check how many events were produced, then assert on each one with `assert_semantic_logger_event`:
@@ -108,6 +118,7 @@ test. The available checks are:
108
118
  | `time` | When the entry was created. |
109
119
  | `duration` | Duration of a measure call, in milliseconds. |
110
120
  | `backtrace` | The captured backtrace, if any. |
121
+ | `call_site` | Where the entry was logged, a `SemanticLogger::CallSite`, when `SemanticLogger.call_site_level` is set. |
111
122
  | `thread_name` | Name of the thread that logged the entry, or its object id when the thread has no name. |
112
123
 
113
124
  ### Match part of a message or payload
@@ -185,6 +196,18 @@ events = capture_semantic_logger_events(ApiClient) do
185
196
  end
186
197
  ~~~
187
198
 
199
+ Passing a class replaces that class's `logger` until the end of the example, not just the block, so
200
+ it captures only the log calls made through that logger. Log calls made after the block are added to
201
+ the same returned array, so check the event count before running more code that logs. Capture without
202
+ a class instead when:
203
+
204
+ - the code under test logs through a logger it got some other way, such as `SemanticLogger["Name"]`
205
+ or a logger handed to it by a framework;
206
+ - an instance of the class called `logger` before the block, since each instance keeps the first
207
+ logger it is given; or
208
+ - you need to assert on `name`: events captured through a class are named
209
+ `SemanticLogger::Test::CaptureLogEvents`, not after the class.
210
+
188
211
  ### Step 3: assert on the events
189
212
 
190
213
  Use `be_a_semantic_logger_event` to assert on a single captured event: