New documentation: https://matrix-org.github.io/dendrite/

docs/tracing/opentracing.md

@@ -1,5 +1,11 @@
-Opentracing
-===========
+---
+title: OpenTracing
+has_children: true
+parent: Development
+permalink: /development/opentracing
+---
+
+# OpenTracing
 
 Dendrite extensively uses the [opentracing.io](http://opentracing.io) framework
 to trace work across the different logical components.
@@ -23,7 +29,6 @@ This is useful to see where the time is being spent processing a request on a
 component. However, opentracing allows tracking of spans across components. This
 makes it possible to see exactly what work goes into processing a request:
 
-
 ```
 Component 1       |<─────────────────── HTTP ────────────────────>|
                      |<──────────────── RPC ─────────────────>|
@@ -39,7 +44,6 @@ deserialized span as the parent).
 
 A collection of spans that are related is called a trace.
 
-
 Spans are passed through the code via contexts, rather than manually. It is
 therefore important that all spans that are created are immediately added to the
 current context. Thankfully the opentracing library gives helper functions for
@@ -53,11 +57,11 @@ defer span.Finish()
 This will create a new span, adding any span already in `ctx` as a parent to the
 new span.
 
-
 Adding Information
 ------------------
 
 Opentracing allows adding information to a trace via three mechanisms:
+
 - "tags" ─ A span can be tagged with a key/value pair. This is typically
   information that relates to the span, e.g. for spans created for incoming HTTP
   requests could include the request path and response codes as tags, spans for
@@ -69,12 +73,10 @@ Opentracing allows adding information to a trace via three mechanisms:
   inspecting the traces, but can be used to add context to logs or tags in child
   spans.
 
-
 See
 [specification.md](https://github.com/opentracing/specification/blob/master/specification.md)
 for some of the common tags and log fields used.
 
-
 Span Relationships
 ------------------
 
@@ -86,7 +88,6 @@ A second relation type is `followsFrom`, where the parent has no dependence on
 the child span. This usually indicates some sort of fire and forget behaviour,
 e.g. adding a message to a pipeline or inserting into a kafka topic.
 
-
 Jaeger
 ------
 
@@ -99,6 +100,7 @@ giving a UI for viewing and interacting with traces.
 To enable jaeger a `Tracer` object must be instansiated from the config (as well
 as having a jaeger server running somewhere, usually locally). A `Tracer` does
 several things:
+
 - Decides which traces to save and send to the server. There are multiple
   schemes for doing this, with a simple example being to save a certain fraction
   of traces.

docs/tracing/setup.md

@@ -1,14 +1,20 @@
-## OpenTracing Setup
+---
+title: Setup
+parent: OpenTracing
+grand_parent: Development
+permalink: /development/opentracing/setup
+---
 
-![Trace when sending an event into a room](/docs/tracing/jaeger.png)
+# OpenTracing Setup
 
 Dendrite uses [Jaeger](https://www.jaegertracing.io/) for tracing between microservices.
 Tracing shows the nesting of logical spans which provides visibility on how the microservices interact.
 This document explains how to set up Jaeger locally on a single machine.
 
-### Set up the Jaeger backend
+## Set up the Jaeger backend
 
 The [easiest way](https://www.jaegertracing.io/docs/1.18/getting-started/) is to use the all-in-one Docker image:
+
 ```
 $ docker run -d --name jaeger \
   -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
@@ -23,9 +29,10 @@ $ docker run -d --name jaeger \
   jaegertracing/all-in-one:1.18
 ```
 
-### Configuring Dendrite to talk to Jaeger
+## Configuring Dendrite to talk to Jaeger
 
 Modify your config to look like: (this will send every single span to Jaeger which will be slow on large instances, but for local testing it's fine)
+
 ```
 tracing:
   enabled: true
@@ -40,10 +47,11 @@ tracing:
 ```
 
 then run the monolith server with `--api true` to use polylith components which do tracing spans:
+
 ```
-$ ./dendrite-monolith-server --tls-cert server.crt --tls-key server.key --config dendrite.yaml --api true
+./dendrite-monolith-server --tls-cert server.crt --tls-key server.key --config dendrite.yaml --api true
 ```
 
-### Checking traces
+## Checking traces
 
-Visit http://localhost:16686 to see traces under `DendriteMonolith`.
+Visit <http://localhost:16686> to see traces under `DendriteMonolith`.