From b07403bfe0df4b0567163600da9d232eed1b95f3 Mon Sep 17 00:00:00 2001 From: Jorik Schellekens Date: Fri, 26 Jul 2019 17:43:24 +0100 Subject: [PATCH 1/6] Update opentracing doc to reflect module changes - trace and trace_deferred are now one method - add doc for tag_args --- synapse/logging/opentracing.py | 63 +++++++++++++++++++++------------- 1 file changed, 39 insertions(+), 24 deletions(-) diff --git a/synapse/logging/opentracing.py b/synapse/logging/opentracing.py index d2c209c471fa..35775d4a5ebc 100644 --- a/synapse/logging/opentracing.py +++ b/synapse/logging/opentracing.py @@ -43,6 +43,9 @@ an optional dependency. This does however limit the number of modifiable spans at any point in the code to one. From here out references to `opentracing` in the code snippets refer to the Synapses module. +Most methods provided in the module have a direct correlation to those provided +by opentracing. Refer to docs there for a more in-depth documentation on some of +the args and methods. Tracing ------- @@ -68,52 +71,64 @@ Tracing functions ----------------- -Functions can be easily traced using decorators. There is a decorator for -'normal' function and for functions which are actually deferreds. The name of +Functions can be easily traced using decorators. The name of the function becomes the operation name for the span. .. code-block:: python - from synapse.logging.opentracing import trace, trace_deferred + from synapse.logging.opentracing import trace - # Start a span using 'normal_function' as the operation name + # Start a span using 'interesting_function' as the operation name @trace - def normal_function(*args, **kwargs): + def interesting_function(*args, **kwargs): # Does all kinds of cool and expected things return something_usual_and_useful - # Start a span using 'deferred_function' as the operation name - @trace_deferred - @defer.inlineCallbacks - def deferred_function(*args, **kwargs): - # We start - yield we_wait - # we finish - return something_usual_and_useful Operation names can be explicitly set for functions by using -``trace_using_operation_name`` and -``trace_deferred_using_operation_name`` +``trace_using_operation_name`` .. code-block:: python from synapse.logging.opentracing import ( trace_using_operation_name, - trace_deferred_using_operation_name ) @trace_using_operation_name("A *much* better operation name") - def normal_function(*args, **kwargs): + def interesting_badly_named_function(*args, **kwargs): # Does all kinds of cool and expected things return something_usual_and_useful - @trace_deferred_using_operation_name("Another exciting operation name!") - @defer.inlineCallbacks - def deferred_function(*args, **kwargs): - # We start - yield we_wait - # we finish - return something_usual_and_useful +Setting Tags +------------ + +To set a tag on the active span do + +.. code-block:: python + + from synapse.logging.opentracing import set_tag + + opentracing.set_tag(tag_name, tag_value) + +There's a convenient decorator to tag all the args of the method. It uses +inspection in order to use the formal parameter names prefixed with 'ARG_' as +tag names. It uses kwarg names as tag names without the prefix. + +.. code-block:: python + + from synapse.logging.opentracing import tag_args + + @tag_args + def set_fates(clotho, lachesis, atropos, father="Zues", mother="Themis"): + pass + + set_fates("the story", "the end", "the act") + # This will have the following tags + # - ARG_clotho: "the story" + # - ARG_lachesis: "the end" + # - ARG_atropos: "the act" + # - father: "Zues" + # - mother: "Themis" Contexts and carriers --------------------- From dc8f6f5c21d07813cd39c3da009be53cbd85992a Mon Sep 17 00:00:00 2001 From: Jorik Schellekens Date: Fri, 26 Jul 2019 17:52:28 +0100 Subject: [PATCH 2/6] newsfile --- changelog.d/5776.misc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/5776.misc diff --git a/changelog.d/5776.misc b/changelog.d/5776.misc new file mode 100644 index 000000000000..f34adc2b6657 --- /dev/null +++ b/changelog.d/5776.misc @@ -0,0 +1 @@ +Remove references to trace_deferred in opetnracing docs. From feabd4e4cac5a5e843d94ac84ca7e7c54a0f4fcb Mon Sep 17 00:00:00 2001 From: Jorik Schellekens Date: Mon, 5 Aug 2019 11:26:12 +0100 Subject: [PATCH 3/6] Always import opentracing as opentracing. --- synapse/logging/opentracing.py | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/synapse/logging/opentracing.py b/synapse/logging/opentracing.py index 35775d4a5ebc..2c3c30f25f99 100644 --- a/synapse/logging/opentracing.py +++ b/synapse/logging/opentracing.py @@ -57,9 +57,9 @@ .. code-block:: python - from synapse.logging.opentracing import start_active_span + import synapse.logging.opentracing as opentracing - with start_active_span("operation name"): + with opentracing.start_active_span("operation name"): # Do something we want to tracer Forgetting to enter or exit a scope will result in some mysterious and grievous log @@ -76,10 +76,10 @@ .. code-block:: python - from synapse.logging.opentracing import trace + import synapse.logging.opentracing as opentracing # Start a span using 'interesting_function' as the operation name - @trace + @opentracing.trace def interesting_function(*args, **kwargs): # Does all kinds of cool and expected things return something_usual_and_useful @@ -90,11 +90,9 @@ def interesting_function(*args, **kwargs): .. code-block:: python - from synapse.logging.opentracing import ( - trace_using_operation_name, - ) + import synapse.logging.opentracing as opentracing - @trace_using_operation_name("A *much* better operation name") + @opentracing.trace_using_operation_name("A *much* better operation name") def interesting_badly_named_function(*args, **kwargs): # Does all kinds of cool and expected things return something_usual_and_useful @@ -106,7 +104,7 @@ def interesting_badly_named_function(*args, **kwargs): .. code-block:: python - from synapse.logging.opentracing import set_tag + import synapse.logging.opentracing as opentracing opentracing.set_tag(tag_name, tag_value) @@ -116,9 +114,9 @@ def interesting_badly_named_function(*args, **kwargs): .. code-block:: python - from synapse.logging.opentracing import tag_args - - @tag_args + import synapse.logging.opentracing as opentracing + + @opentracing.tag_args def set_fates(clotho, lachesis, atropos, father="Zues", mother="Themis"): pass From f8b403142f2a9c446e5ae2801b644f55d392e411 Mon Sep 17 00:00:00 2001 From: Jorik Schellekens Date: Mon, 5 Aug 2019 11:53:21 +0100 Subject: [PATCH 4/6] Trailing whitespace --- synapse/logging/opentracing.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/synapse/logging/opentracing.py b/synapse/logging/opentracing.py index 2c3c30f25f99..1f2e39d3ec41 100644 --- a/synapse/logging/opentracing.py +++ b/synapse/logging/opentracing.py @@ -115,7 +115,7 @@ def interesting_badly_named_function(*args, **kwargs): .. code-block:: python import synapse.logging.opentracing as opentracing - + @opentracing.tag_args def set_fates(clotho, lachesis, atropos, father="Zues", mother="Themis"): pass From 2708728b33fbcaf60e5c3b4efc673e5446e07220 Mon Sep 17 00:00:00 2001 From: Jorik Schellekens Date: Fri, 16 Aug 2019 18:45:38 +0100 Subject: [PATCH 5/6] Import style --- synapse/logging/opentracing.py | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/synapse/logging/opentracing.py b/synapse/logging/opentracing.py index 1f2e39d3ec41..6b706e189282 100644 --- a/synapse/logging/opentracing.py +++ b/synapse/logging/opentracing.py @@ -57,9 +57,9 @@ .. code-block:: python - import synapse.logging.opentracing as opentracing + from synapse.logging.opentracing import start_active_span - with opentracing.start_active_span("operation name"): + with start_active_span("operation name"): # Do something we want to tracer Forgetting to enter or exit a scope will result in some mysterious and grievous log @@ -76,10 +76,10 @@ .. code-block:: python - import synapse.logging.opentracing as opentracing + from synapse.logging.opentracing import trace # Start a span using 'interesting_function' as the operation name - @opentracing.trace + @trace def interesting_function(*args, **kwargs): # Does all kinds of cool and expected things return something_usual_and_useful @@ -90,9 +90,9 @@ def interesting_function(*args, **kwargs): .. code-block:: python - import synapse.logging.opentracing as opentracing + from synapse.logging.opentracing import trace_using_operation_name - @opentracing.trace_using_operation_name("A *much* better operation name") + @trace_using_operation_name("A *much* better operation name") def interesting_badly_named_function(*args, **kwargs): # Does all kinds of cool and expected things return something_usual_and_useful @@ -104,9 +104,9 @@ def interesting_badly_named_function(*args, **kwargs): .. code-block:: python - import synapse.logging.opentracing as opentracing + from synapse.logging.opentracing import set_tag - opentracing.set_tag(tag_name, tag_value) + set_tag(tag_name, tag_value) There's a convenient decorator to tag all the args of the method. It uses inspection in order to use the formal parameter names prefixed with 'ARG_' as @@ -114,9 +114,9 @@ def interesting_badly_named_function(*args, **kwargs): .. code-block:: python - import synapse.logging.opentracing as opentracing + from synapse.logging.opentracing import tag_args - @opentracing.tag_args + @tag_args def set_fates(clotho, lachesis, atropos, father="Zues", mother="Themis"): pass From 5cfa9a057705b643879ed6bc43f4f622ae0b7c31 Mon Sep 17 00:00:00 2001 From: Jorik Schellekens Date: Fri, 16 Aug 2019 18:47:40 +0100 Subject: [PATCH 6/6] Update 5776.misc --- changelog.d/5776.misc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog.d/5776.misc b/changelog.d/5776.misc index f34adc2b6657..1fb1b9c15295 100644 --- a/changelog.d/5776.misc +++ b/changelog.d/5776.misc @@ -1 +1 @@ -Remove references to trace_deferred in opetnracing docs. +Update opentracing docs to use the unified `trace` method.