merge with master branch

Author: mmacai

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Support publishing events consumed from [NATS](https://nats.io) topics. See the [documentation](https://accenture.github.io/reactive-interaction-gateway/docs/event-streams.html#nats) for how to get started. [#297](https://github.com/Accenture/reactive-interaction-gateway/issues/297)
 - Added validation for reverse proxy configuration. Now it crashes RIG on start when configuration is not valid or returns `400` when using REST API to update configuration. [#277](https://github.com/Accenture/reactive-interaction-gateway/issues/277)
+- Added basic distributed tracing support in [W3C Trace Context specification](https://www.w3.org/TR/trace-context/) with Jaeger and Openzipkin exporters. RIG opens a span at the API Gateway and emits trace context in Cloud Events following the [distributed tracing spec](https://github.com/cloudevents/spec/blob/v1.0/extensions/distributed-tracing.md). [#281](https://github.com/Accenture/reactive-interaction-gateway/issues/281)
 
 ### Changed
 

config/config.exs

@@ -122,7 +122,7 @@ config :rig, RIG.AuthorizationCheck.Submission,
 # Peerage
 # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-config :rig, Rig.Discovery,
+config :rig, RIG.Discovery,
   discovery_type: {:system, "DISCOVERY_TYPE", nil},
   dns_name: {:system, "DNS_NAME", "localhost"}
 
@@ -133,3 +133,14 @@ import_config "rig_inbound_gateway/config.exs"
 import_config "rig_metrics/config.exs"
 import_config "rig_outbound_gateway/config.exs"
 import_config "rig_tests/config.exs"
+
+# --------------------------------------
+# Jaeger
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+config :rig, RIG.Tracing,
+  jaeger_host: {:system, :charlist, "JAEGER_HOST", ''},
+  jaeger_port: {:system, :integer, "JAEGER_PORT", 6831},
+  jaeger_service_name: {:system, :charlist, "JAEGER_SERVICE_NAME", 'rig'},
+  zipkin_address: {:system, :charlist, "ZIPKIN_ADDR", ''},
+  zipkin_service_name: {:system, "ZIPKIN_SERVICE_NAME", "rig"}

config/prod.exs

@@ -7,6 +7,6 @@ config :rig, Rig.Application, log_level: {:system, :atom, "LOG_LEVEL", :warn}
 # Peerage
 # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-config :rig, Rig.Discovery,
+config :rig, RIG.Discovery,
   discovery_type: {:system, "DISCOVERY_TYPE", nil},
   dns_name: {:system, "DNS_NAME", "localhost"}

docs/api-gateway.md

@@ -75,7 +75,10 @@ $ docker run -d \
 After that we should be able to reach our small demo service through RIG:
 
 ```bash
-$ curl localhost:4000
+$ curl \
+    -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
+    -H 'tracestate: hello=tracing' \
+    localhost:4000
 Hi, I'm a demo service!
 ```
 
@@ -93,7 +96,10 @@ $ docker run \
 Note that this way we don't need a Docker volume, which might work better in your environment. Again, we should be able to reach the demo service:
 
 ```bash
-$ curl localhost:4000
+$ curl \
+    -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
+    -H 'tracestate: hello=tracing' \
+    localhost:4000
 Hi, I'm a demo service!
 ```
 

docs/distributed-tracing.md

@@ -0,0 +1,22 @@
+---
+id: distributed-tracing
+title: Distributed Tracing
+sidebar_label: Distributed Tracing
+---
+
+RIG is able to process distributed tracing data following the [W3C Trace Contexts](https://www.w3.org/TR/trace-context/). Sometimes RIG expects the trace context to be in the (HTTP) Header, and sometimes in the event payload itself. With events, we always speak of cloudevents following the [distributed tracing extension](https://github.com/cloudevents/spec/blob/v1.0/extensions/distributed-tracing.md).
+
+There is one key rule when RIG expects the trace context either in the header or in the cloudevent:
+
+1. if we talk of messages, then RIG expects the trace context to be in the (HTTP) header
+2. if we talk of events (cloudevents), then RIG expects the trace context to be in the cloudevent
+
+In our point of view, the difference of a message to an event is the following:
+
+* a message is a request from one system to another for an action to be taken. The sender expects that the message will get processed somehow
+* an event is a notification that data has been processed and some objects’ state has changed
+* thus, a message and events have a different correlation between producer and consumer:
+  * messages have 1-to-1 correlation between a producer and a consumer
+  * events have a 1-to-n correlation between a producer and (potentially multiple) consumers
+
+As a concrete example how distributed tracing has been implemented, read about it in the [channels-example](../examples/channels-example/README.md#one-word-to-distributed-tracing).

examples/api-gateway/README.md renamed to examples/api-gateway/http/README.md

@@ -2,6 +2,7 @@ const http = require("http");
 const port = 3000;
 const handler = (req, res) => {
   console.log(`Request URL: ${req.url}`);
+  console.log(JSON.stringify(req.headers));
   res.end("Hi, I'm a demo service!\n");
 }
 const server = http.createServer(handler);

examples/api-gateway/config.json renamed to examples/api-gateway/http/config.json

@@ -0,0 +1,37 @@
+# API Gateway HTTP <> Kafka
+
+First start Kafka
+
+```shell
+docker-compose -f kafka.docker-compose.yml up -d
+```
+
+Start RIG locally:
+
+```shell
+cd ../../../
+export KAFKA_SOURCE_TOPICS=example
+export KAFKA_BROKERS=localhost:9092
+config=$(cat examples/api-gateway/kafka/config.json)
+export PROXY_CONFIG_FILE="$config"
+mix run --no-halt
+```
+
+[Download some quickstart scripts for Kafka](https://kafka.apache.org/quickstart) and run a consumer (note: there must not be a space in the path of the script):
+
+```shell
+/path/to/download/folder/bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic example --from-beginning
+```
+
+After that we should be able to send events to Kafka through RIG:
+
+```shell
+curl -X POST \
+  -H 'traceparent: 00-9c18b63f316cbfe3854122c20c8c6b23-22d69e0945046f2d-01' \
+  --data '{"specversion":"0.2","type":"com.github.pull.create","source":"https://github.com/cloudevents/spec/pull","id":"A234-1234-1234","time":"2018-04-05T17:31:00Z","data":"hello"}' \
+  localhost:4000
+```
+
+You should see the message in the Kafka consumer.
+
+> RIG does not yet support forwarding trace context to a Kafka backend. There is an issue that addresses this.

examples/api-gateway/service.js renamed to examples/api-gateway/http/service.js

@@ -0,0 +1,16 @@
+[
+  {
+    "id": "my-kafka-service",
+    "version_data": {
+      "default": {
+        "endpoints": [{
+          "id": "my-endpoint",
+          "method": "POST",
+          "path": "/",
+          "target": "kafka",
+          "topic": "example"
+        }]
+      }
+    }
+  }
+]