Brave backend docs

2 files changed, 31 insertions, 1 deletions

diff --git a/docs/backends/brave.rst b/docs/backends/brave.rst
new file mode 100644
index 0000000..a71db00
--- /dev/null
+++ b/docs/backends/brave.rst
@@ -0,0 +1,26 @@
+.. _brave:
+
+brave backend
+=============
+
+To use, add the following dependency to your project::
+
+  "com.softwaremill.sttp" %% "brave-backend" % "1.1.5"
+
+This backend depends on `brave <https://github.com/openzipkin/brave>`_, a distributed tracing implementation compatible with Zipkin backend services.
+
+The brave backend wraps any other backend, and needs an instance of brave's ``HttpTracing`` or ``Tracing``, for example::
+
+  val httpTracing: HttpTracing = ...
+  implicit val sttpBackend = BraveBackend(AkkaHttpBackend(), httpTracing)
+
+The backend obtains the current trace context using default Brave's propagation mechanisms. As it's often challenging to integrate context propagation in an asynchronous setting, there's also a possibility to add the trace context to the request's tags::
+
+  import com.softwaremill.sttp.brave.BraveBackend._
+
+  val parent: TraceContext = ...
+
+  sttp
+    .get(...)
+    .tagWithTraceContext(parent))
+
diff --git a/docs/backends/summary.rst b/docs/backends/summary.rst
index 72b20c9..d648c73 100644
--- a/docs/backends/summary.rst
+++ b/docs/backends/summary.rst
@@ -3,7 +3,7 @@
 Supported backends
 ==================
 
-sttp suports a number of synchornous and asynchronous backends. It's the backends that take care of managing connections, sending requests and receiving responses: sttp defines only the API to describe the requests to be send and handle the response data. It's the backends where all the heavy-lifting is done.
+sttp suports a number of synchronous and asynchronous backends. It's the backends that take care of managing connections, sending requests and receiving responses: sttp defines only the API to describe the requests to be send and handle the response data. It's the backends where all the heavy-lifting is done.
 
 Choosing the right backend depends on a number of factors: if you are using sttp to explore some data, or is it a production system; are you using a synchronous, blocking architecture or an asynchronous one; do you work mostly with Scala's ``Future``, or maybe you use some form of a ``Task`` abstraction; finally, if you want to stream requests/responses, or not.
 
@@ -30,3 +30,7 @@ Class                            Response wrapper             Supported stream t
 ``OkHttpMonixBackend``           ``monix.eval.Task``          ``monix.reactive.Observable[ByteBuffer]``
 ================================ ============================ ================================================
 
+There are also backends which wrap other backends to provide additional functionality. These include:
+
+* ``TryBackend``, which safely wraps any exceptions thrwon by a synchronous backend in ``scala.util.Try``
+* ``BraveBackend``, for Zipkin-compatible distributed tracing. See the :ref:`dedicated section <brave>`.
\ No newline at end of file