From 91525e0d5c84f5416dfff032d95f26575643a2b0 Mon Sep 17 00:00:00 2001
From: Mafer Rodriguez <119091615+MaferRod@users.noreply.github.com>
Date: Sun, 5 Jan 2025 02:42:23 -0600
Subject: [PATCH 1/3] Spanish Translation for tracing.md

---
 docs/advanced/tracing.es.md | 85 +++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 docs/advanced/tracing.es.md

diff --git a/docs/advanced/tracing.es.md b/docs/advanced/tracing.es.md
new file mode 100644
index 000000000..eb7997834
--- /dev/null
+++ b/docs/advanced/tracing.es.md
@@ -0,0 +1,85 @@
+# Rastreo
+
+El rastreo (Tracing) es una herramienta poderosa para monitorear y depurar sistemas distribuidos. La API de rastreo (Tracing) de Vapor permite a los desarrolladores rastrear facilmente los ciclos de vida de las solicitudes, propagar metadatos e integrarse con backends populares como OpenTelemetry.
+
+La API de rastreo (Tracing) de Vapor se basa en [swift-distributed-tracing](https://github.com/apple/swift-distributed-tracing), esto quiere decir que es compatible con todas las [implementaciones de backend ](https://github.com/apple/swift-distributed-tracing/blob/main/README.md#tracing-backends) de swift-distributed-tracing.
+
+Si no estas familiarizado con tracing y spans en Swift, revise la [documentación de OpenTelemetry Trace](https://opentelemetry.io/docs/concepts/signals/traces/) y la [documentación de swift-distributed-tracing](https://swiftpackageindex.com/apple/swift-distributed-tracing/main/documentation/tracing).
+
+## TracingMiddleware
+
+Para crear automaticamente un span completamente anotado para cada solicitud, agrega el `TracingMiddleware` a tu aplicación.
+
+```swift
+app.middleware.use(TracingMiddleware())
+```
+
+Para obtener mediciones precisas de los spans y asegurarte de que los identificadores de rastreo se pasen correctamente a otros sercvicios, añade este middleware antes que otros middlewares.
+
+## Añadiendo Spans
+
+Cuando se añaden spans a los manejadores de rutas, es ideal que estén asociados con el span de solicitud de nivel superior. Esto se conoce como 'propagación de spans' y se puede manejar de dos maneras diferentes: automática o manual
+
+### Propagación Automática
+
+Vapor tiene soporte para propagar automáticamente spans entre middleware y callbacks de rutas. Para hacerlo, establece la propiedad `Application.traceAutoPropagation` en true durante la configuración.
+
+```swift
+app.traceAutoPropagation = true
+```
+
+!!! nota
+     Habilitar la auto-propagación puede degradar el rendimiento en APIs de alto rendimiento con necesidades mínimas de rastreo, ya que los metadatos del span de solicitud deben restaurarse para cada manejador de rutas, independientemente de si se crean spans o no.
+
+
+Entonces, los spans pueden crearse en el cierre de la ruta utilizando la sintaxis ordinaria de rastreo distribuido.
+
+```swift
+app.get("fetchAndProcess") { req in
+    let result = try await fetch()
+    return try await withSpan("getNameParameter") { _ in
+        try await process(result)
+    }
+}
+```
+
+### Propagación Manual 
+
+Para evitar las implicaciones de rendimiento de la propagación automática, puedes restaurar manualmente los metadatos del span donde sea necesario. `TracingMiddleware` establece automáticamente una propiedad `Request.serviceContext` que puede usarse directamente en el parámetro `context` de `withSpan`.
+
+```swift
+app.get("fetchAndProcess") { req in
+    let result = try await fetch()
+    return try await withSpan("getNameParameter", context: req.serviceContext) { _ in
+        try await process(result)
+    }
+}
+```
+
+Para restaurar los metadatos del span sin crear un span, usa `ServiceContext.withValue`. Esto es valioso si sabes que las bibliotecas asíncronas posteriores emiten sus propios spans de rastreo, y estos deben estar anidados debajo del span de solicitud principal.
+
+
+```swift
+app.get("fetchAndProcess") { req in
+    try await ServiceContext.withValue(req.serviceContext) {
+        try await fetch()
+        return try await process(result)
+    }
+}
+```
+
+## Consideraciones de NIO 
+
+Debido a que `swift-distributed-tracing` usa [`propiedades TaskLocal`](https://developer.apple.com/documentation/swift/tasklocal) para propagar, debes restaurar manualmente el contexto cada vez que cruces los límites de `NIO EventLoopFuture` para asegurar que los spans estén vinculados correctamente. **Esto es necesario independientemente de si la propagación automática está habilitada**.
+
+```swift
+app.get("fetchAndProcessNIO") { req in
+    withSpan("fetch", context: req.serviceContext) { span in
+        fetchSomething().map { result in
+            withSpan("process", context: span.context) { _ in
+                process(result)
+            }
+        }
+    }
+}
+```

From 374bc868052dcde6f1a0ddf88805d8ab573483f5 Mon Sep 17 00:00:00 2001
From: Mafer Rodriguez <119091615+MaferRod@users.noreply.github.com>
Date: Mon, 13 Jan 2025 00:04:09 -0600
Subject: [PATCH 2/3] Apply suggestions from code review

Co-authored-by: TheHandyOwl <24987271+TheHandyOwl@users.noreply.github.com>
---
 docs/advanced/tracing.es.md | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/docs/advanced/tracing.es.md b/docs/advanced/tracing.es.md
index eb7997834..dc5790d70 100644
--- a/docs/advanced/tracing.es.md
+++ b/docs/advanced/tracing.es.md
@@ -2,7 +2,7 @@
 
 El rastreo (Tracing) es una herramienta poderosa para monitorear y depurar sistemas distribuidos. La API de rastreo (Tracing) de Vapor permite a los desarrolladores rastrear facilmente los ciclos de vida de las solicitudes, propagar metadatos e integrarse con backends populares como OpenTelemetry.
 
-La API de rastreo (Tracing) de Vapor se basa en [swift-distributed-tracing](https://github.com/apple/swift-distributed-tracing), esto quiere decir que es compatible con todas las [implementaciones de backend ](https://github.com/apple/swift-distributed-tracing/blob/main/README.md#tracing-backends) de swift-distributed-tracing.
+La API de rastreo (Tracing) de Vapor se basa en [swift-distributed-tracing](https://github.com/apple/swift-distributed-tracing), esto quiere decir que es compatible con todas las [implementaciones de backend](https://github.com/apple/swift-distributed-tracing/blob/main/README.md#tracing-backends) de swift-distributed-tracing.
 
 Si no estas familiarizado con tracing y spans en Swift, revise la [documentación de OpenTelemetry Trace](https://opentelemetry.io/docs/concepts/signals/traces/) y la [documentación de swift-distributed-tracing](https://swiftpackageindex.com/apple/swift-distributed-tracing/main/documentation/tracing).
 
@@ -28,11 +28,10 @@ Vapor tiene soporte para propagar automáticamente spans entre middleware y call
 app.traceAutoPropagation = true
 ```
 
-!!! nota
-     Habilitar la auto-propagación puede degradar el rendimiento en APIs de alto rendimiento con necesidades mínimas de rastreo, ya que los metadatos del span de solicitud deben restaurarse para cada manejador de rutas, independientemente de si se crean spans o no.
+!!! note "Nota"
+    Habilitar la auto-propagación puede degradar el rendimiento en APIs de alto rendimiento con necesidades mínimas de rastreo, ya que los metadatos del span de solicitud deben restaurarse para cada manejador de rutas, independientemente de si se crean spans o no.
 
-
-Entonces, los spans pueden crearse en el cierre de la ruta utilizando la sintaxis ordinaria de rastreo distribuido.
+Entonces, los spans pueden crearse en el closure de la ruta utilizando la sintaxis habitual de rastreo distribuido.
 
 ```swift
 app.get("fetchAndProcess") { req in
@@ -58,7 +57,6 @@ app.get("fetchAndProcess") { req in
 
 Para restaurar los metadatos del span sin crear un span, usa `ServiceContext.withValue`. Esto es valioso si sabes que las bibliotecas asíncronas posteriores emiten sus propios spans de rastreo, y estos deben estar anidados debajo del span de solicitud principal.
 
-
 ```swift
 app.get("fetchAndProcess") { req in
     try await ServiceContext.withValue(req.serviceContext) {

From 3c7c6ead718fafcdde7f284c2f77b13eb20145a2 Mon Sep 17 00:00:00 2001
From: Mafer Rodriguez <119091615+MaferRod@users.noreply.github.com>
Date: Tue, 14 Jan 2025 18:04:53 -0600
Subject: [PATCH 3/3] Changing "Rastreo" to "Tracing"

---
 docs/advanced/tracing.es.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/advanced/tracing.es.md b/docs/advanced/tracing.es.md
index dc5790d70..bedb864d2 100644
--- a/docs/advanced/tracing.es.md
+++ b/docs/advanced/tracing.es.md
@@ -1,4 +1,4 @@
-# Rastreo
+# Tracing
 
 El rastreo (Tracing) es una herramienta poderosa para monitorear y depurar sistemas distribuidos. La API de rastreo (Tracing) de Vapor permite a los desarrolladores rastrear facilmente los ciclos de vida de las solicitudes, propagar metadatos e integrarse con backends populares como OpenTelemetry.