JustAnalytics/Documentation

Host Monitoring Agent

Install the JustAnalytics agent to collect host-level CPU, memory, disk, and network metrics.

Overview#

The @justanalyticsapp/agent is a lightweight daemon that runs on your servers and reports host-level infrastructure metrics to JustAnalytics. It collects CPU, memory, disk, and network metrics at configurable intervals, and can auto-detect Docker containers and Kubernetes pods.

Installation#

npm (Global Install)#

npm install -g @justanalyticsapp/agent

# Start the agent
justanalytics-agent start \
  --api-key ja_sk_... \
  --site-id your-site-id \
  --url https://youranalytics.com

Docker#

docker run -d \
  --name ja-agent \
  --restart unless-stopped \
  --pid host \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e JA_API_KEY=ja_sk_... \
  -e JA_SITE_ID=your-site-id \
  -e JA_URL=https://youranalytics.com \
  justanalyticsapp/agent:latest

The Docker image mounts /proc and /sys as read-only for host metric collection and optionally mounts the Docker socket for container monitoring.

systemd Service#

For Linux servers, install as a systemd service:

# Install the agent
npm install -g @justanalyticsapp/agent

# Install systemd unit
justanalytics-agent install-service \
  --api-key ja_sk_... \
  --site-id your-site-id \
  --url https://youranalytics.com

# The service starts automatically and survives reboots
systemctl status justanalytics-agent

Configuration#

Environment Variables#

| Variable | Description | Default | |----------|-------------|---------| | JA_API_KEY | API key for authentication | Required | | JA_SITE_ID | Site ID to report metrics to | Required | | JA_URL | JustAnalytics instance URL | Required | | JA_HOSTNAME | Override reported hostname | System hostname | | JA_INTERVAL | Metric collection interval (seconds) | 15 | | JA_TAGS | Comma-separated key=value tags | None | | JA_DOCKER | Enable Docker monitoring | true (auto-detect) | | JA_KUBERNETES | Enable Kubernetes monitoring | false |

Configuration File#

Alternatively, use a YAML configuration file:

# /etc/justanalytics/agent.yaml
api_key: ja_sk_...
site_id: your-site-id
url: https://youranalytics.com

hostname: web-server-01
interval: 15
tags:
  environment: production
  region: us-east-1
  role: web

docker:
  enabled: true
  socket: /var/run/docker.sock
  exclude_containers:
    - ja-agent  # exclude the agent itself

kubernetes:
  enabled: false
  namespace: default

Start with a config file:

justanalytics-agent start --config /etc/justanalytics/agent.yaml

Metrics Collected#

CPU Metrics#

| Metric | Description | Unit | |--------|-------------|------| | host.cpu.usage | Overall CPU utilization | Percentage (0-100) | | host.cpu.user | Time spent in user space | Percentage | | host.cpu.system | Time spent in kernel space | Percentage | | host.cpu.iowait | Time waiting on I/O | Percentage | | host.cpu.steal | Time stolen by hypervisor (VMs) | Percentage | | host.cpu.core.usage | Per-core CPU utilization | Percentage per core |

CPU metrics are collected per-core and aggregated. The per-core breakdown is available in the Infrastructure dashboard by expanding the CPU chart.

Memory Metrics#

| Metric | Description | Unit | |--------|-------------|------| | host.memory.total | Total physical memory | Bytes | | host.memory.used | Used memory | Bytes | | host.memory.available | Available memory (including buffers/cache) | Bytes | | host.memory.usage | Memory utilization | Percentage | | host.memory.swap.total | Total swap space | Bytes | | host.memory.swap.used | Used swap space | Bytes |

Disk Metrics#

| Metric | Description | Unit | |--------|-------------|------| | host.disk.total | Total disk space | Bytes | | host.disk.used | Used disk space | Bytes | | host.disk.usage | Disk utilization | Percentage | | host.disk.read.bytes | Bytes read per second | Bytes/s | | host.disk.write.bytes | Bytes written per second | Bytes/s | | host.disk.read.ops | Read operations per second | ops/s | | host.disk.write.ops | Write operations per second | ops/s |

Disk metrics are collected per mount point. The agent automatically discovers all mounted filesystems and excludes virtual/system mounts.

Network Metrics#

| Metric | Description | Unit | |--------|-------------|------| | host.network.rx.bytes | Bytes received per second | Bytes/s | | host.network.tx.bytes | Bytes transmitted per second | Bytes/s | | host.network.rx.packets | Packets received per second | packets/s | | host.network.tx.packets | Packets transmitted per second | packets/s | | host.network.rx.errors | Receive errors per second | errors/s | | host.network.tx.errors | Transmit errors per second | errors/s | | host.network.connections | Active TCP connections | Count |

Network metrics are collected per interface and aggregated. Loopback interfaces are excluded by default.

System Metrics#

| Metric | Description | Unit | |--------|-------------|------| | host.load.1 | 1-minute load average | Load | | host.load.5 | 5-minute load average | Load | | host.load.15 | 15-minute load average | Load | | host.uptime | System uptime | Seconds | | host.processes.total | Total processes | Count | | host.processes.running | Running processes | Count |

Docker Container Monitoring#

When Docker is detected (or enabled), the agent automatically monitors all running containers.

See Container Monitoring for full details on Docker and Kubernetes monitoring.

Quick Setup#

The agent auto-detects Docker when the socket is accessible:

# Docker auto-detected when /var/run/docker.sock exists
justanalytics-agent start --api-key ja_sk_... --site-id your-site-id --url https://youranalytics.com

# Or explicitly enable/disable
justanalytics-agent start --docker=true --api-key ja_sk_...

Kubernetes Monitoring#

For Kubernetes deployments, run the agent as a DaemonSet:

# kubernetes/daemonset.yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: justanalytics-agent
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: justanalytics-agent
  template:
    metadata:
      labels:
        app: justanalytics-agent
    spec:
      hostPID: true
      containers:
        - name: agent
          image: justanalyticsapp/agent:latest
          env:
            - name: JA_API_KEY
              valueFrom:
                secretKeyRef:
                  name: justanalytics
                  key: api-key
            - name: JA_SITE_ID
              value: "your-site-id"
            - name: JA_URL
              value: "https://youranalytics.com"
            - name: JA_KUBERNETES
              value: "true"
            - name: JA_HOSTNAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
          volumeMounts:
            - name: proc
              mountPath: /host/proc
              readOnly: true
            - name: sys
              mountPath: /host/sys
              readOnly: true
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 200m
              memory: 128Mi
      volumes:
        - name: proc
          hostPath:
            path: /proc
        - name: sys
          hostPath:
            path: /sys

Apply with:

kubectl apply -f kubernetes/daemonset.yaml

Troubleshooting#

Agent won't start#

# Check agent status
justanalytics-agent status

# Run in verbose mode
justanalytics-agent start --debug

# Common issues:
# - Invalid API key: verify the key hasn't been revoked
# - Network error: verify the JA_URL is reachable from the host
# - Permission denied: /proc or /sys access requires root or appropriate capabilities

No metrics appearing in dashboard#

  1. Verify the agent is running: justanalytics-agent status
  2. Check agent logs: journalctl -u justanalytics-agent -f (systemd) or docker logs ja-agent (Docker)
  3. Verify API key is valid and not revoked
  4. Verify Site ID matches an existing site
  5. Check network connectivity: curl -v https://youranalytics.com/api/ingest/metrics

High resource usage#

The agent is designed to use minimal resources (~50MB RAM, under 1% CPU). If you see higher usage:

  • Increase the collection interval: JA_INTERVAL=30 (30 seconds instead of 15)
  • Exclude containers you don't need to monitor in the config file
  • Reduce the number of disk mount points being monitored

Docker socket permission denied#

# Add the agent user to the docker group
usermod -aG docker justanalytics-agent

# Or run the Docker container with the docker group GID
docker run -d \
  --group-add $(getent group docker | cut -d: -f3) \
  ...

Firewall/Proxy Configuration#

The agent sends metrics via HTTPS POST to /api/ingest/metrics. Ensure outbound HTTPS (port 443) is allowed to your JustAnalytics instance URL. For proxied environments:

JA_PROXY=http://proxy.internal:8080 justanalytics-agent start ...