Environment Variables

The KloudMate Agent is configured primarily through environment variables prefixed with KM_. This reference documents all available variables organized by category.

Core Configuration

Authentication & Connectivity

KM_API_KEY

string

required

Required. API key for authenticating with the KloudMate platform.Obtain your API key from the KloudMate Settings page.

export KM_API_KEY="km_1234567890abcdefghijklmnopqrstuv"

Used in:

Authentication header for telemetry export
Configuration update requests
Agent registration

Source reference: /home/daytona/workspace/source/cmd/kmagent/main.go:199-203

KM_COLLECTOR_ENDPOINT

string

default:"https://otel.kloudmate.com:4318"

OTLP/HTTP endpoint where the agent sends telemetry data.

export KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318"

Format: Must be a valid HTTPS URL with portRegional endpoints:

US: https://otel.kloudmate.com:4318
EU: https://otel.eu.kloudmate.com:4318
Custom: Your self-hosted endpoint

Source reference: /home/daytona/workspace/source/cmd/kmagent/main.go:191-197

Configuration Files

KM_AGENT_CONFIG

string

default:"auto"

Path to the agent configuration file (YAML format).

export KM_AGENT_CONFIG="/path/to/agent-config.yaml"

Default paths:

Linux: /etc/kmagent/config.yaml
macOS: /Library/Application Support/kmagent/config.yaml
Windows: %ProgramFiles%\kmagent\config.yaml
Docker: /etc/kmagent/config.yaml

Source reference: /home/daytona/workspace/source/cmd/kmagent/main.go:180-184

KM_COLLECTOR_CONFIG

string

default:"auto"

Path to the OpenTelemetry Collector configuration file (YAML format).

export KM_COLLECTOR_CONFIG="/etc/kmagent/otel-config.yaml"

This configuration defines the collector’s receivers, processors, and exporters.Source reference: /home/daytona/workspace/source/cmd/kmagent/main.go:186-190

Remote Configuration

KM_CONFIG_CHECK_INTERVAL

integer

default:"60"

Interval in seconds between configuration update checks.

export KM_CONFIG_CHECK_INTERVAL=60

Valid values:

0: Disable remote configuration updates
10-300: Recommended range (seconds)
> 300: Use for reduced API calls

Source reference: /home/daytona/workspace/source/cmd/kmagent/main.go:204-210

KM_UPDATE_ENDPOINT

string

default:"auto-derived"

API endpoint for fetching configuration updates.

export KM_UPDATE_ENDPOINT="https://api.kloudmate.com/agents/config-check"

If not set, automatically derived from KM_COLLECTOR_ENDPOINT:

Collector: https://otel.kloudmate.com:4318
Update: https://api.kloudmate.com/agents/config-check

Source reference: /home/daytona/workspace/source/cmd/kmagent/main.go:211-217

Deployment Mode

KM_DOCKER_MODE

boolean

default:"false"

Enable Docker-specific configuration and receivers.

export KM_DOCKER_MODE=true

When enabled:

Uses /home/daytona/workspace/source/configs/docker-col-config.yaml
Enables docker_stats receiver
Mounts /var/run/docker.sock
Collects container logs from /var/lib/docker/containers

Source reference: /home/daytona/workspace/source/cmd/kmagent/main.go:218-223

KM_DOCKER_ENDPOINT

string

default:"unix:///var/run/docker.sock"

Docker daemon socket endpoint.

export KM_DOCKER_ENDPOINT="unix:///var/run/docker.sock"

Source reference: /home/daytona/workspace/source/cmd/kmagent/main.go:224-229

Kubernetes Configuration

Cluster Identification

KM_CLUSTER_NAME

string

required

Required for Kubernetes. Name of the Kubernetes cluster.

export KM_CLUSTER_NAME="production-cluster"

Applied as k8s.cluster.name attribute to all telemetry data.Source reference: /home/daytona/workspace/source/configs/daemonset-col-config.yaml:13,22,52,76,84,162,170

KM_NODE_NAME

string

required

Required for DaemonSet. Name of the Kubernetes node where the agent is running.Typically set automatically via the Downward API:

env:
- name: KM_NODE_NAME
  valueFrom:
    fieldRef:
      fieldPath: spec.nodeName

Used for:

Filtering metrics to specific node
Node-level resource attribution
Kubelet stats collection

Source reference: /home/daytona/workspace/source/configs/daemonset-col-config.yaml:84,167,175,514

KM_NODE_HOST_IP

string

Host IP address of the Kubernetes node.

env:
- name: KM_NODE_HOST_IP
  valueFrom:
    fieldRef:
      fieldPath: status.hostIP

Feature Toggles

KM_LOGS_ENABLED

boolean

default:"false"

Enable log collection from Kubernetes pods.

