Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add some docs on using tracing #597

Merged
merged 4 commits into from
Jul 10, 2020
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 98 additions & 0 deletions demo/AgentTracing.md
Original file line number Diff line number Diff line change
@@ -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:

```bash
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The red operators because it expects bash syntax are a little distracting

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
```


12 changes: 12 additions & 0 deletions demo/EFK-stack/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down