cardano-tracer: new changes.

IntersectMBO · Nov 23, 2021 · 2ee8f18 · 2ee8f18
1 parent 4f60dde
commit 2ee8f18
Show file tree

Hide file tree

Showing 28 changed files with 556 additions and 431 deletions.
diff --git a/cabal.project b/cabal.project
@@ -73,6 +73,9 @@ package cardano-submit-api
 package cardano-testnet
   tests: True
 
+package cardano-tracer
+  tests: True
+
 package plutus-examples
   tests: True
 
@@ -273,8 +276,14 @@ source-repository-package
 source-repository-package
   type: git
   location: https://github.com/input-output-hk/ekg-forward
-  tag: d9e8fd302fa6ba41c07183d371e6777286d37bc2
-  --sha256: 0s8cblhq3i528jj7r7yd4v82nqzafj8vrgf0y80l7saxc3a5f2lk
+  tag: b50b215651822fa0d5f5dd2fc28b57ca2b33baa4
+  --sha256: 1dlknw83cmya9z8s2iwi35ymhv1yip5wvdh8p3jhmx9yv89apkq2
+
+source-repository-package
+  type: git
+  location: https://github.com/HeinrichApfelmus/threepenny-gui
+  tag: e3bb8283fc7d2e8aa374eea29426002e8dcd67a8
+  --sha256: 0nf836b552asgpwn2gxwl7yd7ssdhb1wkvdqz6s4dpzqnlpyivx9
 
 source-repository-package
   type: git

diff --git a/cardano-tracer/CODEOWNERS b/cardano-tracer/CODEOWNERS
@@ -0,0 +1,3 @@
+# General reviewers per PR
+#                       Denis            Serge
+*                       @denisshevchenko @deepfire
diff --git a/cardano-tracer/README.md b/cardano-tracer/README.md
@@ -1,5 +1,5 @@
-# cardano-tracer
+# Cardano Tracer
 
-`cardano-tracer` is an application for logging and monitoring over `cardano-node`. After it is connected to the node, it periodically asks the node for different information, receives it, and handles it.
+`cardano-tracer` is a service for logging and monitoring over `cardano-node`. After it is connected to the node, it periodically asks the node for different information, receives it, and handles it.
 
-For more details please [read the documentation](https://github.com/input-output-hk/cardano-node/blob/tracing-master/cardano-tracer/docs/cardano-tracer.md).
+For more details please [read the documentation](https://github.com/input-output-hk/cardano-node/blob/master/cardano-tracer/docs/cardano-tracer.md).
diff --git a/cardano-tracer/cardano-tracer.cabal b/cardano-tracer/cardano-tracer.cabal
@@ -1,7 +1,7 @@
 cabal-version:       2.4
 name:                cardano-tracer
 version:             0.1.0
-synopsis:            See README for more info
+synopsis:            A service for logging and monitoring over Cardano node.
 description:         See README for more info
 license:             Apache-2.0
 license-file:        LICENSE
@@ -55,6 +55,7 @@ library
 
   build-depends:         aeson
                        , async
+                       , async-extras
                        , blaze-html
                        , blaze-markup
                        , bytestring
@@ -74,6 +75,7 @@ library
                        , snap-server
                        , stm
                        , text
+                       , threepenny-gui
                        , time
                        , trace-dispatcher
                        , trace-forward
@@ -158,7 +160,6 @@ test-suite cardano-tracer-test
                        , filepath
                        , ouroboros-network-framework
                        , QuickCheck
-                       , stm
                        , tasty
                        , tasty-quickcheck
                        , text

diff --git a/cardano-tracer/configuration/complete-example.json b/cardano-tracer/configuration/complete-example.json
@@ -0,0 +1,39 @@
+{
+  "network": {
+    "tag": "AcceptAt",
+    "contents": "/tmp/forwarder.sock"
+  },
+  "loRequestNum": 100,
+  "ekgRequestFreq": 2,
+  "hasEKG": [
+    {
+      "epHost": "127.0.0.1",
+      "epPort": 3100
+    },
+    {
+      "epHost": "127.0.0.1",
+      "epPort": 3101
+    }
+  ],
+  "hasPrometheus": {
+    "epHost": "127.0.0.1",
+    "epPort": 3000
+  },
+  "logging": [
+    {
+      "logRoot": "/tmp/cardano-tracer-h-logs",
+      "logMode": "FileMode",
+      "logFormat": "ForHuman"
+    },
+    {
+      "logRoot": "/tmp/cardano-tracer-m-logs",
+      "logMode": "FileMode",
+      "logFormat": "ForMachine"
+    }
+  ],
+  "rotation": {
+    "rpKeepFilesNum": 1,
+    "rpLogLimitBytes": 50000,
+    "rpMaxAgeHours": 1
+  }
+}
diff --git a/cardano-tracer/configuration/example.json → ...tracer/configuration/minimal-example.json b/cardano-tracer/configuration/example.json → ...tracer/configuration/minimal-example.json
@@ -3,18 +3,11 @@
     "tag": "ConnectTo",
     "contents": ["/tmp/forwarder.sock"]
   },
-  "hasEKG": null,
-  "hasPrometheus": null,
   "logging": [
     {
       "logRoot": "/tmp/cardano-tracer-logs",
       "logMode": "FileMode",
       "logFormat": "ForMachine"
     }
-  ],
-  "rotation": {
-    "rpKeepFilesNum": 1,
-    "rpLogLimitBytes": 50000,
-    "rpMaxAgeHours": 1
-  }
+  ]
 }
