Using BMC Helix Monitor Agent to collect data

BMC Helix Monitor Agent is a light-weight containerized collector that is pre-configured and is ready to be deployed. It has the following advantages:

No Agent configurations are required after deployment.
Knowledge modules (KMs) are already deployed within the container.

BMC provides you the following options in BMC Helix Monitor Agent:

BMC Helix Monitor Agent-Containerized
Kubernetes multi-node deployment

The first option (BMC Helix Monitor Agent-Containerized) is to use BMC Helix Monitor Agent to monitor multiple environments by using the same Agent:

KM	Version
PATROL for Amazon Web Services	22.4.10
PATROL for Apache Tomcat and Generic Java Server	3.1.02
PATROL for Elasticsearch	1.0.12
PATROL for Kubernetes	22.4.02
PATROL for Linux	22.4.11
PATROL for Microsoft Azure	22.4.02
PATROL for MongoDB	1.1.31
PATROL for OpenShift	1.0.01
PATROL for OpenStack	1.1.02
PATROL for Oracle Enterprise Database	3.1.10
PATROL for PostgreSQL	1.1.10
PATROL for VMware vSphere	4.0.31
PATROL for Apache Kafka	23.2
PATROL for IBM MQ Series	23.2
PATROL Agent for BMC Helix Operations Management	23.3

The second option (Kubernetes multi-node deployment) focuses on monitoring Kubernetes clusters and is bundled with only PATROL for Kubernetes 22.4.02 and PATROL for Linux 22.4.01. When you deploy this option of BMC Helix Monitor Agent to a Kubernetes cluster, a BMC Helix Monitor Agent container is deployed on each node of the cluster. It facilitates metrics collection from each node and associated pods.

System requirements

Docker registry requirements

Direct access to BMC's Docker Trusted Repository (DTR) at https://containers.bmc.com is available. You can also use Local Harbor 2.1 or later synchronized with BMC's Docker Trusted Repository.

Best practice
BMC highly recommends that you install a local repository. A local repository provides the following benefits:

Improved performance
The container images are cached and accessed locally during deployments and upgrades.
Security
You can implement your own security scan of containers before deployment.
Access control
You can control access to the local repository by using authentication and authorization.
Air-gap support
You can replicate the local repository to support environments that do not have internet access.

For information about installing a local Harbor repository synchronized with the BMC DTR, see Setting-up-a-Harbor-repository.

Note: The local Harbor repository is recommended

BMC does not manage any repository other than Harbor and recommends that you use the local Harbor repository to pull the container image. However, if you are using any other repository, make sure that the repository is configured to connect to the BMC DTR to pull the container image.

Downloading the BMC Helix Monitor Agent chart and container images

To download the helm chart and token

Log in to EPD by using your Support user ID and password. You might also be prompted to complete the Export Compliance Form. If you are accessing this site for the first time, create a new EPD profile to specify the languages and platforms that you want to download. For assistance with EPD, see EPD site help.
Download the helm chart Helix-monitor-agent-23.2.00.00.tar to a temporary directory.
Download the container-token.bmc file containing the Docker token.

Download link for the installation file

Contains of the downloaded file

Container images

BMC containers images are distributed from https://containers.bmc.com. You can access the containers for the licensed products by using your registered support account and a new password. This password is saved in a file which is downloaded with this PDF file. The password is shared among all the containerized BMC software that you have access to.

Check your downloads directory for the container-token.bmc file that contains your generated password. For step-by-step instructions on how to use this password to obtain the BMC container images, see Setting-up-a-Harbor-repository.

To deploy BMC Helix Monitor Agent

Copy the downloaded file (Helix-monitor-agent-23.2.00.tar) to the controller or bastion machine from where the Kubernetes cluster is accessible. Extract the tar file.
Create Kubernetes image pull secret by using the following command:
kubectl create secret docker-registry <image pull secret name> --docker-server=containers.bmc.com --docker-username=<docker registry user name> --docker-password=<docker registry password> --docker-email=<docker registry email>
For local repository, ensure that you change the docker-server value in this command.
There are two (2) helm charts available in the downloaded file. Extract the required file from the downloaded files by running the following command: tar -zxf <filename>.
The default yaml file is helix-monitor-agent/values.yaml. You must replace all values starting and ending with __. Also, replace image pull secret name with the newly created secret name.

Blank values.yaml file

# Default values for helix-monitor-agent
# This is a YAML-formatted file.
# Declare variables to be passed into your templates.
registryhost: __DOCKER_REPOSITORY_HOSTNAME__
namespace: __NAMESPACE__
imagePullSecrets:
  name: bmc-epdhub
  enabled: true
image:
  repository: bmc/lp411
  pullPolicy: IfNotPresent
  tag: helix-monitor-agent-23.2.00-30
service:
  name: patrolagent
  ports:
    port: 3181
    name: pa-port
