Skip to content

cardano-tracer: improve documentation #4207

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Jul 20, 2022
Merged

cardano-tracer: improve documentation #4207

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 4 additions & 0 deletions cardano-tracer/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,7 @@ For more details please [read its documentation](https://github.com/input-output
## Developers

Benchmarking team is responsible for this service. The primary developer is [@denisshevchenko](https://github.com/denisshevchenko).

## Feedback

Your bug reports and/or Feature Requests are welcome! Feel free to open a ticket in [this repository](https://github.com/input-output-hk/cardano-node/issues) with labels `RTView` and `tracing`.
14 changes: 13 additions & 1 deletion cardano-tracer/docs/cardano-rtview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,8 @@ Now, open your node's configuration file (if you took it from [Hydra](https://hy
"TraceOptionNodeName": "relay-1"
```

Please make sure you specified the _real name_ of your node in `TraceOptionNodeName` field.

Finally, run the node with this configuration file and add tracer's CLI-parameter like this:

```
Expand All @@ -87,6 +89,16 @@ $ ./cardano-node run --tracer-socket-path-connect /tmp/forwarder.sock

That's it. Now you can open [https://127.0.0.1:3300](https://127.0.0.1:3300/) in your browser.

### Important

Please note that the node has another CLI-parameter for the socket:

```
--socket-path FILEPATH Path to a cardano-node socket
```

But `--socket-path` is **not** for working with `cardano-tracer`. The only CLI-parameters you need to specify the path to the socket for working with `cardano-tracer` are `--tracer-socket-path-connect` (if your node should _initiate_ connection) or `--tracer-socket-path-accept` (if your node should _accept_ connection). They are **not** related to `--socket-path`, so you can use these CLI-parameters independently from each other.

# Configuration

Since RTView is a part of `cardano-tracer`, the only thing you need to do is to enable RTView (because it's disabled by default). To do it, please add the following lines to `cardano-tracer`'s configuration file.
Expand All @@ -108,7 +120,7 @@ hasRTView:
  epPort: 3300
```

Here `epHost` and `epPort` specify the host and the port for RTView web page.
Here `epHost` and `epPort` specify the host and the port for RTView web page. Also, you can find examples of configuration files in [configuration directory](https://github.com/input-output-hk/cardano-node/tree/master/cardano-tracer/configuration).

That's it. Now run `cardano-tracer` and open [127.0.0.1:3300](https://127.0.0.1:3300) in your browser.

Expand Down
119 changes: 63 additions & 56 deletions cardano-tracer/docs/cardano-tracer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Distributed scenario is for real-life case: for example, you have `N` nodes work

Local scenario is for testing case: for example, you want to try your new infrastructure from scratch, so you run `N` nodes and one `cardano-tracer` process on your machine.

**IMPORTANT NOTICE**: Please note that `cardano-tracer` **does not** support connection via IP-address and port, to avoid unauthorized connections. The **only** way to establish connection with the node is a local socket (Unix sockets or Windows named pipes).
**IMPORTANT NOTICE**: Please note that `cardano-tracer` **does not** support connection via IP-address and port, to avoid unauthorized connections. The **only** way to establish connection with the node is the local socket (Unix sockets or Windows named pipes).

## Distributed Scenario

Expand Down Expand Up @@ -103,7 +103,7 @@ The minimalistic configuration file for `cardano-tracer` would be:
"networkMagic": 764824073,
"network": {
"tag": "AcceptAt",
"contents": "/tmp/cardano-tracer.sock"
"contents": "/tmp/forwarder.sock"
},
"logging": [
{
Expand All @@ -115,79 +115,86 @@ The minimalistic configuration file for `cardano-tracer` would be:
}
```

The `network` field specifies the way how `cardano-tracer` will be connected to your nodes. Here you see `AcceptAt` tag, which means that `cardano-tracer` works as a server: it _accepts_ network connections by listening the local socket `/tmp/cardano-tracer.sock`. Your nodes work as clients: they _initiate_ network connections using their local sockets. It can be shown like this:
The `network` field specifies the way how `cardano-tracer` will be connected to your nodes. Here you see `AcceptAt` tag, which means that `cardano-tracer` works as a server: it _accepts_ network connections by listening the local socket `/tmp/forwarder.sock`. Your nodes work as clients: they _initiate_ network connections using their local sockets. It can be shown like this:

```
machine A machine B machine C
+-----------------+ +-----------------+ +-----------------+
| node 1 | | node 2 | | node 3 |
| \ | | \ | | \ |
| v | | v | | v |
| local socket | | local socket | | local socket |
+-----------------+ +-----------------+ +-----------------+
machine A machine B machine C
+----------------------+ +----------------------+ +----------------------+
| node 1 | | node 2 | | node 3 |
| \ | | \ | | \ |
| v | | v | | v |
| /tmp/forwarder.sock | | /tmp/forwarder.sock | | /tmp/forwarder.sock |
+----------------------+ +----------------------+ +----------------------+





+---------------------+
| local socket |
| ^ |
| \ |
| cardano-tracer |
+---------------------+
machine D
+---------------------+
| /tmp/forwarder.sock |
| ^ |
| \ |
| cardano-tracer |
+---------------------+
machine D
```

To establish the real network connections between your machines, you need SSH forwarding:

```
machine A machine B machine C
+-----------------+ +-----------------+ +-----------------+
| node 1 | | node 2 | | node 3 |
| \ | | \ | | \ |
| v | | v | | v |
| local socket | | local socket | | local socket |
+-----------------+ +-----------------+ +-----------------+
^ ^ ^
\ | /
SSH SSH SSH
\ | /
v v v
+---------------------+
| local socket |
| ^ |
| \ |
| cardano-tracer |
+---------------------+
machine D
machine A machine B machine C
+----------------------+ +----------------------+ +----------------------+
| node 1 | | node 2 | | node 3 |
| \ | | \ | | \ |
| v | | v | | v |
| /tmp/forwarder.sock | | /tmp/forwarder.sock | | /tmp/forwarder.sock |
+----------------------+ +----------------------+ +----------------------+
^ ^ ^
\ | /
SSH SSH SSH
\ | /
v v v
+---------------------+
| /tmp/forwarder.sock |
| ^ |
| \ |
| cardano-tracer |
+---------------------+
machine D
```

The idea of SSH forwarding is simple: we do connect not the processes directly, but their network endpoints instead. You can think of it as a network channel from the local socket on one machine to the local socket on another machine:

```
machine A machine D
+----------------------------+ +------------------------------------+
| node 1 ---> local socket <-|---SSH channel---|-> local socket <--- cardano-tracer |
+----------------------------+ +------------------------------------+
machine A machine D
+----------------------------------+ +------------------------------------------+
| node 1 --> /tmp/forwarder.sock <-|---SSH channel---|-> /tmp/forwarder.sock <-- cardano-tracer |
+----------------------------------+ +------------------------------------------+
```

So neither your nodes nor `cardano-tracer` know anything about SSH, they only know about their local sockets. But because of SSH forwarding mechanism they work together from different machines. And since you already have your SSH credentials, the connection between your nodes and `cardano-tracer` will be secure.

Please note that the path `/tmp/forwarder.sock` is just an example. You can use any other name in any other directory where you have read/write permissions.

So, to connect `cardano-node` working on machine `A` with `cardano-tracer` working on machine `D`, run this command on machine `A`:

```
ssh -nNT -L /tmp/cardano-tracer.sock:/tmp/cardano-node.sock -o "ExitOnForwardFailure yes" [email protected]
ssh -nNT -L /tmp/forwarder.sock:/tmp/forwarder.sock -o "ExitOnForwardFailure yes" [email protected]
```

where:

- `/tmp/cardano-tracer.sock` is a path to the local socket on machine `A`,
- `/tmp/cardano-node.sock` is a path to the local socket on machine `D`,
- `john` is a user you use to login on machine `D`,
- `/tmp/forwarder.sock` is a path to the local socket on machine `A` _and_ a path to the local socket on machine `D`,
- `john` is a user name you use to login on machine `D`,
- `109.75.33.121` is an IP-adress of machine `D`.

Run the same command on machines `B` and `C` to connect corresponding nodes with the same `cardano-tracer` working on machine `D`.
Now run the same command on machines `B` and `C` to connect corresponding nodes with the same `cardano-tracer` working on machine `D`.

Please note that your nodes working on machines `A`, `B` and `C` should specify paths `/tmp/forwarder.sock` using node's CLI-parameter `--tracer-socket-path-connect` or `--tracer-socket-path-accept` (see explanation below). There is another CLI-parameter `--socket-path` as well, but it's **not** related to `cardano-tracer`.

### Important

Please make sure you run `ssh`-command **before** you start your node. Since `ssh` creates the channel and `cardano-node` uses that channel, you should _create_ it before _using_ it.

## Local Scenario

Expand All @@ -198,7 +205,7 @@ As was mentioned above, local scenario is for testing, when your nodes and `card
"networkMagic": 764824073,
"network": {
"tag": "AcceptAt",
"contents": "/tmp/cardano-tracer.sock"
"contents": "/tmp/forwarder.sock"
},
"logging": [
{
Expand All @@ -210,7 +217,7 @@ As was mentioned above, local scenario is for testing, when your nodes and `card
}
```

As you see, it is the same configuration file: the `cardano-tracer` works as a server: it _accepts_ network connections by listening the local socket `/tmp/cardano-tracer.sock`. Your local nodes work as clients: they _initiate_ network connections using the _same_ local socket `/tmp/cardano-tracer.sock`.
As you see, it is the same configuration file: the `cardano-tracer` works as a server: it _accepts_ network connections by listening the local socket `/tmp/forwarder.sock`. Your local nodes work as clients: they _initiate_ network connections using the _same_ local socket `/tmp/forwarder.sock`.

There is another way to connect `cardano-tracer` to your nodes: the `cardano-tracer` can work as _initiator_, this is an example of configuration file:

Expand All @@ -237,13 +244,13 @@ There is another way to connect `cardano-tracer` to your nodes: the `cardano-tra

As you see, the tag in `network` field is `ConnectTo` now, which means that `cardano-tracer` works as a client: it _establishes_ network connections with your local nodes via the local sockets `/tmp/cardano-node-*.sock`. In this case each socket is used by a particular node.

Please use `ConnectTo`-based scenario only if you really need it. Otherwise, it is **highly recommended** to use `AcceptAt`-based scenario.
Please use `ConnectTo`-based scenario only if you really need it. Otherwise, it is **highly recommended** to use `AcceptAt`-based scenario. The reason is easier maintainance. Suppose you have 3 working nodes, and they are connected to the same `cardano-tracer`. And then you want to connect 4-th node to it. If `cardano-tracer` is configured using `AcceptAt`, you shouldn't change its configuration - you just connect your 4-th node to it. But if `cardano-tracer` is configured using `ConnectTo`, you should add path to 4-th socket in its configuration file and then restart `cardano-tracer` process.

## Network Magic

The field `networkMagic` specifies the value of network magic. It is an integer constant from the genesis file, the node uses this value for the network handshake with peers. Since `cardano-tracer` should be connected to the node, it needs that network magic.

The value from the example above, `764824073`, is taken from the Shelley genesis file for Mainnet. Please take this value from the genesis file your nodes are launched with.
The value from the example above, `764824073`, is taken from the Shelley genesis file for [Mainnet](https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/index.html). Please take this value from the genesis file your nodes are launched with.

## Requests

Expand Down Expand Up @@ -340,9 +347,9 @@ Here the web page is available at `http://127.0.0.1:3000`. Please note that if y
After you open `http://127.0.0.1:3000` in your browser, you will see the list of identifiers of connected nodes (or the warning message, if there are no connected nodes yet), for example:

```
* tmp-cardano-tracer.sock@0
* tmp-cardano-tracer.sock@1
* tmp-cardano-tracer.sock@2
* tmp-forwarder.sock@0
* tmp-forwarder.sock@1
* tmp-forwarder.sock@2
```

Each identifier is a hyperlink to the page where you will see the **current** list of metrics received from the corresponding node, in such a format:
Expand All @@ -368,7 +375,7 @@ The optional field `hasEKG` specifies the hosts and ports of two web pages:
1. the list of identifiers of connected nodes,
2. EKG monitoring page.

For example:
For example, if you use JSON configuration file:

```
"hasEKG": [
Expand All @@ -386,9 +393,9 @@ For example:
The page with the list of identifiers of connected nodes will be available at `http://127.0.0.1:3100`, for example:

```
* tmp-cardano-tracer.sock@0
* tmp-cardano-tracer.sock@1
* tmp-cardano-tracer.sock@2
* tmp-forwarder.sock@0
* tmp-forwarder.sock@1
* tmp-forwarder.sock@2
```

Each identifier is a hyperlink, after clicking to it you will be redirected to `http://127.0.0.1:3101` where you will see EKG monitoring page for corresponding node.
Expand Down