Agent Setup


The agent requires the following environment variables to be set to properly upload data to BlocWatch. How these variables are set will depend on the execution environment. Details for Docker and Kubernetes are provided below.

  1. BLOCWATCH_AGENT_CHAINS: Found in Registering a Blockchain
    • This variable should include a comma-separated list of blockchain references from which the agent should collect data.
  2. BLOCWATCH_AGENT_REF: Found in Creating an Agent
    • A reference to the agent that was created in the BlocWatch application.
  3. BLOCWATCH_AGENT_AUTH: Found in Creating a Service Account
    • A file, generally mounted within the agent Docker image, that contains credentials for a BlocWatch service account.
  4. [OPTIONAL] BLOCWATCH_AGENT_FABRIC_METRICS_ENDPOINTS: A comma delimited list specifying endpoints in host:port form identifying nodes that expose Prometheus metrics.

BlocWatch has the ability to collect metrics from deployed blockchain peers when those peers have Prometheus metrics enabled.

If you need help getting prometheus metrics enabled, see:

Standalone Docker

  1. If you have not already done so, download the agent credentials and name the file 'blocwatch-agent-auth.json'.

  2. Pull the docker image:

    $ docker pull blocwatch/agent

  3. Run the docker command to connect our agent:

    • The first block of code below is your template for the docker command:
      • Replace '[path/to/secret/file/SECRET_FILE_NAME.json]' with the absolute path to your secret credentials file you downloaded.
      • Replace [SECRET_FILE_NAME.json] with the name of your secret file (e.g. blocwatch-agent-auth.json)
      • Replace [YOUR_AGENT_REF] with the Agent Reference ID
      • Replace [YOUR_AGENT_CHAINS] with the list of Blockchain Reference IDs you want monitored
      • Replace [YOUR_BLOCWATCH_AGENT_FABRIC_METRICS_ENDPOINTS] with the comma separated list of host/ports you wish to monitor
$ docker run --restart=unless-stopped \
  -v '[path/to/secret/file/SECRET_FILE_NAME.json]':/'[SECRET_FILE_NAME.json]' \
  -it blocwatch/agent
  • Final command with the appropriate information:
$ docker run --restart=unless-stopped \
  -v /Users/public/Desktop/blocwatch-agent-auth.json:/blocwatch-agent-auth.json \
  -e BLOCWATCH_AGENT_REF='v1/organizations/demo-chain-fabric/agents/agent-demo-chain-fabric' \
  -e BLOCWATCH_AGENT_AUTH='/blocwatch-agent-auth.json' \
  -e BLOCWATCH_AGENT_CHAINS='v1/organizations/demo-chain-fabric/chains/fabric/fabric-blockchain-demo' \
  -it blocwatch/agent

Side Notes:

  • Notice that the three reference fields (AGENT_REF, AGENT_AUTH, and AGENT_CHAINS) use quotes but the path does not:
    • If you are on a mac, it might try to auto correct those into smart quotes. Your command will throw an error if it has smart quotes in it.
  • Providing an absolute path is not required. However, if you decide to not do that, you will have to be in the directory that contains the file whenever running the command. In which case the second line of your command will look like this:

    -v blocwatch-agent-auth.json:/blocwatch-agent-auth.json


There are four steps to starting the BlocWatch agent on Kubernetes.

  1. If you have not already done so, download the agent credentials and name the file 'blocwatch-agent-auth.json'.

  2. Create a secret in kubernetes from the file 'blocwatch-agent-auth.json':

$ kubectl create secret generic blocwatch-agent-service-account \
      --from-file blocwatch-agent-auth.json
  1. Create a YAML file, named blocwatch-agent-deployment.yaml, describing the agent deployment.

In the below example, replace [YOUR_AGENT_REF] and [YOUR_AGENT_CHAINS] with a reference to the agent and a comma-separated list of blockchain references that the agent should monitor.

  apiVersion: apps/v1
  kind: Deployment
    name: blocwatch-agent
    labels: blocwatch-agent
    replicas: 1

      matchLabels: blocwatch-agent

        name: agent

        - name: "blocwatch-agent-service-account"
            secretName: "blocwatch-agent-service-account"
        - name: blocwatch-agent
          imagePullPolicy: "Always"
          command: ["/usr/bin/python3", "/"]
          - name: BLOCWATCH_AGENT_REF
            value: "[YOUR_AGENT_REF]"
          - name: BLOCWATCH_AGENT_CHAINS
            value: "[YOUR_AGENT_CHAINS]"
          - name: BLOCWATCH_AGENT_AUTH
            value: "/secrets/blocwatch-agent-service-account/blocwatch-agent-auth.json"
          - mountPath: /secrets/blocwatch-agent-service-account
            name: "blocwatch-agent-service-account"
            readOnly: true

  1. Have Kubernetes launch the agent:

    $ kubectl apply -f blocwatch-agent-deployment.yaml

  2. Verify things are up and running:

    $ kubectl get pods


The agent will periodically check BlocWatch for updates. When a new version is available, the agent will automatically update itself to the latest version, within its existing container. No manual intervention is needed to stop, update, or restart the agent.