export KM_LOGS_ENABLED=true

When enabled:

filelog/containers receiver activated
Collects logs from /var/log/pods/*/*/*.log
Parses JSON and plaintext logs
Extracts trace context

Source reference: /home/daytona/workspace/source/internal/updater/k8s_updater.go:88-95

KM_APM_ENABLED

boolean

default:"false"

Enable automatic application instrumentation for distributed tracing.

export KM_APM_ENABLED=true

Supported languages:

Java
Node.js
Python
.NET

Source reference: /home/daytona/workspace/source/internal/updater/k8s_updater.go:98-105

KM_K8S_MONITORED_NAMESPACES

string

default:"all"

Comma-separated list of Kubernetes namespaces to monitor.

# Monitor specific namespaces
export KM_K8S_MONITORED_NAMESPACES="production,staging,default"

# Monitor all namespaces (default)
export KM_K8S_MONITORED_NAMESPACES=""

Source reference: /home/daytona/workspace/source/internal/updater/k8s_updater.go:79

Operator Configuration

KM_NAMESPACE

string

default:"km-agent"

Namespace where the KloudMate agent is deployed.

export KM_NAMESPACE="km-agent"

Source reference: /home/daytona/workspace/source/internal/instrumentation/autoinstrument.go:13

KM_CRD_NAME

string

default:"km-agent-instrumentation-crd"

Name of the Instrumentation CustomResourceDefinition.

export KM_CRD_NAME="km-agent-instrumentation-crd"

Source reference: /home/daytona/workspace/source/internal/instrumentation/autoinstrument.go:17

KM_DAEMONSET_NAME

string

default:"km-agent"

Name of the agent DaemonSet.

export KM_DAEMONSET_NAME="km-agent"

KM_DEPLOYMENT_NAME

string

default:"km-agent-cluster"

Name of the agent Deployment.

export KM_DEPLOYMENT_NAME="km-agent-cluster"

RPC Configuration

KM_CFG_UPDATER_RPC_ADDR

string

default:"5501"

Port for the configuration updater RPC server.

export KM_CFG_UPDATER_RPC_ADDR=5501

Used for communication between the config updater and agent pods in Kubernetes.Source reference: /home/daytona/workspace/source/rpc/server.go:24

Log Filtering

KM_XLOG_PATHS

array

default:"[]"

Additional log paths to exclude from collection.

export KM_XLOG_PATHS="/var/log/sensitive/*,/var/log/archive/*"

In Helm values:

KM_XLOG_PATHS:
  - /var/log/sensitive/*
  - /var/log/archive/*

Source reference: /home/daytona/workspace/source/configs/daemonset-col-config.yaml:252

FILELOG_PATHS

string

Additional file log paths to include (Docker mode).

export FILELOG_PATHS="/app/logs/*.log,/custom/logs/**/*.log"

Source reference: /home/daytona/workspace/source/configs/docker-col-config.yaml:7

Logging & Debugging

KM_LOG_LEVEL

string

default:"info"

Agent log level.

export KM_LOG_LEVEL=debug

Valid values:

trace: Most verbose, includes all debug messages
debug: Detailed debugging information
info: General informational messages (default)
warn: Warning messages only
error: Error messages only
fatal: Fatal errors only

Implementation:

func ParseLogLevel() zapcore.Level {
    switch strings.ToLower(os.Getenv("KM_LOG_LEVEL")) {
    case "trace", "debug":
        return zapcore.DebugLevel
    case "info":
        return zapcore.InfoLevel
    case "warn", "warning":
        return zapcore.WarnLevel
    case "error":
        return zapcore.ErrorLevel
    case "fatal":
        return zapcore.FatalLevel
    default:
        return zapcore.InfoLevel
    }
}

Source reference: /home/daytona/workspace/source/internal/logger/level.go:10-14

KM_AGENT_VERSION

string

default:"auto"

Agent version identifier. Automatically set by the agent at startup.

os.Setenv("KM_AGENT_VERSION", r.Version)

Used for:

Version reporting to platform
Update compatibility checks
Troubleshooting and support

Source reference: /home/daytona/workspace/source/internal/k8sagent/agent.go:172

Environment Variable Expansion

All OpenTelemetry Collector configuration files support environment variable expansion using the ${env:VAR_NAME} syntax:

exporters:
  otlphttp:
    endpoint: ${env:KM_COLLECTOR_ENDPOINT}
    headers:
      Authorization: ${env:KM_API_KEY}

Configuration Examples

Host Deployment (Linux)

#!/bin/bash
# /etc/kmagent/env.sh

export KM_API_KEY="km_your_api_key_here"
export KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318"
export KM_CONFIG_CHECK_INTERVAL=60
export KM_LOG_LEVEL=info

