Merge pull request openwallet-foundation#597 from ianco/trace-docs

Add some docs on using tracing
Signed-off-by: Nicholas Rempel <[email protected]>

demo/AgentTracing.md

@@ -0,0 +1,98 @@
+# Using Tracing in ACA-PY
+
+The aca-py agent supports message tracing, according to the [Tracing RFC](https://github.com/hyperledger/aries-rfcs/tree/master/features/0034-message-tracing).
+
+Tracing can be enabled globally, for all messages/events, or it can be enabled on an exchange-by-exchange basis.
+
+Tracing is configured globally for the agent.
+
+## ACA-PY Configuration
+
+The following options can be specified when starting the aca-py agent:
+
+```
+  --trace               Generate tracing events.
+  --trace-target <trace-target>
+                        Target for trace events ("log", "message", or http
+                        endpoint).
+  --trace-tag <trace-tag>
+                        Tag to be included when logging events.
+  --trace-label <trace-label>
+                        Label (agent name) used logging events.
+```
+
+The `--trace` option enables tracing globally for the agent, the other options can configure the trace destination and content (default is `log`).
+
+Tracing can be enabled on an exchange-by-exchange basis, by including `{ ... "trace": True, ...}` in the JSON payload to the API call (for credential and proof exchanges).
+
+## Enabling Tracing in the Alice/Faber Demo
+
+The `run_demo` script supports the following parameters and environment variables.
+
+Environment variables:
+
+```
+TRACE_ENABLED          Flag to enable tracing
+
+TRACE_TARGET_URL       Host:port of endpoint to log trace events (e.g. fluentd:8088)
+
+DOCKER_NET             Docker network to join (must be used if EFK stack is running in docker)
+
+TRACE_TAG              Tag to be included in all logged trace events
+```
+
+Parameters:
+
+```
+--trace-log            Enables tracing to the standard log output
+                       (sets TRACE_ENABLED, TRACE_TARGET, TRACE_TAG)
+
+--trace-http           Enables tracing to an HTTP endpoint (specified by TRACE_TARGET_URL)
+                       (sets TRACE_ENABLED, TRACE_TARGET, TRACE_TAG)
+```
+
+When running the Faber controller, tracing can be enabled using the `T` menu option:
+
+```
+Faber      | Connected
+    (1) Issue Credential
+    (2) Send Proof Request
+    (3) Send Message
+    (T) Toggle tracing on credential/proof exchange
+    (X) Exit?
+[1/2/3/T/X] t
+
+>>> Credential/Proof Exchange Tracing is ON
+    (1) Issue Credential
+    (2) Send Proof Request
+    (3) Send Message
+    (T) Toggle tracing on credential/proof exchange
+    (X) Exit?
+
+[1/2/3/T/X] t
+
+>>> Credential/Proof Exchange Tracing is OFF
+    (1) Issue Credential
+    (2) Send Proof Request
+    (3) Send Message
+    (T) Toggle tracing on credential/proof exchange
+    (X) Exit?
+
+[1/2/3/T/X]
+```
+
+When `Exchange Tracing` is `ON`, all exchanges will include tracing.
+
+## Logging Trace Events to an EFK Stack
+
+You can use the `EFK` stack in the [EFK sub-directory](./EFK-stack) as a target for trace events, just start the EFK stack using the docker-compose file and then in two separate bash shells, startup the demo as follows:
+
+```bash
+DOCKER_NET=efk-stack_efk_net TRACE_TARGET_URL=fluentd:8088 ./run_demo faber --trace-http
+```
+
+```bash
+DOCKER_NET=efk-stack_efk_net TRACE_TARGET_URL=fluentd:8088 ./run_demo alice --trace-http
+```
+
+

demo/EFK-stack/README.md

@@ -65,6 +65,18 @@ Files are available in the [examples](examples) folder.
 
 Please note that RESTed is not strictly necessary as any other REST client application will work fine.
 
+## Running the aca-py Alice/Faber Demo Tracing using EFK
+
+In two separate bash shells, startup the demo as follows:
+
+```bash
+DOCKER_NET=efk-stack_efk_net TRACE_TARGET_URL=fluentd:8088 ./run_demo faber --trace-http
+```
+
+```bash
+DOCKER_NET=efk-stack_efk_net TRACE_TARGET_URL=fluentd:8088 ./run_demo alice --trace-http
+```
+
 ## Reference
 
 - [Quora - What is the ELK stack](https://www.quora.com/What-is-the-ELK-stack)