8125cd0262
* refactor(metrics): prefix node metrics with logos_delivery_
Every metric the node exports now starts with logos_delivery_. There was no
prefix mechanism before: nim-metrics derives the exported name from the Nim
identifier, no declaration passed an explicit `name = "..."`, and the waku_
convention was maintained by hand -- 69 of the 80 node metrics followed it and
11 did not (query_count, query_time_secs, event_loop_load,
event_loop_accumulated_lag_secs, postgres_payload_size_bytes, reconciliation_*,
total_* and the camelCase rendezvousPeerFoundTotal).
Identifiers are renamed rather than given a `name = "..."` argument, keeping the
invariant that the Nim identifier is the exported name and letting the compiler
check every call site.
rendezvousPeerFoundTotal becomes logos_delivery_rendezvous_peer_found: it was the
only camelCase metric, and the trailing Total was redundant since nim-metrics
already appends _total to counters at exposition time.
library/ is untouched on purpose -- `proc waku_version()` in
kernel_api/debug_node_api.nim is the exported libwaku C ABI symbol, not the gauge
of the same name in node_telemetry.nim.
BREAKING CHANGE: metric names change. Dashboards, alert rules and recording rules
that reference waku_* must be updated; see docs/operators/how-to/monitor.md.
* refactor(metrics): prefix auxiliary app metrics with logos_delivery_
Applies the same prefix to the tools shipped from this repo: liteprotocoltester
(lpt_*), networkmonitor (networkmonitor_*), chat2bridge (chat2_*) and the
lightpush_mix example (lp_mix_*).
These tools are not the delivery node and already had their own consistent
prefixes, so this commit is separable from the node rename if the intent was to
namespace only the node itself.
* chore(metrics): query old and new metric names in Grafana dashboards
212 expressions across 9 dashboards now match both the waku_* and the
logos_delivery_* spelling, so panels keep working across the upgrade and over
historical data:
sum by (type)((increase(waku_node_errors_total{...}[$__rate_interval])
or increase(logos_delivery_node_errors_total{...}[$__rate_interval])))
The `or` is placed around the leaf, inside every aggregation. That depth is
load-bearing: `or` keeps its right operand only for label sets absent from the
left, so `sum by (type)(old) or sum by (type)(new)` aggregates each half of the
fleet separately and then discards the right one entirely -- silently dropping
every already-upgraded node. 36 panels here collapse `instance`.
Measured against a local Prometheus scraping two targets, one exporting old names
at 10/s and one exporting new names at 20/s (truth 30/s): union outside the
aggregation gives 10, union around the leaf gives 30.
Where the leaf sits in a range vector the whole call is duplicated, since
`(a or b)[5m]` is not valid PromQL.
Once every scraped node runs a release with the new names and the old samples
have aged out of retention, the `or` half can be deleted.
* test(e2e): expect logos_delivery_-prefixed metric names
The e2e suite asserts against a live /metrics endpoint, which serves only the new
names, so these are replaced rather than unioned. libp2p_* entries are unchanged.
* docs(operators): document the logos_delivery_ metric prefix
Records that every metric the node exports is prefixed, that dependency metrics
(libp2p_*, nim_gc_*, process_*) keep their own names, and shows where the `or`
has to sit if operators maintain their own dashboards or alert rules.
* refactor(metrics): name the store fleet metrics after store, not relay
logos_delivery_relay_fleet_store_msg_size_bytes and _msg_count are declared in
waku_store/protocol_metrics.nim and recorded by the store client, but carried a
relay prefix. Renamed to logos_delivery_store_fleet_msg_size_bytes and
logos_delivery_store_fleet_msg_count.
The dashboard keeps matching the old exported name, which was
waku_relay_fleet_store_*.
Note that both metrics are wrong independently of their name, see the PR
description.
Logos Messaging Nim
Introduction
This repository implements a set of libp2p protocols aimed to bring private communications.
- Nim implementation of these specs.
- C library that exposes the implemented protocols.
- CLI application that allows you to run a logos-delivery node.
- Examples.
- Various tests of above.
For more details see the source code
How to Build & Run ( Linux, MacOS & WSL )
These instructions are generic. For more detailed instructions, see the source code above.
Recommended and tested toolchain versions (these are installed when you follow the build instructions below):
- Nim 2.2.4
- Nimble 0.22.3
Prerequisites
The standard developer tools, including a C compiler, GNU Make, Bash, and Git.
In some distributions (Fedora linux for example), you may need to install
whichutility separately. Nimbus build system is relying on it.
You'll also need an installation of Rust and its toolchain (specifically rustc and cargo).
The easiest way to install these, is using rustup:
Rust:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Wakunode
# The first `make` invocation will initialize the local dependency state.
make wakunode2
# Build with custom compilation flags. Do not use NIM_PARAMS unless you know what you are doing.
# Replace with your own flags
make wakunode2 NIMFLAGS="-d:chronicles_colors:none -d:disableMarchNative"
# Run with DNS bootstrapping
./build/wakunode2 --dns-discovery --dns-discovery-url=DNS_BOOTSTRAP_NODE_URL
# Run with the QUIC transport enabled
./build/wakunode2 --quic-support=true
# See available command line options
./build/wakunode2 --help
To join the network, you need to know the address of at least one bootstrap node. Please refer to the Waku README for more information.
For more on how to run wakunode2, refer to:
Issues
WSL
If you encounter difficulties building the project on WSL, consider placing the project within WSL's filesystem, avoiding the /mnt/ directory.
How to Build & Run ( Windows )
Windows Build Instructions
1. Install Required Tools
- Git Bash Terminal: Download and install from https://git-scm.com/download/win
- MSYS2:
a. Download installer from https://www.msys2.org
b. Install at "C:" (default location). Remove/rename the msys folder in case of previous installation. c. Use the mingw64 terminal from msys64 directory for package installation.
2. Install Dependencies
Open MSYS2 mingw64 terminal and run the following one-by-one :
pacman -Syu --noconfirm
pacman -S --noconfirm --needed mingw-w64-x86_64-toolchain
pacman -S --noconfirm --needed base-devel make cmake upx
pacman -S --noconfirm --needed mingw-w64-x86_64-rust
pacman -S --noconfirm --needed mingw-w64-x86_64-postgresql
pacman -S --noconfirm --needed mingw-w64-x86_64-gcc
pacman -S --noconfirm --needed mingw-w64-x86_64-gcc-libs
pacman -S --noconfirm --needed mingw-w64-x86_64-libwinpthread-git
pacman -S --noconfirm --needed mingw-w64-x86_64-zlib
pacman -S --noconfirm --needed mingw-w64-x86_64-openssl
pacman -S --noconfirm --needed mingw-w64-x86_64-python
3. Build Wakunode
- Open Git Bash as administrator
- clone nwaku and cd nwaku
- Execute:
./scripts/build_windows.sh
4. Troubleshooting
If wakunode2.exe isn't generated:
- Missing Dependencies: Verify with:
which make cmake gcc g++ rustc cargo python3 upx
If missing, revisit Step 2 or ensure MSYS2 is atC:\ - Installation Conflicts: Remove existing MinGW/MSYS2/Git Bash installations and perform fresh install
Developing
Nim Runtime
This repository is bundled with a Nim runtime that includes the necessary dependencies for the project.
Before you can utilize the runtime you'll need to build the project, as detailed in a previous section.
This will generate a nimbledeps/pkgs2 directory containing various dependencies.
If everything went well, you should see your prompt suffixed with [SuccessX]. Now you can run nim commands as usual.
Test Suite
# Run all the Waku tests
make test
# Run a specific test file
make test <test_file_path>
# e.g. : make test tests/wakunode2/test_all.nim
# Run a specific test name from a specific test file
make test <test_file_path> <test_name>
# e.g. : make test tests/wakunode2/test_all.nim "node setup is successful with default configuration"
Building single test files
During development it is helpful to build and run a single test file. To support this make has a specific target:
targets:
build/<relative path to your test file.nim>test/<relative path to your test file.nim>
Binary will be created as <path to your test file.nim>.bin under the build directory .
# Build and run your test file separately
make test/tests/common/test_enr_builder.nim
Testing against js-waku
Refer to logos-delivery-js repo for instructions.
Formatting
Nim files are expected to be formatted using the nph version present in vendor/nph.
You can easily format file with the make nph/<relative path to nim> file command.
For example:
make nph/waku/waku_core.nim
A convenient git hook is provided to automatically format file at commit time. Run the following command to install it:
make install-nph
Examples
Examples can be found in the examples folder. This includes a fully featured chat example.
Tools
Different tools and their corresponding how-to guides can be found in the tools folder.
Bugs, Questions & Features
For an inquiry, or if you would like to propose new features, feel free to open a general issue.
For bug reports, please tag your issue with the bug label.
If you believe the reported issue requires critical attention, please use the critical label to assist with triaging.
To get help, or participate in the conversation, join the Logos Discord server.