mirror of
https://github.com/hyperledger/fabric-samples.git
synced 2026-06-17 07:25:10 +00:00
Minor improvement to test network docs (#607)
Also fix the version of prometheus and grafana being used to ensure the queries remain compatible as well as avoid issues whether they may not work if latest images already exist on machine but are not at a level that will work Signed-off-by: D <d_kelsey@uk.ibm.com> Co-authored-by: D <d_kelsey@uk.ibm.com>
This commit is contained in:
Dave Kelsey
GitHub
parent
f79190e88b
commit
e2d351ed61
4 changed files with 57 additions and 51 deletions
|
|
@ -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\"}"
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -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 `<name>=<value>` 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)
|
||||
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).
|
||||
|
|
|
|||
|
|
@ -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/)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue