Cleanup location of docs and example files (#1195)

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