[GitHub] [couchdb] ksnavely commented on a change in pull request #2286: Opentracing

[GitBox <gi...@apache.org>]

ksnavely commented on a change in pull request #2286: Opentracing
URL: https://github.com/apache/couchdb/pull/2286#discussion_r346053103
 
 

 ##########
 File path: src/ctrace/README.md
 ##########
 @@ -0,0 +1,308 @@
+Overview
+========
+
+This application provides an interface to opentracing compatible
+tracing systems.
+
+Open Tracing
+------------
+
+[//]: # (taken from https://github.com/opentracing/specification/blob/master/specification.md)
+Traces in OpenTracing are defined implicitly by their Spans.
+In particular, a Trace can be thought of as a directed acyclic
+graph (DAG) of Spans, where the edges between Spans are called
+References.
+
+Each Span encapsulates the following state:
+
+- An operation name
+- A start timestamp
+- A finish timestamp
+- A set of zero or more key:value Span Tags.
+- A set of zero or more Span Logs, each of which is
+  itself a key:value map paired with a timestamp.
+- A SpanContext
+- References to zero or more causally-related Spans
+
+Every trace is identified by unique trace_id.
+Every trace includes zero or more tracing spans.
+Which are identified by span id.
+
+Jaeger
+------
+
+Jaeger is a distributed tracing system released as open source by Uber Technologies.
+It is one of implementations of open tracing specification.
+Jaeger supports Trace detail view where a single trace is represented as
+a tree of tracing span with detailed timing information about every span.
+In order to make this feature work all tracing spans should form a lineage
+from the same root span.
+
+
+
+Implementation
+==============
+
+Every operation has unique identifier. Example identifiers are:
+
+- all-dbs.read
+- database.delete
+- replication.trigger
+- view.compaction
+
+The tracing begins with sampling. We don't do anything if
+sampler is not configured for a given operation.
+
+For every operation we start a separate tracing filter process.
+This process receieve spans when `ctrace:finish_span` is called.
+The filtering processes are named after operation name.
+
+Every filtering process has a number of filtering rules.
+The first rule matching the conditions of a given span would be selected.
+Every rule has a list of actions to execute on given span.
+
+Currently we only support `report`. In the future we might support following:
+
+- report
+- count
+- sample = probability (float)
+
+When the rule is selected and it has `report` action we forward the span to
+`reporter` process. Reporter process encodes the span and sends it to jaeger.
+
+Span pipeline
+-------------
+
++-------+       +------+       +--------+       +------+
+|sampler| ----> |filter| ----> |reporter| ----> |jaeger|
++-------+       +------+       +--------+       +------+
+
+- sampler - adds filtering rules into span and does prefiltering
+- filter - uses filtering rules to decide if it needs to forward span
+- reporter - sends span to jaeger
+
+Code instrumentation
+--------------------
+
+The span lifecycle is controled by
+
+- `ctrace:start_span`
+- `ctrace:finish_span`
+
+The instrumentation can add tags and logs to a span. In some cases we
+embed span in other structures. Therefore to avoid confussion we don't 
+use term `span` and use `subject` instead. Currently we support `#httpd{}`
+record and `db` as subjects.
+
+Example of instrumentation:
+```
+HttpReq2 = ctrace:trace(HttpReq1, fun(S0) ->
+    S1 = ctrace:tag(S0, #{
+        peer => Peer,
+        'http.method' => Method,
+        nonce => Nonce,
+        'http.url' => Path,
+        'span.kind' => <<"server">>,
+        component => <<"couchdb.chttpd">>
+    }),
+    ctrace:log(S1, #{
+        field0 => "value0"
+    })
+end``1),
+```
+
+As you can see the `ctrace:trace/2` function receives a function which
+operates on the span. The functions that can be on span are:
+
+- `ctrace:tag/2` to add new tags to the span
+- `ctrace:set_operation_name/2` sometimes operation name is
+  not available when span is started. This function let
+  us set the name latter.
+- `ctrace:log/2` add log event to the span
+
+There are some informative functions as well:
+
+- `ctrace:refs/1` - returns all other spans we have references from the current
+- `ctrace:operation_name/1` - returns operation name for the current span
+- `ctrace:trace_id/1` - returns trace id for the current span
+- `ctrace:span_id/1` - returns span id for the current span
+
+Instrumentation guide
+---------------------
+
+- Start root span at system boundaries
+  - httpd
+  - internal trigger (replication or compaction jobs)
+- Start new child span when you cross layer boundaries
+- Start new child span when you cross node bounadary
+- Extend `<app>_httpd_handlers:handler_info/1` as needed to
+  have operation ids. (We as community might need to work on
+  naming conventions)
+- Use `ctrace:new_request_ctx` to pass additional information
+  about request.
+- Update layers to pass `request_ctx` as needed (not done for jobs).
+- Use [span conventions](https://github.com/apache/couchdb-documentation/blob/master/rfcs/011-opentracing.md#conventions) https://github.com/opentracing/specification/blob/master/semantic_conventions.md
+- When in doubt consult open tracing spec
+  - [spec overview](https://github.com/opentracing/specification/blob/master/specification.md)
+  - [conventions](https://github.com/opentracing/specification/blob/master/semantic_conventions.md#standard-span-tags-and-log-fields)
+
+Configuration
+-------------
+
+The tracers are configured using standard CouchDB ini files
+based configuration. There is a global toggle
+`[tracing]->'enabled' = false` which enables the tracing.
+The samplers are configured in a `[tracing.samplers]` section, which
+specifies the sampler to use for given tracer. If sampler is not
+configured the spans for a given operation are droped. Every sampler
+must have a corespondent filter section. The naming convention is:
+`[tracing.OperationId]`. For security reasons `[tracing.OperationId]`
+is not available via HTTP endpoint. Administrator can toggle tracing
+with predefined rules for specific operation by setting a correspondent
+sampler to either `none` or `all`.
+The keys in filter section are irrelevant and used only for ordering
+purpose. The rules are processed in the alphabetical order. We use a
+DSL for defining rules. The DSL has following structure:
+```
+( #{<[arguments]>} ) when <[conditions]> -> <[actions]>
+```
+
+Where:
+ - arguments is comma separated pairs of
+   `<tag_or_field_name> := <variable_name>`
+ - actions is a list which contains
+   - `report`
+ - conditions
+   - `<[condition]>`
+   - `| <[condition]> <[operator]> <[condition]>`
+ - condition:
+   - `<variable_name> <[operator]> <value>`
+     `| <[guard_function]>(<[variable_name]>)`
+ - `variable_name` - lowercase name without special characters
+ - guarg_function: one of
 
 Review comment:
   Typo, "guard"

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services