From 3d1788083122be49dcd0f645fcd6e29bd3b83fde Mon Sep 17 00:00:00 2001
From: Shane Myrick <mail@shanemyrick.com>
Date: Tue, 11 Jun 2024 12:26:37 -0700
Subject: [PATCH] [docs] Add docs about span macros (#4918)

Co-authored-by: Edward Huang <edhuang@gmail.com>
---
 docs/source/customizations/native.mdx | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/docs/source/customizations/native.mdx b/docs/source/customizations/native.mdx
index b297cb1670..98ebacf53b 100644
--- a/docs/source/customizations/native.mdx
+++ b/docs/source/customizations/native.mdx
@@ -245,17 +245,17 @@ plugins:
     # Any values here are passed to the plugin as part of your configuration
 ```
 
-## Add custom metrics
+## Using macros
+To create custom metrics, traces, and spans, you can use [`tracing` macros](https://docs.rs/tracing/latest/tracing/index.html#macros) to generate events and logs.
 
+### Add custom metrics
 <Note>
 
 Make sure to [enable prometheus metrics](../configuration/telemetry/exporters/metrics/prometheus) in your configuration if you want to have metrics generated by the Router.
 
 </Note>
 
-### Using macros
-
-To create your custom metrics in [Prometheus](https://prometheus.io/) you can use the [tracing macros](https://docs.rs/tracing/latest/tracing/index.html#macros) to generate an event.
+To create your custom metrics in [Prometheus](https://prometheus.io/) you can use [event macros](https://docs.rs/tracing/latest/tracing/index.html#macros) to generate an event.
 If you observe a specific naming pattern for your event you'll be able to generate your own custom metrics directly in Prometheus.
 
 To publish a new metric, use tracing macros to generate an event that contains one of the following prefixes:
@@ -292,6 +292,22 @@ tracing::info!(
 );
 ```
 
+### Add custom spans
+<Note>
+
+Make sure to [enable OpenTelemetry tracing](../configuration/telemetry/exporters/tracing/overview) in your configuration if you want customize the traces generated and linked by the router.
+
+</Note>
+
+To create custom spans and traces you can use [`tracing` macros](https://docs.rs/tracing/latest/tracing/index.html#macros) to generate a span.
+
+```rust
+use tracing::info_span;
+
+info_span!("my_span");
+```
+
+
 ## Plugin Lifecycle
 
 Like individual requests, plugins follow their own strict lifecycle that helps provide structure to the Apollo Router's execution.