Cleanup location of docs and example files (#1195)

docs/configure-clio.md

@@ -18,7 +18,7 @@ Clio needs access to a `rippled` server in order to work. The following configur
 
    - A port to handle gRPC requests, with the IP(s) of Clio specified in the `secure_gateway` entry
 
-The example configs of [rippled](https://github.com/XRPLF/rippled/blob/develop/cfg/rippled-example.cfg) and [Clio](../example-config.json) are set up in a way that minimal changes are required.
+The example configs of [rippled](https://github.com/XRPLF/rippled/blob/develop/cfg/rippled-example.cfg) and [Clio](../docs/examples/config/example-config.json) are set up in a way that minimal changes are required.
 When running locally, the only change needed is to uncomment the `port_grpc` section of the `rippled` config.
 
 If you're running Clio and `rippled` on separate machines, in addition to uncommenting the `port_grpc` section, a few other steps must be taken:

docs/examples/config/cloud-example-config.json

@@ -0,0 +1,43 @@
+/*
+ * This is an example configuration file. Please do not use without modifying to suit your needs.
+ */
+{
+    "database": {
+        "type": "cassandra",
+        "cassandra": {
+            // This option can be used to setup a secure connect bundle connection
+            "secure_connect_bundle": "[path/to/zip. ignore if using contact_points]",
+            // The following options are used only if using contact_points
+            "contact_points": "[ip. ignore if using secure_connect_bundle]",
+            "port": "[port. ignore if using_secure_connect_bundle]",
+            // Authentication settings
+            "username": "[username, if any]",
+            "password": "[password, if any]",
+            // Other common settings
+            "keyspace": "clio",
+            "max_write_requests_outstanding": 25000,
+            "max_read_requests_outstanding": 30000,
+            "threads": 8
+        }
+    },
+    "etl_sources": [
+        {
+            "ip": "[rippled ip]",
+            "ws_port": "6006",
+            "grpc_port": "50051"
+        }
+    ],
+    "dos_guard": {
+        "whitelist": [
+            "127.0.0.1"
+        ]
+    },
+    "server": {
+        "ip": "0.0.0.0",
+        "port": 8080
+    },
+    "log_level": "debug",
+    "log_file": "./clio.log",
+    "extractor_threads": 8,
+    "read_only": false
+}

docs/examples/config/example-config.json

@@ -0,0 +1,130 @@
+/*
+ * This is an example configuration file. Please do not use without modifying to suit your needs.
+ */
+{
+    "database": {
+        "type": "cassandra",
+        "cassandra": {
+            "contact_points": "127.0.0.1",
+            "port": 9042,
+            "keyspace": "clio",
+            "replication_factor": 1,
+            "table_prefix": "",
+            "max_write_requests_outstanding": 25000,
+            "max_read_requests_outstanding": 30000,
+            "threads": 8,
+            //
+            // Advanced options. USE AT OWN RISK:
+            // ---
+            "core_connections_per_host": 1, // Defaults to 1
+            "write_batch_size": 20 // Defaults to 20
+            //
+            // Below options will use defaults from cassandra driver if left unspecified.
+            // See https://docs.datastax.com/en/developer/cpp-driver/2.17/api/struct.CassCluster/ for details.
+            // 
+            // "queue_size_io": 2
+            //
+            // ---
+        }
+    },
+    "allow_no_etl": false, // Allow Clio to run without valid ETL source, otherwise Clio will stop if ETL check fails
+    "etl_sources": [
+        {
+            "ip": "127.0.0.1",
+            "ws_port": "6006",
+            "grpc_port": "50051"
+        }
+    ],
+    "dos_guard": {
+        // Comma-separated list of IPs to exclude from rate limiting
+        "whitelist": [
+            "127.0.0.1"
+        ],
+        //
+        // The below values are the default values and are only specified here
+        // for documentation purposes. The rate limiter currently limits
+        // connections and bandwidth per IP. The rate limiter looks at the raw
+        // IP of a client connection, and so requests routed through a load
+        // balancer will all have the same IP and be treated as a single client.
+        //
+        "max_fetches": 1000000, // Max bytes per IP per sweep interval
+        "max_connections": 20, // Max connections per IP
+        "max_requests": 20, // Max connections per IP per sweep interval
+        "sweep_interval": 1 // Time in seconds before resetting max_fetches and max_requests
+    },
+    "cache": {
+        // Comma-separated list of peer nodes that Clio can use to download cache from at startup
+        "peers": [
+            {
+                "ip": "127.0.0.1",
+                "port": 51234
+            }
+        ]
+    },
+    "server": {
+        "ip": "0.0.0.0",
+        "port": 51233,
+        // Max number of requests to queue up before rejecting further requests.
+        // Defaults to 0, which disables the limit.
+        "max_queue_size": 500,
+        // If request contains header with authorization, Clio will check if it matches the prefix 'Password ' + this value's sha256 hash
+        // If matches, the request will be considered as admin request
+        "admin_password": "xrp",
+        // If local_admin is true, Clio will consider requests come from 127.0.0.1 as admin requests
+        // It's true by default unless admin_password is set,'local_admin' : true and 'admin_password' can not be set at the same time
+        "local_amdin": false
+    },
+    // Overrides log level on a per logging channel.
+    // Defaults to global "log_level" for each unspecified channel.
+    "log_channels": [
+        {
+            "channel": "Backend",
+            "log_level": "fatal"
+        },
+        {
+            "channel": "WebServer",
+            "log_level": "info"
+        },
+        {
+            "channel": "Subscriptions",
+            "log_level": "info"
+        },
+        {
+            "channel": "RPC",
+            "log_level": "error"
+        },
+        {
+            "channel": "ETL",
+            "log_level": "debug"
+        },
+        {
+            "channel": "Performance",
+            "log_level": "trace"
+        }
+    ],
+    "prometheus": {
+        "enabled": true,
+        "compress_reply": true
+    },
+    "log_level": "info",
+    // Log format (this is the default format)
+    "log_format": "%TimeStamp% (%SourceLocation%) [%ThreadID%] %Channel%:%Severity% %Message%",
+    "log_to_console": true,
+    // Clio logs to file in the specified directory only if "log_directory" is set
+    // "log_directory": "./clio_log",
+    "log_rotation_size": 2048,
+    "log_directory_max_size": 51200,
+    "log_rotation_hour_interval": 12,
+    "log_tag_style": "uint",
+    "extractor_threads": 8,
+    "read_only": false,
+    // "start_sequence": [integer] the ledger index to start from,
+    // "finish_sequence": [integer] the ledger index to finish at,
+    // "ssl_cert_file" : "/full/path/to/cert.file",
+    // "ssl_key_file" : "/full/path/to/key.file"
+    "api_version": {
+        "min": 1, // Minimum API version supported (could be 1 or 2)
+        "max": 2, // Maximum API version supported (could be 1 or 2, but >= min)
+        "default": 1 // Clio behaves the same as rippled by default
+    }
+}

docs/examples/infrastructure/README.md

@@ -0,0 +1,25 @@
+# Example of clio monitoring infrastructure
+
+This directory contains an example of docker based infrastructure to collect and visualise metrics from clio.
+
+The structure of the directory:
+- `compose.yaml`
+   Docker-compose file with Prometheus and Grafana set up.
+- `prometheus.yaml`
+  Defines metrics collection from Clio and Prometheus itself.
+  Demonstrates how to setup Clio target and Clio's admin authorisation in Prometheus.
+- `grafana/clio_dashboard.json`
+  Json file containing preconfigured dashboard in Grafana format.
+- `grafana/dashboard_local.yaml`
+  Grafana configuration file defining the directory to search for dashboards json files.
+- `grafana/datasources.yaml`
+  Grafana configuration file defining Prometheus as a data source for Grafana.
+
+## How to try
+
+1. Make sure you have `docker` and `docker-compose` installed.
+2. Run `docker-compose up -d` from this directory. It will start docker containers with Prometheus and Grafana.
+3. Open [http://localhost:3000/dashboards](http://localhost:3000/dashboards). Grafana login `admin`, password `grafana`.
+There will be preconfigured Clio dashboard.
+
+If Clio is not running yet launch Clio to see metrics. Some of the metrics may appear only after requests to Clio.

docs/examples/infrastructure/compose.yaml

@@ -0,0 +1,20 @@
+services:
+  prometheus:
+    image: prom/prometheus
+    ports:
+      - 9090:9090
+    volumes:
+      - ./prometheus.yaml:/etc/prometheus/prometheus.yml
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+  grafana:
+    image: grafana/grafana
+    ports:
+      - 3000:3000
+    environment:
+      - GF_SECURITY_ADMIN_USER=admin
+      - GF_SECURITY_ADMIN_PASSWORD=grafana
+    volumes:
+      - ./grafana/datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml
+      - ./grafana/dashboard_local.yaml:/etc/grafana/provisioning/dashboards/local.yaml
+      - ./grafana/clio_dashboard.json:/var/lib/grafana/dashboards/clio_dashboard.json

docs/examples/infrastructure/grafana/dashboard_local.yaml

@@ -0,0 +1,23 @@
+apiVersion: 1
+
+providers:
+  - name: 'Clio dashboard'
+    # <int> Org id. Default to 1
+    orgId: 1
+    # <string> name of the dashboard folder.
+    folder: ''
+    # <string> folder UID. will be automatically generated if not specified
+    folderUid: ''
+    # <string> provider type. Default to 'file'
+    type: file
+    # <bool> disable dashboard deletion
+    disableDeletion: false
+    # <int> how often Grafana will scan for changed dashboards
+    updateIntervalSeconds: 10
+    # <bool> allow updating provisioned dashboards from the UI
+    allowUiUpdates: false
+    options:
+      # <string, required> path to dashboard files on disk. Required when using the 'file' type
+      path: /var/lib/grafana/dashboards
+      # <bool> use folder names from filesystem to create folders in Grafana
+      foldersFromFilesStructure: true

docs/examples/infrastructure/grafana/datasources.yaml

@@ -0,0 +1,8 @@
+apiVersion: 1
+
+datasources:
+- name: Prometheus
+  type: prometheus
+  url: http://prometheus:9090
+  isDefault: true
+  access: proxy

docs/examples/infrastructure/prometheus.yaml

@@ -0,0 +1,19 @@
+scrape_configs:
+- job_name: clio
+  scrape_interval: 5s
+  scrape_timeout: 5s
+  authorization:
+    type: Password
+    # sha256sum from password `xrp`
+    # use echo -n 'your_password' | shasum -a 256 to get hash
+    credentials: 0e1dcf1ff020cceabf8f4a60a32e814b5b46ee0bb8cd4af5c814e4071bd86a18
+  static_configs:
+  - targets:
+    -  host.docker.internal:51233
+- job_name: prometheus
+  honor_timestamps: true
+  scrape_interval: 15s
+  scrape_timeout: 10s
+  static_configs:
+  - targets:
+    - localhost:9090

docs/logging.md

@@ -40,7 +40,7 @@ If no override is present for a given channel, that channel will log at the seve
 The log channels that can be overridden are: `Backend`, `WebServer`, `Subscriptions`, `RPC`, `ETL` and `Performance`.
 
 > [!NOTE]
-> See [example-config.json](../example-config.json) for more details.
+> See [example-config.json](../docs/examples/config/example-config.json) for more details.
 
 ## `log_to_console`
 

docs/metrics-and-static-analysis.md

@@ -10,7 +10,7 @@ To completely disable Prometheus metrics add `"prometheus": { "enabled": false }
 
 It is important to know that Clio responds to Prometheus request only if they are admin requests. If you are using the admin password feature, the same password should be provided in the Authorization header of Prometheus requests.
 
-You can find an example docker-compose file, with Prometheus and Grafana configs, in [examples/infrastructure](../examples/infrastructure/).
+You can find an example docker-compose file, with Prometheus and Grafana configs, in [examples/infrastructure](../docs/examples/infrastructure/).
 
 ## Using `clang-tidy` for static analysis
 

docs/run-clio.md

@@ -79,4 +79,4 @@ All of the above are optional.
 Clio will fallback to hardcoded defaults when these values are not specified in the config file, or if the configured values are outside of the minimum and maximum supported versions hardcoded in [src/rpc/common/APIVersion.h](../src/rpc/common/APIVersion.hpp).
 
 > [!TIP]
-> See the [example-config.json](../example-config.json) for more details.
+> See the [example-config.json](../docs/examples/config/example-config.json) for more details.