containers:
  secrets:
    apikey: __APIKEY__
    certificate: "__CERTIFICATE__"
  envMap:
    BHOM_TENANT_URL: __BHOM_TENANT_URL__
    PUBLISHOSTNAME: __HOSTNAME__
    TAGS: CNTR
    FORWARDPROXYSERVER: ""
    FORWARDPROXYUSER: ""
    FORWARDPROXYPASSWD: ""
  maxlogsize: 3Gi
  resources:
    limits:
      cpu: 500m
      memory: 4096Mi
    requests:
      cpu: 100m
      memory: 1024Mi

Open the values.yaml file in a text editor and edit the following details:

Yaml parameters

Configuration	Details
registryhost	The docker registry host containing the Helix Monitor Agent. The default value is containers.bmc.com.
namespace	Specify the namespace where you want to deploy the Helix Monitor Agent container.
imagePullSecrets	Secret to authenticate with a container registry to pull an image. For more information, see Pull an Image from a Private Registry.
name	The name of Secrets. Replace image pull secret name with the newly created secret name.
enabled	Set it true when you want to enable imagePullSecrets.
Image
repository	The location on the registry where the container image exists. Modify the parameter if you are using a local repository.
pullPolicy	Image pull policy for pod. Options available: Always IfNotPresent Never
tag (Optional)	Container image tag. Modify the parameter only if you have created custom tags on containers.
Service
name	The Kubernetes deployment name. This name must be unique in a namespace.
ports (Optional)	The port used by PATROL Agent.
API Key	In BMC Helix Operations Management, navigate to Administration > Repository. Click Copy API key and paste it in the values.yaml file. If you have configured a rotation interval for the API key in BMC Helix Portal, make sure that you use the latest API key each time the key rotates. For instructions about configuring a rotation interval, see Using API keys for external integrations.
BHOM tenant URL	Enter https:< BMC Helix Operations Management tenant URL>:443. For example, https:example-hostname.bmc.com:443 .
Certificate	Chrome browser Click the lock sign before the BMC Helix Operations Management URL. Click Connection is secure and then click Certificate is valid. Click the Certificate Path tab. Select the root certificate path (for example, DigiCert Global Root CA) and then click View Certifiate. Click the Details tab and then click Copy to File. On the Certificate Export Wizard, click Next. On the Export File Format page, select Base 64 encoded X.509 (.CER) and then click Next. In the File Name field, enter the file name to save the certificate and browse a folder to save the file. Open the file where you saved the certificate and copy the certificate. Do not copy the BEGIN CERTIFICATE and END CERTIFICATE lines. Back in the configuration file, paste the certifiate enclosed in single quotes (''). The following image shows the process to download and copy the certificate: Firefox browser Click the lock sign before the BMC Helix Operations Management URL. Click Connect secure and then click More information. Click View Certificate. Click the root certificate tab (for example, DigiCert Global Root CA). In the Miscellaneous section, click PEM (cert) and save the file. Open the downloaded file and copy the certificaate. Do not copy the BEGIN CERTIFICATE and END CERTIFICATE lines. Back in the configuration file, paste the certifiate enclosed in single quotes (''). The following image shows the process to download and copy the certificate:
Publishhostname	The hostname by which PATROL Agent is displayed in BMC Helix Operation Management. There should not be any other existing Agent with the same host name.
Tags (Optional)	Tags with which PATROL Agent identifies in the server.
maxlogsize (optional)	The maximum amount of ephemeral storage container consumes on kubernetes for the logs folder.
Resources *(Optional)*
Limits (CPU, memory)	The upper limit of CPU and memory resources allotted for the container. For more information, see Resource Management.
Requests (CPU, memory)	The minimum CPU and memory resources allotted for the container. For more information, see Resource Management.
Forward Proxy configuration	If you have configured forward proxy server, enter the username, password, and the forward proxy URL.
Multi-node specific Kubernetes variable
enableNodeDeployment	Set the variable to true.
Tags	Tags with which PATROL Agent identifies in the server. ( Use tag name in agent selection criteria while creating monitor policy)

Sample values.yaml file

# Default values for helix-monitor-agent
# This is a YAML-formatted file.
# Declare variables to be passed into your templates.

registryhost: test-harboreg.bmc.com

namespace: patrolagent
imagePullSecrets:
name: bmc-epdhub
enabled: true

image:
  repository: bmc/lp411
  pullPolicy: IfNotPresent
  tag: helix-monitor-agent-23.2.00-30

service:
  name: patrolagent
  ports:
    port: 3181
    name: pa-port

