Birdwatcher debugging tool

Birdwatcher is a command-line debugging tool for Milvus. Using Birdwatcher, you can connect to etcd or Milvus or both and check the state of the Milvus system.

watsonx.data on IBM Software Hub

watsonx.data Developer edition

etcd is a metadata engine that manages the storage and access of metadata. This topic explains how to connect and execute Birdwatcher with etcd.

Executing Birdwatcher inside etcd

Birdwatcher is available inside etcd pod in /usr/birdwatcher. Complete the following steps to log into etcd and execute Birdwatcher.

Procedure

  1. Set the project as cpd-instance. 
    oc project cpd-instance
  2. Run the following command to get the etcd pod details. 
    oc get pods | grep etcd
  3. Select one of the etcd pods and run the following command to log into it. 
    oc exec -it <etcd-pod-name> bash
    For example:
    oc exec -it ibm-lh-lakehouse-milvus922-etcd-0 bash
  4. Run the following command to change to the path to /usr/birdwatcher. 
    cd /usr/birdwatcher
  5. Run the following command to execute Birdwatcher CLI. 
    ./birdwatcher
  6. Run the following command to connect to etcd. 
    connect --etcd https://localhost:<LOCAL_PORT> --enableTLS true --etcdCert <tls.crt path> --etcdKey <tls.key path> --rootCAPem <ca.crt path>
    For example:
    connect --etcd https://localhost:2379 --enableTLS true --etcdCert /mnt/infra/tls/tls.crt --etcdKey /mnt/infra/tls/tls.key --rootCAPem /mnt/infra/tls/ca.crt

Download and set up Birdwatcher externally

To download and set up Birdwatcher externally (Birdwatcher running as an independent POD) and to connect to etcd, complete the following steps:

Procedure

  1. Download the latest Birdwatcher binary file from the Assets section here or by running the following command. 
    curl –Lo birdwatcher.tar.gz <latest-birdwatcher-binary-link>
    For example:
    curl –Lo birdwatcher.tar.gz https://github.com/milvus-io/birdwatcher/releases/download/v1.0.5/birdwatcher_Linux_x86_64.tar.gz
  2. Run the following command to extract the Birdwatcher binary file. 
    $ tar -xvzf birdwatcher.tar.gz
  3. Run the following command to make the extracted file executable. 
    $ chmod +x birdwatcher.tar.gz
  4. Run the following command to port forward the etcd port in CPD. 
    $kubectl port-forward <etcd-pod-name> <LOCAL_PORT>:<POD_PORT>
    For example:
    $kubectl port-forward ibm-lh-lakehouse-milvus922-etcd-0 2379:2379
    Port forwarding is used to allow clients to communicate with the etcd cluster through a single endpoint.
  5. Run the following command to connect to your etcd pod. 
    $ oc exec-it <etcd-pod-name> bash
  6. Run the following command to change to the /mnt/infra/tls/ directory inside the etcd pod. 
    $ cd /mnt/infra/tls/
  7. Copy the TLS certificate (tls.crt), TLS key (tls.key), and CA certificate (ca.crt) to your directory.
  8. Run the following commands:
    1. Execute the Birdwatcher CLI. 
      $./birdwatcher
    2. Connect Birdwatcher to etcd. 
      connect --etcd localhost:<LOCAL_PORT> --enableTLS true --etcdCert <tls.crt path> --etcdKey <tls.key path> --rootCAPem <ca.crt path>
      For example:
      connect --etcd localhost:2379 --enableTLS true --etcdCert /root/cert/tls.crt --etcdKey
/root/cert/tls.key --rootCAPem /root/cert/ca.crt

What to do next

For information about using Birdwatcher, see Use Birdwatcher.