From e9c31f504fba42a8f2ff683326fe0bcfe5c0d5d8 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Thu, 18 Dec 2025 11:57:33 -0500 Subject: [PATCH 1/3] docs: fix break syntax Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index 0a35385d..f91037e2 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -61,9 +61,9 @@ Telemetry hooks can emit OpenTelemetry signals in three distinct ways: | Pattern | Advantages | Disadvantages | | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Span Events**
![recommended](https://img.shields.io/badge/recommended-green) | - Leverages existing trace configuration and tooling
- Minimal overhead, no additional spans created
- Maintains trace context relationships
- Simpler than creating spans | - Requires an active span to function
- Must gracefully handle absence of active span
- Limited to span lifetime and context. | -| **Event Logging** | - Works independently without active spans
- Aligns with OpenTelemetry's emerging direction
- Suitable for environments without tracing
- Simpler implementation model | - Requires an event exporter to be configured
- Processed and stored separately from spans
- Event logging standards still evolving | -| **Standalone Spans** | - Distributed traces contain every evaluation
- Detailed timing information
- Full span lifecycle control | - Creates one span per evaluation
- May clutter trace visualizations
- Increased overhead and resource usage
- Potential performance impact at scale
- More complex implementation | +| **Span Events**
![recommended](https://img.shields.io/badge/recommended-green) | - Leverages existing trace configuration and tooling
- Minimal overhead, no additional spans created
- Maintains trace context relationships
- Simpler than creating spans | - Requires an active span to function
- Must gracefully handle absence of active span
- Limited to span lifetime and context. | +| **Event Logging** | - Works independently without active spans
- Aligns with OpenTelemetry's emerging direction
- Suitable for environments without tracing
- Simpler implementation model | - Requires an event exporter to be configured
- Processed and stored separately from spans
- Event logging standards still evolving | +| **Standalone Spans** | - Distributed traces contain every evaluation
- Detailed timing information
- Full span lifecycle control | - Creates one span per evaluation
- May clutter trace visualizations
- Increased overhead and resource usage
- Potential performance impact at scale
- More complex implementation | > [!NOTE] > While span events are recommended for their low overhead and ease of use, OpenTelemetry is trending toward using log-based events instead of span events. Please refer to the [OpenTelemetry Span Event Deprecation Plan][otel-span-event-deprecation-plan] for more details. From 07eaa2438c261d93962ca4a6d0cfe8b8132845a0 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Thu, 18 Dec 2025 13:00:34 -0500 Subject: [PATCH 2/3] Update specification/appendix-d-observability.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index f91037e2..665b68e3 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -61,9 +61,9 @@ Telemetry hooks can emit OpenTelemetry signals in three distinct ways: | Pattern | Advantages | Disadvantages | | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Span Events**
![recommended](https://img.shields.io/badge/recommended-green) | - Leverages existing trace configuration and tooling
- Minimal overhead, no additional spans created
- Maintains trace context relationships
- Simpler than creating spans | - Requires an active span to function
- Must gracefully handle absence of active span
- Limited to span lifetime and context. | -| **Event Logging** | - Works independently without active spans
- Aligns with OpenTelemetry's emerging direction
- Suitable for environments without tracing
- Simpler implementation model | - Requires an event exporter to be configured
- Processed and stored separately from spans
- Event logging standards still evolving | -| **Standalone Spans** | - Distributed traces contain every evaluation
- Detailed timing information
- Full span lifecycle control | - Creates one span per evaluation
- May clutter trace visualizations
- Increased overhead and resource usage
- Potential performance impact at scale
- More complex implementation | +| **Span Events**
![recommended](https://img.shields.io/badge/recommended-green) |
  • Leverages existing trace configuration and tooling
  • Minimal overhead, no additional spans created
  • Maintains trace context relationships
  • Simpler than creating spans
|
  • Requires an active span to function
  • Must gracefully handle absence of active span
  • Limited to span lifetime and context.
| +| **Event Logging** |
  • Works independently without active spans
  • Aligns with OpenTelemetry's emerging direction
  • Suitable for environments without tracing
  • Simpler implementation model
|
  • Requires an event exporter to be configured
  • Processed and stored separately from spans
  • Event logging standards still evolving
| +| **Standalone Spans** |
  • Distributed traces contain every evaluation
  • Detailed timing information
  • Full span lifecycle control
|
  • Creates one span per evaluation
  • May clutter trace visualizations
  • Increased overhead and resource usage
  • Potential performance impact at scale
  • More complex implementation
| > [!NOTE] > While span events are recommended for their low overhead and ease of use, OpenTelemetry is trending toward using log-based events instead of span events. Please refer to the [OpenTelemetry Span Event Deprecation Plan][otel-span-event-deprecation-plan] for more details. From 93ab0d29d3cf73524eb2260417eb9356515c67ff Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Thu, 18 Dec 2025 14:02:53 -0500 Subject: [PATCH 3/3] Add allowed elements for markdown linting Signed-off-by: Michael Beemer --- .markdownlint.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.markdownlint.yml b/.markdownlint.yml index d130710e..5782c066 100644 --- a/.markdownlint.yml +++ b/.markdownlint.yml @@ -4,6 +4,9 @@ MD033: allowed_elements: - summary - details + - br + - li + - ul MD024: siblings_only: true MD025: