From d835eb6d40f7e741b95d4d663b2e9146552beeb9 Mon Sep 17 00:00:00 2001 From: georgi-l95 Date: Tue, 17 Dec 2024 15:26:25 +0200 Subject: [PATCH] rework documentation Signed-off-by: georgi-l95 --- server/docs/configuration.md | 82 +++++++++++++++++++++++++++------ simulator/docs/configuration.md | 50 ++++++++++++-------- simulator/docs/quickstart.md | 34 +++----------- 3 files changed, 107 insertions(+), 59 deletions(-) diff --git a/server/docs/configuration.md b/server/docs/configuration.md index c68f65f4b..770bd7150 100644 --- a/server/docs/configuration.md +++ b/server/docs/configuration.md @@ -1,7 +1,6 @@ # Server Configuration -The components of the Hedera Block Node all support loading configuration via the -environment. +The components of the Hedera Block Node all support loading configuration via the environment. ## Default Values @@ -9,14 +8,71 @@ The default configuration allows users to quickly get up and running without hav ease of use at the trade-off of some insecure default configuration. Most configuration settings have appropriate defaults and can be left unchanged. It is recommended to browse the properties below and adjust to your needs. -| Environment Variable | Description | Default Value | -|:---|:---|---:| -| PERSISTENCE_STORAGE_LIVE_ROOT_PATH | The root path for the live storage. | | -| PERSISTENCE_STORAGE_ARCHIVE_ROOT_PATH | The root path for the archive storage. | | -| PERSISTENCE_STORAGE_TYPE | Type of the persistence storage | BLOCK_AS_LOCAL_FILE | -| CONSUMER_TIMEOUT_THRESHOLD_MILLIS | Time to wait for subscribers before disconnecting in milliseconds | 1500 | -| SERVICE_DELAY_MILLIS | Service shutdown delay in milliseconds | 500 | -| MEDIATOR_RING_BUFFER_SIZE | Size of the ring buffer used by the mediator (must be a power of 2) | 67108864 | -| NOTIFIER_RING_BUFFER_SIZE | Size of the ring buffer used by the notifier (must be a power of 2) | 2048 | -| SERVER_PORT | The port the server will listen on | 8080 | -| SERVER_MAX_MESSAGE_SIZE_BYTES | The maximum size of a message frame in bytes | 1048576 | +## ConsumerConfig + +Uses the prefix `consumer` so all properties should start with `consumer.` + +| Key | Environment Variable | Description | Default Value | +| :----------------------- | :---------------------------------- | :---------------------------------------------------------------- | ------------: | +| `timeoutThresholdMillis` | `CONSUMER_TIMEOUT_THRESHOLD_MILLIS` | Time to wait for subscribers before disconnecting in milliseconds | 1500 | + +## PersistenceConfig + +Uses the prefix `persistence.storage` so all properties should start with `persistence.storage.` + +| Key | Environment Variable | Description | Default Value | +| :---------------- | :-------------------------------------- | :------------------------------------ | --------------------: | +| `liveRootPath` | `PERSISTENCE_STORAGE_LIVE_ROOT_PATH` | The root path for the live storage | - | +| `archiveRootPath` | `PERSISTENCE_STORAGE_ARCHIVE_ROOT_PATH` | The root path for the archive storage | - | +| `type` | `PERSISTENCE_STORAGE_TYPE` | Type of the persistence storage | `BLOCK_AS_LOCAL_FILE` | + +## ServiceConfig + +Uses the prefix `service` so all properties should start with `service.` + +| Key | Environment Variable | Description | Default Value | +| :------------ | :--------------------- | :------------------------------------- | ------------: | +| `delayMillis` | `SERVICE_DELAY_MILLIS` | Service shutdown delay in milliseconds | 500 | + +## MediatorConfig + +Uses the prefix `mediator` so all properties should start with `mediator.` + +| Key | Environment Variable | Description | Default Value | +| :--------------- | :-------------------------- | :------------------------------------------------------------------ | ------------: | +| `ringBufferSize` | `MEDIATOR_RING_BUFFER_SIZE` | Size of the ring buffer used by the mediator (must be a power of 2) | 67108864 | +| `type` | `MEDIATOR_TYPE` | Type of the mediator | - | + +## NotifierConfig + +Uses the prefix `notifier` so all properties should start with `notifier.` + +| Key | Environment Variable | Description | Default Value | +| :--------------- | :-------------------------- | :------------------------------------------------------------------ | ------------: | +| `ringBufferSize` | `NOTIFIER_RING_BUFFER_SIZE` | Size of the ring buffer used by the notifier (must be a power of 2) | 2048 | + +## ProducerConfig + +Uses the prefix `producer` so all properties should start with `producer.` + +| Key | Environment Variable | Description | Default Value | +| :----- | :------------------- | :------------------- | ------------: | +| `type` | `PRODUCER_TYPE` | Type of the producer | - | + +## ServerConfig + +Uses the prefix `server` so all properties should start with `server.` + +| Key | Environment Variable | Description | Default Value | +| :-------------------- | :------------------------------ | :------------------------------------------- | ------------: | +| `maxMessageSizeBytes` | `SERVER_MAX_MESSAGE_SIZE_BYTES` | The maximum size of a message frame in bytes | 1048576 | +| `port` | `SERVER_PORT` | The port the server will listen on | 8080 | + +## PrometheusConfig + +Uses the prefix `prometheus` so all properties should start with `prometheus.` + +| Key | Environment Variable | Description | Default Value | +| :------------------- | :-------------------------------- | :------------------------------------------ | ------------: | +| `endpointEnabled` | `PROMETHEUS_ENDPOINT_ENABLED` | Whether the Prometheus endpoint is enabled | - | +| `endpointPortNumber` | `PROMETHEUS_ENDPOINT_PORT_NUMBER` | The port number for the Prometheus endpoint | - | diff --git a/simulator/docs/configuration.md b/simulator/docs/configuration.md index 939ea5213..c7b4c0d90 100644 --- a/simulator/docs/configuration.md +++ b/simulator/docs/configuration.md @@ -1,6 +1,7 @@ # Configuration There are 3 configuration sets: + 1. [BlockStreamConfig](#blockstreamconfig): contains the configuration for the Block Stream Simulator logic. 1. [GeneratorConfig](#generatorconfig): contains the configuration for the Block Stream Simulator generation module. 1. [GrpcConfig](#grpcconfig): contains the configuration for the gRPC communication with the Block-Node. @@ -9,32 +10,43 @@ There are 3 configuration sets: Uses the prefix `blockStream` so all properties should start with `blockStream.` -| Key | Description | Default Value | -|:---|:---|---:| -| `simulatorMode` | The desired simulator mode to use, it can be either `PUBLISHER` or `CONSUMER`. | `PUBLISHER` | -| `delayBetweenBlockItems` | The delay between each block item in nanoseconds, only applicable when streamingMode=CONSTANT_RATE | `1_500_000` | -| `maxBlockItemsToStream` | exit condition for the simulator and the circular implementations such as `BlockAsDir` or `BlockAsFile` implementations | `10_000` | -| `streamingMode` | can either be `CONSTANT_RATE` or `MILLIS_PER_BLOCK` | `CONSTANT_RATE` | -| `millisecondsPerBlock` | if streamingMode is `MILLIS_PER_BLOCK` this will be the time to wait between blocks in milliseconds | `1_000` | -| `blockItemsBatchSize` | the number of block items to send in a single batch, however if a block has less block items, it will send all the items in a block | `1_000` | +| Key | Environment Variable | Description | Default Value | +| :----------------------- | :--------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | --------------: | +| `simulatorMode` | `BLOCK_STREAM_SIMULATOR_MODE` | The desired simulator mode to use, it can be either `PUBLISHER` or `CONSUMER`. | `PUBLISHER` | +| `delayBetweenBlockItems` | `BLOCK_STREAM_DELAY_BETWEEN_BLOCK_ITEMS` | The delay between each block item in nanoseconds, only applicable when streamingMode=CONSTANT_RATE | `1_500_000` | +| `maxBlockItemsToStream` | `BLOCK_STREAM_MAX_BLOCK_ITEMS_TO_STREAM` | exit condition for the simulator and the circular implementations such as `BlockAsDir` or `BlockAsFile` implementations | `10_000` | +| `streamingMode` | `BLOCK_STREAM_STREAMING_MODE` | can either be `CONSTANT_RATE` or `MILLIS_PER_BLOCK` | `CONSTANT_RATE` | +| `millisecondsPerBlock` | `BLOCK_STREAM_MILLISECONDS_PER_BLOCK` | if streamingMode is `MILLIS_PER_BLOCK` this will be the time to wait between blocks in milliseconds | `1_000` | +| `blockItemsBatchSize` | `BLOCK_STREAM_BLOCK_ITEMS_BATCH_SIZE` | the number of block items to send in a single batch, however if a block has less block items, it will send all the items in a block | `1_000` | ## GeneratorConfig Uses the prefix `generator` so all properties should start with `generator.` -| Key | Description | Default Value | -|:---|:---|---:| -| `generationMode` | The desired generation Mode to use, it can only be `DIR` or `AD_HOC` | `DIR` | -| `folderRootPath` | If the generationMode is DIR this will be used as the source of the recording to stream to the Block-Node | `` | -| `managerImplementation` | The desired implementation of the BlockStreamManager to use, it can only be `BlockAsDirBlockStreamManager`, `BlockAsFileBlockStreamManager` or `BlockAsFileLargeDataSets` | `BlockAsFileBlockStreamManager` | -| `paddedLength` | on the `BlockAsFileLargeDataSets` implementation, the length of the padded left zeroes `000001.blk.gz` | 36 | -| `fileExtension` | on the `BlockAsFileLargeDataSets` implementation, the extension of the files to be streamed | `.blk.gz` | +| Key | Environment Variable | Description | Default Value | +| :---------------------- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------: | +| `generationMode` | `GENERATOR_GENERATION_MODE` | The desired generation Mode to use, it can only be `DIR` or `AD_HOC` | `DIR` | +| `folderRootPath` | `GENERATOR_FOLDER_ROOT_PATH` | If the generationMode is DIR this will be used as the source of the recording to stream to the Block-Node | `` | +| `managerImplementation` | `GENERATOR_MANAGER_IMPLEMENTATION` | The desired implementation of the BlockStreamManager to use, it can only be `BlockAsDirBlockStreamManager`, `BlockAsFileBlockStreamManager` or `BlockAsFileLargeDataSets` | `BlockAsFileBlockStreamManager` | +| `paddedLength` | `GENERATOR_PADDED_LENGTH` | on the `BlockAsFileLargeDataSets` implementation, the length of the padded left zeroes `000001.blk.gz` | 36 | +| `fileExtension` | `GENERATOR_FILE_EXTENSION` | on the `BlockAsFileLargeDataSets` implementation, the extension of the files to be streamed | `.blk.gz` | +| `startBlockNumber` | `GENERATOR_START_BLOCK_NUMBER` | The starting block number for block generation | - | +| `endBlockNumber` | `GENERATOR_END_BLOCK_NUMBER` | The ending block number for block generation | - | ## GrpcConfig Uses the prefix `grpc` so all properties should start with `grpc.` -| Key | Description | Default Value | -|:---|:---|---:| -| `serverAddress` | The host of the Block-Node | `localhost` | -| `port` | The port of the Block-Node | `8080` | +| Key | Environment Variable | Description | Default Value | +| :-------------- | :-------------------- | :------------------------- | ------------: | +| `serverAddress` | `GRPC_SERVER_ADDRESS` | The host of the Block-Node | `localhost` | +| `port` | `GRPC_PORT` | The port of the Block-Node | `8080` | + +## PrometheusConfig + +Uses the prefix `prometheus` so all properties should start with `prometheus.` + +| Key | Environment Variable | Description | Default Value | +| :------------------- | :-------------------------------- | :------------------------------------------ | ------------: | +| `endpointEnabled` | `PROMETHEUS_ENDPOINT_ENABLED` | Whether the Prometheus endpoint is enabled | - | +| `endpointPortNumber` | `PROMETHEUS_ENDPOINT_PORT_NUMBER` | The port number for the Prometheus endpoint | - | diff --git a/simulator/docs/quickstart.md b/simulator/docs/quickstart.md index b0202b012..df745addb 100644 --- a/simulator/docs/quickstart.md +++ b/simulator/docs/quickstart.md @@ -72,33 +72,13 @@ The simulator can run in two modes (Publisher and Consumer) and provides metrics ./gradlew startDockerContainer ``` -2. Configure and run the simulator in Publisher mode: - - - In `app.properties`, set: - ```properties - blockStream.simulatorMode=PUBLISHER - prometheus.endpointEnabled=true - prometheus.endpointPortNumber=9998 - ``` - - Start the simulator: - ```bash - ./gradlew :simulator:run - ``` - -3. Configure and run the simulator in Consumer mode: - - - In `app.properties`, update: - ```properties - blockStream.simulatorMode=CONSUMER - prometheus.endpointEnabled=true - prometheus.endpointPortNumber=9997 - ``` - - Start another instance of the simulator: - ```bash - ./gradlew :simulator:run - ``` - -4. Access the metrics: +2. Start the simulator containers (both Publisher and Consumer): + + ```bash + ./gradlew startSimulatorDockerContainers + ``` + +3. Access the metrics: - Open Grafana at http://localhost:3000 - Navigate to Dashboards - You'll find two dashboards: