Skip to content

Commit 10c66b6

Browse files
authored
Clarify event naming for different outcomes (#2010)
The "Severity and placement" section previously suggested using the same event name (node.shutdown) at different severity levels to distinguish a graceful shutdown (INFO) from a critical failure (ERROR). This conflicts with the guidance in Event Naming and Verbs, which recommends distinct event names for different outcomes. Updated the example to use node.shutdown.complete (INFO) and node.shutdown.fail (ERROR) so the guide is internally consistent. This is an intentional semantic change, not just a wording tweak. The guide now consistently says: different outcomes → different event names. Severity reflects significance, but should not be the sole way to distinguish success from failure. Fixes #1972
1 parent fecd2a8 commit 10c66b6

1 file changed

Lines changed: 7 additions & 5 deletions

File tree

rust/otap-dataflow/docs/telemetry/events-guide.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,9 @@ guide for naming:
185185
attributes.
186186
- Avoid synonyms that fragment cardinality across names (`finish` vs `complete`,
187187
`error` vs `fail`). Pick one verb set and stick to it.
188+
- Use **distinct event names** for different outcomes of the same operation
189+
(e.g. `otlp.exporter.start.complete` and `otlp.exporter.start.fail`). Do not rely
190+
solely on severity to distinguish success from failure.
188191

189192
More precisely, in this project, event names SHOULD follow this pattern:
190193
`otelcol.<entity>[.<thing>].<verb>`
@@ -225,11 +228,10 @@ Optionally, add occurrence-specific attributes (dynamic context):
225228

226229
When events are exported as logs, set an appropriate severity.
227230

228-
Regarding severity, some events may be logged at different levels depending on
229-
their severity or impact. For example, a `node.shutdown` event may be logged at
230-
INFO level during a graceful shutdown, but at ERROR level if the shutdown is due
231-
to a critical failure. When exporting events as logs, choose the log level that
232-
best reflects the significance of the event.
231+
Regarding severity, choose the log level that best reflects the significance of
232+
the event. For example, `node.shutdown.complete` at INFO for a graceful
233+
shutdown and `node.shutdown.fail` at ERROR for a critical failure -- these are
234+
distinct events, not the same event at different severity levels.
233235

234236
## Stages
235237

0 commit comments

Comments
 (0)