KloudMate Agent for OpenTelemetry Auto Instrumentation

Simplifying OpenTelemetry adoption through automated deployment and remote configuration

• Documentation

Key Problems Solved

• Complex Configuration: Eliminates the steep learning curve of OpenTelemetry Collector configuration
• Manual Installation: Provides automated installation scripts for multiple environments
• Configuration Management: Enables remote configuration through a web interface without SSH access

Features

• 🚀 Automated Installation: One-command deployment across Linux, Docker, and Kubernetes
• 🌐 Remote Configuration: Configure agents through a web interface without your target machine access
• 📊 Lifecycle Management: Comprehensive management of OpenTelemetry Collector
• 🔍 Synthetic Monitoring: Built-in health checks and monitoring capabilities
• 🎯 Multi-Platform Support: Native support for various deployment environments
• 📈 Real-time Dashboards: Unique agent identification for centralized monitoring

Supported OpenTelemetry Components

The KloudMate Agent includes a set of OpenTelemetry Collector components including receivers, processors, exporters, and extensions. For a complete list of all supported components with description and documentation links, see the Supported Components Documentation.

Installation

Choose your environment and run the appropriate installation command:

Docker Installation

Docker agent is containerized version of the Agent that collect host level metrics (via hostmetricreceiver) and logs (via the volume mounts) User can install the agent by running below script

