From 34235a45e43489c3f3f744589c1c7e6dd7c410b0 Mon Sep 17 00:00:00 2001
From: Jorik Schellekens <joriks@matrix.org>
Date: Tue, 25 Jun 2019 18:24:38 +0100
Subject: [PATCH] Better opentracing config comment

---
 docs/sample_config.yaml  | 20 +++++++++++---------
 synapse/config/tracer.py | 12 +++++++++---
 2 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/docs/sample_config.yaml b/docs/sample_config.yaml
index 5861861c61..6fb9313db3 100644
--- a/docs/sample_config.yaml
+++ b/docs/sample_config.yaml
@@ -1354,16 +1354,18 @@ password_config:
 #    example_option: 'things'
 
 
-## Tracer ##
+## Opentracing ##
+# These settings enable opentracing which implements distributed tracing
+# This allows you to observe the causal chain of events across servers 
+# including requests, key lookups etc. across any server running
+# synapse or any other other services which supports opentracing.
+# (specifically those implemented with jaeger)
 
-#tracer:
+#opentracing:
 #  # Enable / disable tracer
 #  tracer_enabled: false
-#  # The list of users who's requests will be traced
-#  # The list is a list of regex which is matched against the user_id
-#  user_whitelist:
-#    - "*"
-#  # The list of homeservers we wish to trace across
-#  # The list is a list of regex which is matched against the homeserver name
+#  # The list of homeservers we wish to expose our current traces to.
+#  # The list is a list of regexes which are matched against the
+#  # servername of the homeserver
 #  homeserver_whitelist:
-#    - "*"
+#    - ".*"
diff --git a/synapse/config/tracer.py b/synapse/config/tracer.py
index 506b2afae7..76fa5b8920 100644
--- a/synapse/config/tracer.py
+++ b/synapse/config/tracer.py
@@ -44,14 +44,20 @@ class TracerConfig(Config):
     def generate_config_section(cls, **kwargs):
         return """\
         ## Opentracing ##
+        # These settings enable opentracing which implements distributed tracing
+        # This allows you to observe the causal chain of events across servers 
+        # including requests, key lookups etc. across any server running
+        # synapse or any other other services which supports opentracing.
+        # (specifically those implemented with jaeger)
 
         #opentracing:
         #  # Enable / disable tracer
         #  tracer_enabled: false
-        #  # The list of homeservers we wish to trace across
-        #  # The list is a list of regex which is matched against the homeserver name
+        #  # The list of homeservers we wish to expose our current traces to.
+        #  # The list is a list of regexes which are matched against the
+        #  # servername of the homeserver
         #  homeserver_whitelist:
-        #    - "*"
+        #    - ".*"
         """