diff --git a/test-network/CHAINCODE_AS_A_SERVICE_TUTORIAL.md b/test-network/CHAINCODE_AS_A_SERVICE_TUTORIAL.md index e94070d0..7de0d43c 100644 --- a/test-network/CHAINCODE_AS_A_SERVICE_TUTORIAL.md +++ b/test-network/CHAINCODE_AS_A_SERVICE_TUTORIAL.md @@ -16,7 +16,7 @@ We need to use the latest 2.4.1 release as this contains some improvements to ma ## End-to-end with the the test-network -The `test-network` and some of the chaincodes have been updated to support running chaincode-as-a-service. The commands below assume that you've got the latest fabric-samples cloned, along with the latest Fabric docker images. +The `test-network` and some of the chaincodes have been updated to support running chaincode-as-a-service. The commands below assume that you've got the latest fabric-samples cloned, along with the latest Fabric docker images. It's useful to have two terminal windows open, one for starting the Fabric Network, and a second for monitoring all the docker containers. @@ -27,7 +27,6 @@ In your 'monitoring' window, run this to watch all activity from the all the doc ./test-network/monitordocker.sh ``` - In the 'Fabric Network' window, start the test network ```bash @@ -44,6 +43,7 @@ You can run other variants of this command, eg to use CouchDB or CAs, without af Note that the order listed isn't mandatory. The key thing is that the containers are running before the first transaction is set by the peer. Remember that this could be on the `commit` if the `initRequired` flag is set. This sequence can be run as follows + ```bash ./network.sh deployCCAAS -ccn basicts -ccp ../asset-transfer-basic/chaincode-typescript ``` @@ -68,15 +68,14 @@ export FABRIC_CFG_PATH=${PWD}/../config peer chaincode query -C mychannel -n basicts -c '{"Args":["org.hyperledger.fabric:GetMetadata"]}' | jq ``` -If you don't have `jq` installed omit ` | jq`. The metadata shows the details of the deployed contract and is JSON, so jq makes it easier to read. You can repeat the above commands for org2 to confirm that is working. +If you don't have `jq` installed omit `| jq`. The metadata shows the details of the deployed contract and is JSON, so jq makes it easier to read. You can repeat the above commands for org2 to confirm that is working. -To run the Java example, change the `deployCCAAS` command as follows, This will create a two new containers. +To run the Java example, change the `deployCCAAS` command as follows, This will create two new containers. ```bash -./network.sh deployCCAAS -ccn basicj -ccp ../asset-transfer-basic/chaincode-typescript +./network.sh deployCCAAS -ccn basicj -ccp ../asset-transfer-basic/chaincode-java ``` - ### Troubleshooting If the JSON structure passed in is badly formatted JSON this error will be in the peer log: @@ -85,7 +84,7 @@ If the JSON structure passed in is badly formatted JSON this error will be in th ::Error: Failed to unmarshal json: cannot unmarshal string into Go value of type map[string]interface {} command=build ``` -## How to configure each langauge +## How to configure each language Each language can work in the '-as-a-service' mode. Note that the approaches here are based on the very latest libraries. When starting the image you can also specify any of the TLS options or additional logging options for the respective chaincode libraries. @@ -96,7 +95,7 @@ With the v2.4.1 Java Chaincode libraries, there are no code changes to make or b A sample docker run command could be as follows. The two key variables that are needed are the `CHAINCODE_SERVER_ADDRESS` and `CORE_CHAICODE_ID_NAME` -``` +```bash docker run --rm -d --name peer0org1_assettx_ccaas \ --network fabric_test \ -e CHAINCODE_SERVER_ADDRESS=0.0.0.0:9999 \ @@ -108,18 +107,15 @@ A sample docker run command could be as follows. The two key variables that are For Node.js (JavaScript or TypeScript) chaincode, typically the `package.json` has `fabric-chaincode-node start` as the main start command. To run in the '-as-a-service' mode change this to `fabric-chaincode-node server --chaincode-address=$CHAINCODE_SERVER_ADDRESS --chaincode-id=$CHAINCODE_ID` -### Golang - -TBC - ## Debugging the Chaincode Running in the '-as-a-service' mode offers options, similar to how the Fabric 'dev' mode works on debugging code. The restrictions of the 'dev' mode don't apply. -There is an option `-ccaasdr false` that can be provided on the `deployCCAAS` command. This will _not_ build the docker image or start a docker container. It does output the commands it would have run. +There is an option `-ccaasdr false` that can be provided on the `deployCCAAS` command. This will _not_ build the docker image or start a docker container. It does output the commands it would have run. Run this command, and you'll see similar output -``` + +```bash ./network.sh deployCCAAS -ccn basicj -ccp ../asset-transfer-basic/chaincode-java -ccaasdr false #.... Not building docker image; this the command we would have run @@ -129,14 +125,15 @@ Not starting docker containers; these are the commands we would have run docker run --rm -d --name peer0org1_basicj_ccaas --network fabric_test -e CHAINCODE_SERVER_ADDRESS=0.0.0.0:9999 -e CHAINCODE_ID=basicj_1.0:59dcd73a14e2db8eab7f7683343ce27ac242b93b4e8075605a460d63a0438405 -e CORE_CHAINCODE_ID_NAME=basicj_1.0:59dcd73a14e2db8eab7f7683343ce27ac242b93b4e8075605a460d63a0438405 basicj_ccaas_image:latest ``` -Depending on your directory, and what you need to debug you might need to adjust these commands. +Depending on your directory, and what you need to debug you might need to adjust these commands. ### Building the docker image -The first thing needed is to build the docker image. Remember that so long as the peer can connect to the hostname:port given in the `connection.json` the actual packaging of the chaincode is not important to the peer. You are at liberty to adjust the dockerfiles given here. + +The first thing needed is to build the docker image. Remember that so long as the peer can connect to the hostname:port given in the `connection.json` the actual packaging of the chaincode is not important to the peer. You are at liberty to adjust the dockerfiles given hgere. To manually build the docker image for the `asset-transfer-basic/chaincode-java` -``` +```bash docker build -f ../asset-transfer-basic/chaincode-java/Dockerfile -t basicj_ccaas_image:latest --build-arg CC_SERVER_PORT=9999 ../asset-transfer-basic/chaincode-java ``` @@ -145,13 +142,14 @@ docker build -f ../asset-transfer-basic/chaincode-java/Dockerfile -t basicj_ccaa You need to start the docker container. NodeJs for example, could be started like this -``` + +```bash docker run --rm -it -p 9229:9229 --name peer0org2_basic_ccaas --network fabric_test -e DEBUG=true -e CHAINCODE_SERVER_ADDRESS=0.0.0.0:9999 -e CHAINCODE_ID=basic_1.0:7c7dff5cdc43c77ccea028c422b3348c3c1fb5a26ace0077cf3cc627bd355ef0 -e CORE_CHAINCODE_ID_NAME=basic_1.0:7c7dff5cdc43c77ccea028c422b3348c3c1fb5a26ace0077cf3cc627bd355ef0 basic_ccaas_image:latest ``` Java for example, could be started like this -``` +```bash docker run --rm -it --name peer0org1_basicj_ccaas -p 8000:8000 --network fabric_test -e DEBUG=true -e CHAINCODE_SERVER_ADDRESS=0.0.0.0:9999 -e CHAINCODE_ID=basicj_1.0:b014a03d8eb1898535e25b4dfeeb3f8244c9f07d91a06aec03e2d19174c45e4f -e CORE_CHAINCODE_ID_NAME=basicj_1.0:b014a03d8e b1898535e25b4dfeeb3f8244c9f07d91a06aec03e2d19174c45e4f basicj_ccaas_image:latest ``` @@ -159,9 +157,9 @@ b1898535e25b4dfeeb3f8244c9f07d91a06aec03e2d19174c45e4f basicj_ccaas_image:lates For all languages please note: - the name of the container needs to match what the peer has in the `connection.json` -- the peer is connecting to the chaincode container via the docker network. Therefore port 9999 does not need to forwarded to the host -- If you are going to single step in a debugger, then you are likely to hit the Fabric transaction timeout value. By default this is 30seconds, meaning the chaincode has to complete transactions in 30 seconds or less. In the `test-network/docker/docker-composer-test-net.yml` add `CORE_CHAINCODE_EXECUTETIMEOUT=300s` to the environment options of each peer. -- In the command above, the `-d` option has been removed from the command the test-network would have used, and has been replaced with `-it`. This means that docker container will not run in detached mode, and will run in the foregroud. +- the peer is connecting to the chaincode container via the docker network. Therefore port 9999 does not need to be forwarded to the host +- If you are going to single step in a debugger, then you are likely to hit the Fabric transaction timeout value. By default this is 30 seconds, meaning the chaincode has to complete transactions in 30 seconds or less. In the `test-network/docker/docker-composer-test-net.yml` add `CORE_CHAINCODE_EXECUTETIMEOUT=300s` to the environment options of each peer. +- In the command above, the `-d` option has been removed from the command the test-network would have used, and has been replaced with `-it`. This means that docker container will not run in detached mode, and will run in the foreground. For Node.js please note: @@ -170,11 +168,11 @@ For Node.js please note: - If you are using typescript, ensure that the typescript has been compiled with sourcemaps, otherwise a debugger will struggle matching up the source code. For Java please note: + - Port 800 is forwarded, the debug port for the JVM - `-e DEBUG=true` will trigger the node runtime to be started in debug mode. This is encoded in the `docker/docker-entrypoint.sh` script - this is an example and you may wish to remove this in production images for security - In the java command with the option to start the debugger is `java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=0.0.0.0:8000 -jar /chaincode.jar` Note the `0.0.0.0` as the debug port needs to be bound to all network adapters so the debugger can be attached from outside the container - ## Running with multiple peers In the traditional approach, each peer that the chaincode is approved on will have a container running the chaincode. With the '-as-a-service' approach we need to achieve the same architecture. @@ -194,7 +192,7 @@ We can define the address to be a template in the `connection.json` In the peer's environment configuration we then set for org1's peer1 -``` +```bash CHAINCODE_AS_A_SERVICE_BUILDER_CONFIG="{\"peername\":\"org1peer1\"}" ``` diff --git a/test-network/README.md b/test-network/README.md index d982d51e..4315b639 100644 --- a/test-network/README.md +++ b/test-network/README.md @@ -1,10 +1,11 @@ -## Running the test network +# Running the test network You can use the `./network.sh` script to stand up a simple Fabric test network. The test network has two peer organizations with one peer each and a single node raft ordering service. You can also use the `./network.sh` script to create channels and deploy chaincode. For more information, see [Using the Fabric test network](https://hyperledger-fabric.readthedocs.io/en/latest/test_network.html). The test network is being introduced in Fabric v2.0 as the long term replacement for the `first-network` sample. Before you can deploy the test network, you need to follow the instructions to [Install the Samples, Binaries and Docker Images](https://hyperledger-fabric.readthedocs.io/en/latest/install.html) in the Hyperledger Fabric documentation. ## Using the Peer commands + The `setOrgEnv.sh` script can be used to setup the environment variables for the ogrganziations, this will will help to be able to use the `peer` commands directly. First, ensure that the peer binaries are on your path, and the Fabric Config path is set Assuming that you're in the `test-network` directory. @@ -27,4 +28,8 @@ The `setOrgEnv` script outputs a series of `=` strings. These can t ## Chaincode-as-a-service -To learn more about how to use the improvements to the Chaincode-as-a-service please see this [tutorial](./test-network/../CHAINCODE_AS_A_SERVICE_TUTORIAL.md). It is expected that this will move to augment the tutorial in the [Hyperledger Fabric ReadTheDocs](https://hyperledger-fabric.readthedocs.io/en/release-2.4/cc_service.html) \ No newline at end of file +To learn more about how to use the improvements to the Chaincode-as-a-service please see this [tutorial](./CHAINCODE_AS_A_SERVICE_TUTORIAL.md). It is expected that this will move to augment the tutorial in the [Hyperledger Fabric ReadTheDocs](https://hyperledger-fabric.readthedocs.io/en/release-2.4/cc_service.html) + +## Prometheus and Grafana + +To enable the collection of fabric networks into Prometheus and also have a default Grafana dashboard please see this [tutorial](prometheus-grafana/README.md). diff --git a/test-network/prometheus-grafana/README.md b/test-network/prometheus-grafana/README.md index 64abae9e..6da075d5 100644 --- a/test-network/prometheus-grafana/README.md +++ b/test-network/prometheus-grafana/README.md @@ -1,49 +1,52 @@ # Description -This sample provides an environment to display and capture metrics from the test-network in real time. It consists of a docker-compose file that starts a prometheus and grafana server setup configured to collect and display metrics for the test network. +This sample provides an environment to display and capture metrics from the test-network in real time. It consists of a docker-compose file that starts a Prometheus and Grafana server setup configured to collect and display metrics for the test network. -# Requirements +## Requirements -This sample has been tested and is recomended to be used on **linux** in order to fully benefit from its capabilities, however it can be deployed and works on MacOS-intel machine as well (some modification to the cadvisor docker image and related queries are required to show docker containers metrics). +This sample has been tested and is recommended to be used on **linux** in order to fully benefit from its capabilities, however it can be deployed and works on MacOS-intel machine as well (some modification to the cadvisor docker image and related queries are required to show docker containers metrics). You will need to have installed **docker-compose with version 1.29 or above** (note that this is higher than the v1.14 requirement requested for the test-network). -# How to use +## How to use 1. Go to the test-network directory and run bring up the test-network **./network.sh up createChannel** 2. Bring up the Prometheus/Grafana network in the test-network/prometheus-grafana directory and run **docker-compose up -d** 3. Log in: type “localhost:3000” on your web browser -> username=“admin”, password=“admin” -> set a new password -4. Browse dashboard and analyse results +4. Browse dashboard and analyse results - The default dashboard "HLF Performances Review" can be found and displayed by hovering over the dashboard menu and clicking on the browse button. ![picture alt]("https://user-images.githubusercontent.com/86831094/149115445-5e5f6d95-ecc3-4b46-aadb-5c01148770b3.png "Title is optional") Once opened the dashboard, to display the collected metrics and data, adjust the timeframe on the top right to focus on the latest timespan when the network was up. -5. Deploy a chaincode (i.e. "./network.sh deployCC -ccn basic -ccp ../asset-transfer-basic/chaincode-go -ccl go"), start using the test-network and use the grafana dashboard to analyse and assess your network performances. -Extras: add new queries, modify dashboard & add relevant changes to main repo --> extract json and add it to "grafana/dashboards/hlf-performances.json". +5. Deploy a chaincode (i.e. "./network.sh deployCC -ccn basic -ccp ../asset-transfer-basic/chaincode-go -ccl go"), start using the test-network and use the Grafana dashboard to analyse and assess your network performances. +Extras: add new queries, modify dashboard & add relevant changes to main repo --> extract json and add it to "Grafana/dashboards/hlf-performances.json". Metrics can also be displayed directly from Prometheus by going to "localhost:9090". -# Docker Compose +## Docker Compose Brings up - - a prometheus sever (port 9090) -> pulls metrics from peers, orderer, system(node exporter) and containers(cadvisor) - - grafana sever (port 3000) -> collects and display data from prometheus - - node exporter (port 9100) -> exposes systems metrics - - cadvisor (port 8080) -> exposes docker containers metrics -# Prometheus "configuration file" +- a Prometheus server (port 9090) -> pulls metrics from peers, orderer, system(node exporter) and containers(cadvisor) +- Grafana server (port 3000) -> collects and display data from Prometheus +- node exporter (port 9100) -> exposes systems metrics +- cadvisor (port 8080) -> exposes docker containers metrics -**Prometheus.yml** +## Prometheus "configuration file" + +### Prometheus.yml Fabric metrics targets: - - peer0.org1.example.com:9444 - - peer0.org2.example.com:9445 - - orderer.example.com:9443 + +- `peer0.org1.example.com:9444` +- `peer0.org2.example.com:9445` +- `orderer.example.com:9443` System and docker metrics targets: - - cadvisor:8080 - - node-exporter:9100 + +- `cadvisor:8080` +- `node-exporter:9100` Check the state of the connections with targets on http://localhost:9090/targets. -# Sources +## Sources -Prometheus docs: https://prometheus.io/docs/introduction/overview/ -Grafana docs: https://grafana.com/docs/ +[Prometheus docs](https://prometheus.io/docs/introduction/overview/) +[Grafana docs](https://grafana.com/docs/) diff --git a/test-network/prometheus-grafana/docker-compose.yaml b/test-network/prometheus-grafana/docker-compose.yaml index 992fe69c..b166f6ea 100644 --- a/test-network/prometheus-grafana/docker-compose.yaml +++ b/test-network/prometheus-grafana/docker-compose.yaml @@ -6,7 +6,7 @@ volumes: services: prometheus: - image: prom/prometheus + image: prom/prometheus:v2.32.1 container_name: prometheus volumes: - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml @@ -20,7 +20,7 @@ services: - "9090:9090" grafana: - image: grafana/grafana + image: grafana/grafana:8.3.4 container_name: grafana user: "104" depends_on: @@ -48,7 +48,7 @@ services: restart: always node-exporter: - image: prom/node-exporter + image: prom/node-exporter:v1.3.1 container_name: node-exporter volumes: - /proc:/host/proc:ro