diff --git a/cardano-tracer/docs/cardano-tracer.md b/cardano-tracer/docs/cardano-tracer.md
@@ -1,6 +1,6 @@
-# cardano-tracer
+# Cardano Tracer
 
-`cardano-tracer` is an application for logging and monitoring over `cardano-node`. After it is connected to the node, it periodically asks the node for different information, receives it, and handles it.
+`cardano-tracer` is a service for logging and monitoring over `cardano-node`. After it is connected to the node, it periodically asks the node for different information, receives it, and handles it.
 
 # Contents
 
@@ -20,18 +20,19 @@
 
 ## Motivation
 
-Previously, `cardano-node` handled all the logging by itself. Moreover, it provided monitoring tools as well, for example, a web page for EKG metrics. `cardano-tracer` is an attempt to _move_ all logging/monitoring-related stuff from the node to a separate application. As a result, the node will be smaller, faster, and simpler.
+Previously, `cardano-node` handled all the logging by itself. Moreover, it provided monitoring tools as well, for example, a web page for EKG metrics. `cardano-tracer` is a result of _moving_ all the logging/monitoring-related stuff from the node to a separate service. As a result, the node became smaller, faster, and simpler.
 
 ## Overview
 
 You can think of `cardano-node` as a **producer** of logging/monitoring information, and `cardano-tracer` as a **consumer** of this information. And after the network connection between them is established, `cardano-tracer` periodically asks for logging/monitoring information, and `cardano-node` replies with it.
 
-Currently, this information is presented in two items:
+There are three kinds of such an information:
 