containers:
  secrets:
    apikey: 1a11aa1a-1aa1-111a-1111-11a11a11111a
    certificate: "MIIDrzCCApegAwIBAgIQCDvgVpBCRrGhdWrJWZHHSjANBgkqhkiG9w0BAQUFADBh
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
d3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBD
QTAeFw0wNjExMTAwMDAwMDBaFw0zMTExMTAwMDAwMDBaMGExCzAJBgNVBAYTAlVT
MRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5j
b20xIDAeBgNVBAMTF0RpZ2lDZXJ0IEdsb2JhbCBSb290IENBMIIBIjANBgkqhkiG
9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4jvhEXLeqKTTo1eqUKKPC3eQyaKl7hLOllsB
CSDMAZOnTjC3U/dDxGkAV53ijSLdhwZAAIEJzs4bg7/fzTtxRuLWZscFs3YnFo97
nh6Vfe63SKMI2tavegw5BmV/Sl0fvBf4q77uKNd0f3p4mVmFaG5cIzJLv07A6Fpt
43C/dxC//AH2hdmoRBBYMql1GNXRor5H4idq9Joz+EkIYIvUX7Q6hL+hqkpMfT7P
T19sdl6gSzeRntwi5m3OFBqOasv+zbMUZBfHWymeMr/y7vrTC0LUq7dBMtoM1O/4
gdW7jVg/tRvoSSiicNoxBN33shbyTApOB6jtSj1etX+jkMOvJwIDAQABo2MwYTAO
BgNVHQ8BAf8EBAMCAYYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUA95QNVbR
TLtm8KPiGxvDl7I90VUwHwYDVR0jBBgwFoAUA95QNVbRTLtm8KPiGxvDl7I90VUw
DQYJKoZIhvcNAQEFBQADggEBAMucN6pIExIK+t1EnE9SsPTfrgT1eXkIoyQY/Esr
hMAtudXH/vTBH1jLuG2cenTnmCmrEbXjcKChzUyImZOMkXDiqw8cvpOp/2PV5Adg
06O/nVsJ8dWO41P0jmP6P6fbtGbfYmbW0W5BjfIttep3Sp+dWOIrWcBAI+0tKIJF
PnlUkiaY4IBIqDfv8NZ5YBberOgOzW6sRBc4L0na4UU+Krk2U886UAb3LujEV0ls
YSEY1QSteDwsOoBrp+uvFRTp2InBuThs4pFsiv9kuXclVzDAGySj4dzp30d8tbQk
CAUw7C29C79Fv1C5qfPrmAESrciIxpg0X40KPMbp1ZWVbd4="
  envMap:
    BHOM_TENANT_URL: https:testhost.bmc.com:443
    PUBLISHOSTNAME: oraclemonitor.bmc.com
    TAGS: CNTR
    FORWARDPROXYSERVER: ""
    FORWARDPROXYUSER: ""
    FORWARDPROXYPASSWD: ""
  maxlogsize: 3Gi
  resources:
    limits:
      cpu: 500m
      memory: 4096Mi
    requests:
      cpu: 100m
      memory: 1024Mi

Run the following command:
helm3 install -f <override values yaml file path> <helm deplyoment name> <container file name>
For example, helm3 install -f helix-monitor-agent/values.yaml k8s-agent helix-monitor-agent-23.2.00.tgz

Sample deployment output

NAME: abs-agent
LAST DEPLOYED: Fri Jun 24 06:34:36 2022
NAMESPACE: patroldev
STATUS: deployed
REVISION: 1
TEST SUITE: None

To verify the deployment

Run the following command to check the helm chart deployment status:
helm3 list
In BMC Helix Operations Management, navigate to Configuration > Agents.
Search for BMC Helix Monitor Agent by entering its name in the search box.
For a BMC Helix Monitor Agent, the version ends with letter c.

To uninstall BMC Helix Monitor Agent

Run the following command:
helm3 uninstall <deployment name>

To verify the uninstallation, run the following command:
helm3 list

FAQs

What PATROL Agent features are not available in the containerized version?

Port 3181 is not exposed outside the container. Therefore, no PatrolCli or console connection is possible from the host computer or within the container.
You cannot change or re-configure the default account for the BMC Helix Monitor Agent.
KM push is not supported.
You cannot modify the container contents after deployment.
You cannot restart the Agent.

How to collect Agent debug logs?

To enable the BMC Helix Monitor Agent debug logs, go to Configuration > Agents and use the Query PATROL Agent option from the actions menu for the Agent.

If the Agent is not connected to BMC Helix Operations Management, start a new Agent process with debug flags in the container on a different port.

Copy the debug log files from the container manually.

How to collect KM debug logs?

Enable the KM debug logs option in the KM configuration.

To copy the debug log files from the container manually:

Use the following command to get pod’s name:
kubectl get po | grep <service name defined in values.yml>
Use the following command to copy the file from pod:
kubectl cp <namespace>/<podname>:<LogFilePath> <localFolderPath>

Can I push additional KMs to BMC Helix Monitor Agent?

No.

Can I upgrade KMs on BMC Helix Monitor Agent?

You cannot upgrade KMs by deploying a package. To upgrade a KM, upgrade BMC Helix Monitor Agent.

How can I upgrade BMC Helix Monitor Agent?

Download the helm chart from the BMC EPD website and run the following command:

helm3 upgrade -f <override values yaml file path> <helm deplyoment name> <container file name>

What Java location shall I use in the Java Home or Java Path fields while configuring the KMs?

In a container, Java is installed at /opt/java. Set JAVA_HOME as /opt/java.

How to check PATROL Agent error logs from controller?

Run the following commands:

To search the pod, run kubectl get po
Then run, kubectl logs <POD name>