# Start the agent
source /etc/kmagent/env.sh
sudo systemctl start kmagent

Docker Deployment

docker run -d \
  --name kmagent \
  --restart unless-stopped \
  -e KM_API_KEY="km_your_api_key_here" \
  -e KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318" \
  -e KM_DOCKER_MODE=true \
  -e KM_CONFIG_CHECK_INTERVAL=60 \
  -e KM_LOG_LEVEL=info \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /var/log:/var/log:ro \
  -v /:/hostfs:ro \
  ghcr.io/kloudmate/km-agent:latest

Kubernetes Deployment

apiVersion: v1
kind: Secret
metadata:
  name: km-agent-secret
  namespace: km-agent
type: Opaque
stringData:
  api-key: "km_your_api_key_here"
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: km-agent
  namespace: km-agent
spec:
  template:
    spec:
      containers:
      - name: agent
        image: ghcr.io/kloudmate/km-kube-agent:latest
        env:
        - name: KM_API_KEY
          valueFrom:
            secretKeyRef:
              name: km-agent-secret
              key: api-key
        - name: KM_COLLECTOR_ENDPOINT
          value: "https://otel.kloudmate.com:4318"
        - name: KM_CONFIG_CHECK_INTERVAL
          value: "30"
        - name: KM_CLUSTER_NAME
          value: "production-cluster"
        - name: KM_NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName
        - name: KM_NODE_HOST_IP
          valueFrom:
            fieldRef:
              fieldPath: status.hostIP
        - name: KM_LOGS_ENABLED
          value: "true"
        - name: KM_APM_ENABLED
          value: "false"

Validation

The agent validates required environment variables on startup:

if cfg.APIKey == "" {
    return fmt.Errorf("KM_API_KEY is required")
}

if cfg.CollectorEndpoint == "" {
    return fmt.Errorf("KM_COLLECTOR_ENDPOINT is required")
}

Source reference: /home/daytona/workspace/source/internal/k8sagent/agent.go:146-149

Troubleshooting

Missing Required Variables

FATAL failed to load configuration: KM_API_KEY is required

Solution: Set the required environment variable before starting the agent.

export KM_API_KEY="your-api-key"
export KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318"
kmagent start

Invalid Endpoint Format

ERROR failed to create exporter: invalid endpoint format

Solution: Ensure the endpoint is a valid HTTPS URL with port.

# Correct
export KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318"

# Incorrect
export KM_COLLECTOR_ENDPOINT="otel.kloudmate.com"  # Missing https:// and port

Environment Variable Not Expanded

ERROR failed to load config: cannot resolve ${env:KM_API_KEY}

Solution: Verify the environment variable is set in the correct scope.

# Check if variable is set
echo $KM_API_KEY

# For systemd services
sudo systemctl edit kmagent
# Add:
[Service]
Environment="KM_API_KEY=your-key"

Next Steps

Configuration Overview

Learn about the configuration architecture

Remote Configuration

Dynamic configuration updates

OpenTelemetry Components

Configure receivers, processors, and exporters

Installation

Install the agent on your platform

Getting Started

Installation

Configuration

Features

Architecture

Operations

Core Configuration

Authentication & Connectivity

Configuration Files

Remote Configuration

Deployment Mode

Kubernetes Configuration

Cluster Identification

Feature Toggles

Operator Configuration

RPC Configuration

Log Filtering

Logging & Debugging

Environment Variable Expansion

Configuration Examples

Host Deployment (Linux)

Docker Deployment

Kubernetes Deployment

Validation

Troubleshooting

Next Steps

Configuration Overview

Remote Configuration

OpenTelemetry Components

Installation

Build docs developers (and LLMs) love

Getting Started

Installation

Configuration

Features

Architecture

Operations

​Core Configuration

​Authentication & Connectivity

​Configuration Files

​Remote Configuration

​Deployment Mode

​Kubernetes Configuration

​Cluster Identification

​Feature Toggles

​Operator Configuration

​RPC Configuration

​Log Filtering

​Logging & Debugging

​Environment Variable Expansion

​Configuration Examples

​Host Deployment (Linux)

​Docker Deployment

​Kubernetes Deployment

​Validation

​Troubleshooting

​Next Steps

Configuration Overview

Remote Configuration

OpenTelemetry Components

Installation

Build docs developers (and LLMs) love

Core Configuration

Authentication & Connectivity

Configuration Files

Remote Configuration

Deployment Mode

Kubernetes Configuration

Cluster Identification

Feature Toggles

Operator Configuration

RPC Configuration

Log Filtering

Logging & Debugging

Environment Variable Expansion

Configuration Examples

Host Deployment (Linux)

Docker Deployment

Kubernetes Deployment

Validation

Troubleshooting

Next Steps