-1. Trace object, which contains arbitrary information from the node. For more details, please see `Cardano.Logging.Types.TraceObject` from `trace-dispatcher` library.
-2. EKG metric, which contains some system metric. Please [read the documentation](https://hackage.haskell.org/package/ekg-core) for more info.
+1. Trace object, which contains different logging data. `cardano-tracer` asks for new trace objects each `N` seconds, receives them and stores them in the log files and/or in Linux journal.
+2. EKG metric, which contains some system metric. Please [read EKG documentation](https://hackage.haskell.org/package/ekg-core) for more info. `cardano-tracer` asks for new EKG metrics each `N` seconds, receives them and displays them using monitoring tools.
+3. Data points, which contains arbitrary information about the node. `cardano-tracer` asks for new data points only by _explicit_ request, there is no "stream of data points".
 
-Please note that `cardano-tracer` can work as an aggregator as well: _one_ `cardano-tracer` process can receive the information from _multiple_ `cardano-node` processes. In this case, received logging information will be stored in subdirectories: each subdirectory will contain all the items received from the particular node.
+Please note that `cardano-tracer` can work as an aggregator as well: _one_ `cardano-tracer` process can receive the information from _multiple_ nodes.
 
 # Build and run
 
@@ -55,7 +56,7 @@ Then you can run `cardano-tracer` using the following command:
 cabal exec -- cardano-tracer --config /path/to/your/config.json
 ```
 
-Please see below an explanation about the configuration file.
+Please see below an explanation about the configuration file. You can find an example of the configuration file in `configuration` subdirectory.
 
 # Configuration
 
@@ -64,9 +65,11 @@ The way how to configure `cardano-tracer` is depending on your requirements. The
 1. **Distributed** scenario, when `cardano-tracer` is working on one machine, and your nodes are working on another machine(s).
 2. **Local** scenario, when `cardano-tracer` and your nodes are working on the same machine.
 
-Distributed scenario is for real-world case: for example, you have a cluster from `N` nodes working on `N` different AWS-instances, and you want to collect all the logging/monitoring information from these nodes using one single `cardano-tracer` process working on your machine. So, by default you should consider using distributed scenario.
+Distributed scenario is for real-world case: for example, you have a cluster from `N` nodes working on `N` different AWS-instances, and you want to collect all the logging/monitoring information from these nodes using one `cardano-tracer` process working on your machine. So, by default you should consider using distributed scenario.
 
-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 laptop.
+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.
 
 ## Distributed Scenario
 
@@ -87,7 +90,7 @@ machine A                 machine B                 machine C
                           machine D
 ```
 
-The minimalistic configuration file for `cardano-tracer` in such a scenario would be:
+The minimalistic configuration file for the tracer would be:
 
 ```
 {
@@ -105,10 +108,31 @@ The minimalistic configuration file for `cardano-tracer` in such a scenario woul
 }
 ```
 
-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 Unix socket `/tmp/cardano-tracer.sock`. But if `cardano-tracer` _accepts_ the connections - who should _initiate_ them? The node cannot do that, because it listens its local Unix socket too. To do that, we use SSH forwarding. Please note that `cardano-tracer` **does not** support connection via IP-address and port, to avoid unauthorized connections, that's why we need `ssh` for distributed scenario.
+The `network` field specifies the way how `cardano-tracer` will be connected with 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`. And your nodes work as clients: they _initiate_ network connections using their local sockets. It can be shown like this:
 
-It can be shown like this:
+```
+machine A                 machine B                 machine C
++----------------------+  +----------------------+  +----------------------+
+| cardano-node         |  | cardano-node         |  | cardano-node         |
+|             \        |  |             \        |  |             \        |
+|              v       |  |              v       |  |              v       |
+|         local socket |  |         local socket |  |         local socket |
++----------------------+  +----------------------+  +----------------------+
+                       
+                        
+                        
+                          
+                          
+                          +----------------------+
+                          | local socket         |
+                          |      ^               |
+                          |       \              |
+                          |       cardano-tracer |
+                          +----------------------+
+                          machine D
+```
 
+To establish the real network connections between your machines, you need SSH forwarding:
 
 ```
 machine A                 machine B                 machine C
@@ -127,30 +151,38 @@ machine A                 machine B                 machine C
                           | local socket         |
                           |      ^               |
                           |       \              |
-                          |        \             |
                           |       cardano-tracer |
                           +----------------------+
                           machine D
 ```
 
-In this case, `ssh` connects each node with the same `cardano-tracer`. The idea of SSH forwarding is simple: we 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. So, to connect `cardano-node` working on machine `A` with `cardano-tracer` working on machine `D`, run this command on machine `A`:
+The idea of SSH forwarding is simple: we 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
++----------------------------------+                 +------------------------------------+
+| cardano-node ---> local socket <-|---SSH channel---|-> local socket <--- cardano-tracer |
++----------------------------------+                 +------------------------------------+
+```
+
+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" john@109.75.33.121
 ```
 
 where:
 
-- `/tmp/cardano-tracer.sock` is a path to the local Unix socket on machine `A`,
-- `/tmp/cardano-node.sock` is a path to the local Unix socket on machine `D`,
+- `/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`,
 - `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`.
 
 ## Local Scenario
 
-As was mentioned above, local scenario is for testing, when your nodes and `cardano-tracer` are working on the same machine. In this case all these processes can see the same local sockets directly, so we don't need `ssh`. The configuration file for the local cluster from 3 nodes will look like this this:
+As was mentioned above, local scenario is for testing only, when your nodes and `cardano-tracer` are working on the same machine. In this case all these processes can see the same local sockets directly, so we don't need `ssh`. The configuration file for the local cluster from 3 nodes would look like this:
 
 ```
 {
@@ -172,7 +204,7 @@ As was mentioned above, local scenario is for testing, when your nodes and `card
 }
 ```
 
-As you see, the tag is `ConnectTo` now, which means that `cardano-tracer` works as a client: it _establishes_ network connections with the node via the local Unix sockets `/tmp/cardano-node-*.sock`. Please make sure your local nodes are listening corresponding sockets.
+As you see, the tag is `ConnectTo` now, which means that `cardano-tracer` works as a client: it _establishes_ network connections with the node via the local sockets `/tmp/cardano-node-*.sock`. Please make sure your local nodes are listening corresponding sockets.
 
 Let's explore other fields of the configuration file.