kocolosk commented on a change in pull request #440: RFC-011 : Opentracing support URL: https://github.com/apache/couchdb-documentation/pull/440#discussion_r324858608
########## File path: rfcs/011-opentracing.md ########## @@ -0,0 +1,233 @@ +--- +name: Opentracing support +about: Adopt industry standard distributed tracing solution +title: 'Opentracing support' +labels: rfc, discussion +assignees: '' + +--- + +Adopt an industry standard vendor-neutral APIs and instrumentation for distributed tracing. + +# Introduction + +Collecting profiling data is very tricky at the moment. +Developers have to run generic profiling tools which are not aware of CouchDB specifics. +This makes it hard to do the performance optimization work. We need a tool which would +allow us to get profiling data from specific points in the codebase. +This means code instrumentation. + +## Abstract + +There is an https://opentracing.io/ project, which is a vendor-neutral APIs and instrumentation +for distributed tracing. In Erlang it is implemented by one of the following libraries: + - [otters](https://github.com/project-fifo/otters) extended and more performant version of `otter` + - [opentracing-erlang](https://github.com/opentracing-contrib/opentracing-erlang) `otter` version donated to opentracing project. + - [original otter](https://github.com/Bluehouse-Technology/otter) + - [passage](https://github.com/sile/jaeger_passage) + +The opentracing philosophy is founded on three pillars: +- Low overhead: the tracing system should have a negligible performance impact on running services. +- Application-level transparency: programmers should not need to be aware of the tracing system +- Scalability + +The main addition is to include one of the above mentioned libraries and add instrumentation points into the codebase. +In initial implementation, there would be a new span started on every HTTP request. +The following HTTP headers would be used to link tracing span with application specific traces. +- X-B3-ParentSpanId +- X-B3-TraceId +- b3 + +More information about the use of these headers can be found [here](https://github.com/openzipkin/b3-propagation). +Open tracing [specification](https://github.com/opentracing/specification/blob/master/specification.md) +has a number of [conventions](https://github.com/opentracing/specification/blob/master/semantic_conventions.md) +which would be good to follow. + +In a nutshell the idea is: +- Take the reference to Parent span from one of the supported header and pass it to `span_start` call. +- Construct action name to use in `span_start` call. +- Call `span_start` from `httpd:handle_request_int/1`. +- Pass span in `#httpd{}` record +- Pass `trace_id` and `parend_span_id` through the stack (extend records if needed) +- Attach span tags to better identify trace events. +- Attach span logs at important instrumentation points. +- Forward spans to external service. + +## Requirements Language + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this +document are to be interpreted as described in +[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.txt). + +## Terminology + +- [span](https://github.com/opentracing/specification/blob/1.1/specification.md#the-opentracing-data-model): The "span" + is the primary building block of a distributed trace, representing an individual unit of work done in a distributed system. + 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 structured logs (key:value `Span Logs`). + - A `SpanContext` + - `References` to zero or more causally-related `Spans` + +--- + +# Detailed Description + +## Selection of a library + +As mentioned earlier, there are two flavours of libraries. None of them is perfect for all use cases. +The biggest differences in between `otters` and `passage` are: + +| | otters | passage | +| ------------------------------ | ----------- | ------------------------- | +| reporting protocol | http | udp | +| filtering | custom DSL | sampling callback module | +| reporter | zipkin only | jaeger or plugin | +| functional API | + | + | +| process dictionary | + | + | +| process based span storage | + | - | +| send event in batches | + | - | +| sender overload detection | - | + | +| report batches based on | timer | spans of single operation | +| design for performance | + | - | +| design for robustness at scale | - | + | +| counters | + | - | +| sampling based on duration | + | - | + +In order to allow future replacement of a tracing library it would be desirable to create an interface module `couch_trace`. +The `otters` library would be used for the first iteration. + +## Configuration + +The `otters` library uses application environment to store its configuration. +It also has a facility to compile filtering DSL into a beam module. +The filtering DSL looks like following: `<name>([<condition>]) -> <action>.`. +The safety of DSL compiler is unknown. Therefore a modification of tracing settings via configuration over HTTP wouldn't be possible. +The otter related section of the config `otter.filters` would be protected by BLACKLIST_CONFIG_SECTIONS. +The configuration of tracing would only be allowed from remsh or modification of the ini file. +The configuration for otter filters would be stored in couch_config as follows: +``` +[otter.filters] + +<name> = ([<condition>]) -> <action>. +``` + +## Tracing related HTTP headers + +Following headers on the request would be supported +- X-B3-ParentSpanId : 16 lower-hex characters +- X-B3-TraceId : 32 lower-hex characters +- X-B3-SpanId : 16 lower-hex characters +- b3 : {TraceId}-{SpanId}-{SamplingState}-{ParentSpanId} + - the `SamplingState` would be ignored + +Following headers on the response would be supported +- X-B3-ParentSpanId : 16 lower-hex characters +- X-B3-TraceId : 32 lower-hex characters +- X-B3-SpanId : 16 lower-hex characters + +## Conventions + +### Span tags + +| Span tag name | Type | Notes and examples | +| ---------------- | ------- | --------------------------------------------------- | +| component | string | couchdb.<app> (e.g. couchdb.chttpd, couchdb.fabric) | +| db.instance | string | for fdb-layer would be fdb connection string | +| db.type | string | for fdb-layer would be fdb | +| error | bool | `true` if operation failed | +| http.method | string | HTTP method of the request for the associated Span | +| http.status_code | integer | HTTP response status code for the associated Span | +| http.url | string | sanitized URL of the request in URI format | +| span.type | string | Either `client` or `server`. | +| account | string | Account name (reserved for future use) | +| user | string | Authenticated user name | +| db.name | string | Name of the accessed database | +| db.shard | string | Name of the accessed shard | Review comment: I can see where this is useful in 3.x -- is there a notion of optional vs. required tags here? ---------------------------------------------------------------- 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: us...@infra.apache.org With regards, Apache Git Services