KM_API_KEY="<YOUR_API_KEY>" KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318" bash -c "$(curl -L https://cdn.kloudmate.com/scripts/install_docker.sh)"

Linux Installation

Similar to native OTel agent, agent supports both debian and Red Hat based systems. User can install the agent via this automated bash script

KM_API_KEY="<YOUR_API_KEY>" KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318" bash -c "$(curl -L https://cdn.kloudmate.com/scripts/install_linux.sh)"

Bash script should have various configurable arguments to configure the agent apart from API_KEY which is required for authentication at exporter. Each of the script should have corresponding uninstall command to remove the agent from the system.

Kubernetes Installation

• The agent will run as DaemonSet as well as a Deployment in the cluster and add necessary components to monitor the nodes and pods.
• you must install kloudmate-crd before running helm install command:

 kubectl apply -f https://raw.githubusercontent.com/kloudmate/km-agent/refs/heads/develop/deployment/helm/km-kube-agent/crds/crd-otel-instrumentation.yaml

You can then install the agent using below Helm commands

helm repo add kloudmate https://kloudmate.github.io/km-agent
helm repo update
helm install kloudmate-release kloudmate/km-kube-agent --namespace km-agent --create-namespace \
--set API_KEY="<YOUR_API_KEY>" \n --set COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318" \
--set clusterName="<YOUR_CLUSTER_NAME>" \
--set "monitoredNamespaces={MONITORED_NS}" \
--set featuresEnabled.apm=true \
--set featuresEnabled.logs=true

⚠️NOTE:

• For the monitoredNamespaces flag the namespaces should be passed as comma-separated values. For example - --set "monitoredNamespaces={bookinfo,mongodb,cassandra}" where bookinfo,mongodb and cassandra are the targetted namespaces that you want to monitor.

🚨 Note: For private GKE clusters, you will need to either add a firewall rule that allows master nodes access to port 9443/tcp on worker nodes, or change the existing rule that allows access to port 80/tcp, 443/tcp and 10254/tcp to also allow access to port 9443/tcp. More information can be found in the Official GCP Documentation. See the GKE documentation on adding rules and the Kubernetes issue for more detail.

Note: To enable APM (Application Performance Monitoring) and logs collection, set the featuresEnabled.apm and featuresEnabled.logs flags to true. By default, metrics and traces are enabled. You can customize these settings based on your monitoring requirements:

• featuresEnabled.apm=true - Enables application performance monitoring
• featuresEnabled.logs=true - Enables log collection
• featuresEnabled.metrics=true - Enables metrics collection (enabled by default)
• featuresEnabled.traces=true - Enables trace collection (enabled by default)

⚠️ Configuration Management: Manually updating the ConfigMaps for the DaemonSet or Deployment agents is not recommended, as these configurations may be overwritten by updates sent from KloudMate APIs. The recommended approach is to use the KloudMate Agent Config Editor - a web-based YAML editor that ensures your configurations are properly synchronized and persisted across your infrastructure.

Installing the Agent on Nodes with Taints

If your Kubernetes cluster uses taints on nodes, the agent daemonset pods must have corresponding tolerations to be scheduled successfully. By default, the agent does not apply any tolerations. You can configure tolerations during installation using Helm parameters. The helm installation command in this case will look like this -

helm install kloudmate-release kloudmate/km-kube-agent --namespace km-agent --create-namespace \
--set API_KEY="<YOUR_API_KEY>" --set COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318" \
--set clusterName="<YOUR_CLUSTER_NAME>" \
--set "monitoredNamespaces={MONITORED_NS}" \
--set tolerations[0].key="env" --set tolerations[0].operator="Equal" --set tolerations[0].value="uat" --set tolerations[0].effect="NoSchedule" \
--set tolerations[1].key="env" --set tolerations[1].operator="Equal" --set tolerations[1].value="sb-uat-node" --set tolerations[1].effect="NoSchedule" \

In the above example, two tolerations are provided to match the taints configured on the cluster’s nodes. This ensures the agent daemonset pods can be scheduled across all desired nodes.

Notes

• You can define as many tolerations as needed by incrementing the index (tolerations[0], tolerations[1], etc.).
• The values of key, operator, value, and effect should match the taints applied to your nodes.
• If your cluster has no taints, you can skip these parameters. By default, the agent daemonset pods will be automatically scheduled on untainted nodes.

Windows Installation

Download and run the Windows (.exe) installer from our releases page.

Supported Environments

Current Support

• ✅ Linux (Debian/Ubuntu, RHEL/CentOS)
• ✅ Docker (Host metrics and log collection)
• ✅ Kubernetes (via DaemonSet & Deployment)
• ✅ Windows (Windows Server 2016+)

Architecture

Agent is installed as service on the host system/docker container/demonset on a k8s. It is done during installation process. The agent is responsible for managing the lifecycle of the Collector. The Agent is not an implementation of Collector, instead, it runs and manages lifecycle of existig OTel Collector.

It is also primarily responsible for watching remote configuration (via REST endpoint) and pass on the configuration to Collector when changes has been detected. It has other functionalities such as synthetic monitoring that can be used to monitor the agent's status, various logs for monitoring purpose etc.

Each agent is uniquely identifyable so it can be used to build dashboard for the user to monitor the agents and configure them using a web interface.

Kubernetes Agent Architecture

The Kubernetes agent runs as a Deployment & DaemonSet and includes:

• Node Monitoring: CPU, memory, disk, and network metrics
• Pod Monitoring: Container-level metrics and logs
• Cluster Events: Kubernetes events and resource monitoring
• Service Discovery: Automatic service endpoint detection

In future releases the agent can be installed in any of the following environments as well:

• Mac
• ECS
• Azure k8s

Latest Enhancement to Your KloudMate Suite

Introducing KloudMate Templates - Curated Templates for Every Use Case

Click here or the above image to see available templates

Contributing

We welcome contributions that improve the quality, usability, and functionality of KM-Agent. Please read our contribution guidelines before getting started.

How to Contribute

1. Fork the Repository

   git fork https://github.com/kloudmate/km-agent.git

2. Create a Feature Branch

   git checkout -b feature/amazing-feature

3. Make Your Changes

   • Follow our coding standards
   • Add tests for new functionality
   • Update documentation as needed

4. Submit a Pull Request

   • Provide a clear description of your changes
   • Include any relevant issue numbers
   • Ensure all tests pass

Reporting Issues

Before creating an issue, please:

• Check existing issues
• Use our issue templates
• Provide detailed reproduction steps
• Include environment information

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Community and Support

Getting Help

• 📧 Email: support@kloudmate.com
• 🐛 Issues - Bug reports and feature requests
• 💻 Documentation

Community Resources

• 🌟 Dashboard Templates
• 📝 Blog Posts
• 📱 Slack Community

License

This project is licensed under the Apache License 2.0. See the LICENSE file for full details.

Acknowledgments

• OpenTelemetry Community - For the foundational observability framework

---

Made with 🧡 by the KloudMate Team

Website • Documentation • Community • Support