Merge pull request #559 from future-agi/fix/rewrite-tracing-integrate

rewrite manual tracing integrate event exception and status

Author: hadarishav

src/pages/docs/observe/features/manual-tracing/add-events-exceptions-status.mdx

@@ -3,19 +3,21 @@ title: "Integrate Events, Exceptions, and Status into Spans"
 description: "OpenTelemetry (OTEL) provides support for adding Events, Exceptions, and Status into spans."
 ---
 
-## What it is
+## About
 
-**Events, Exceptions, and Status** are three OpenTelemetry primitives for enriching spans with runtime signal:
+Spans capture timing and attributes, but they do not automatically record what happened during execution or whether it succeeded. Events, exceptions, and status fill that gap.
 
-- **Events** — Readable messages that mark significant moments during a span's lifecycle, similar to basic logs.
-- **Status** — A success or failure indicator set on the span to surface errors in distributed traces.
-- **Exceptions** — Detailed exception records attached to a span alongside a status update, for comprehensive failure debugging.
+- **Events**: Timestamped messages that mark key moments during a span, similar to log lines.
+- **Status**: Marks the span as OK or ERROR so failures are visible in the dashboard and alerting.
+- **Exceptions**: Attaches full error details (type, message, stack trace) to the span for debugging.
 
-## Use cases
+---
+
+## When to use
 
-- **Event logging** — Capture significant actions in your application's workflow at specific moments during span execution.
-- **Error surfacing** — Assign an error status to a span when an exception arises so it's visible when identifying and troubleshooting issues in distributed systems.
-- **Exception recording** — Log detailed exception information alongside span status to get a full view of failures for debugging.
+- **Mark key moments during execution**: Add events at important steps (e.g. "cache miss", "retrying request") to understand what happened inside a span without creating child spans.
+- **Surface errors in traces**: Set an ERROR status on a span so failures are immediately visible when scanning traces in the dashboard.
+- **Capture full failure context**: Record exceptions alongside status so the error type, message, and stack trace are available for debugging.
 
 ---
 
@@ -52,7 +54,7 @@ description: "OpenTelemetry (OTEL) provides support for adding Events, Exception
         // Execute the operation
         // For example: const result = someOperation();
 
-        currentSpan.add_event("Operation completed!");
+        currentSpan.addEvent("Operation completed!");
     }
     ```
 
@@ -157,14 +159,14 @@ description: "OpenTelemetry (OTEL) provides support for adding Events, Exception
 
 ## Key concepts
 
-- **`add_event()` / `addEvent()`** — Attaches a timestamped message to the span at the moment it's called. Useful for logging discrete actions without creating a new span.
-- **`set_status()` / `setStatus()`** — Sets the span's status to `OK` or `ERROR`. An `ERROR` status with a message surfaces the failure in trace UIs and alerting.
-- **`record_exception()` / `recordException()`** — Attaches full exception details (type, message, stack trace) as a span event. Always pair with `set_status(ERROR)` for complete failure context.
-- **`is_recording()`** — Guards against no-op spans. Always check before setting attributes or events on a span retrieved from `get_current_span()`.
+- **`add_event()` / `addEvent()`**:Attaches a timestamped message to the span at the moment it's called. Useful for logging discrete actions without creating a new span.
+- **`set_status()` / `setStatus()`**:Sets the span's status to `OK` or `ERROR`. An `ERROR` status with a message surfaces the failure in trace UIs and alerting.
+- **`record_exception()` / `recordException()`**:Attaches full exception details (type, message, stack trace) as a span event. Always pair with `set_status(ERROR)` for complete failure context.
+- **`is_recording()`**:Guards against no-op spans. Always check before setting attributes or events on a span retrieved from `get_current_span()`.
 
 ---
 
-## What you can do next
+## Next Steps
 
 <CardGroup cols={2}>
   <Card title="Set Up Tracing" icon="gear" href="/docs/observe/features/manual-tracing/set-up-tracing">