JustAnalytics/Documentation

Container Monitoring

Monitor Docker containers and Kubernetes pods with resource usage, limits, and health status.

Overview#

JustAnalytics monitors your containerized workloads automatically. The host agent collects per-container metrics via the Docker socket and per-pod metrics via the Kubernetes API, giving you full visibility into resource consumption, restarts, and health.

Docker Monitoring#

Prerequisites#

The JustAnalytics agent needs read access to the Docker socket (/var/run/docker.sock). This is handled automatically when you run the agent as a Docker container with the socket mounted.

Docker Setup#

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

If running the agent via npm (not Docker), ensure the agent process has permission to read the Docker socket:

# Grant access to docker socket
sudo usermod -aG docker $USER

Container Metrics#

The agent collects the following metrics for each running container:

| Metric | Description | Unit | |--------|-------------|------| | container.cpu.usage | CPU utilization | Percentage | | container.cpu.throttled | Time spent throttled | Nanoseconds | | container.memory.usage | Current memory usage | Bytes | | container.memory.limit | Memory limit (if set) | Bytes | | container.memory.usage_percent | Usage as percentage of limit | Percentage | | container.network.rx.bytes | Network bytes received | Bytes/s | | container.network.tx.bytes | Network bytes transmitted | Bytes/s | | container.disk.read.bytes | Block I/O reads | Bytes/s | | container.disk.write.bytes | Block I/O writes | Bytes/s | | container.restart_count | Number of container restarts | Count | | container.uptime | Time since container started | Seconds | | container.status | Current status (running, paused, exited) | String | | container.health | Health check status (healthy, unhealthy, none) | String |

Container Tags#

Each container metric is automatically tagged with:

  • container.name -- container name
  • container.id -- short container ID (first 12 characters)
  • container.image -- image name and tag
  • container.labels.* -- all Docker labels as tags

Filtering Containers#

Exclude containers from monitoring using the configuration:

# agent.yaml
docker:
  enabled: true
  exclude_containers:
    - ja-agent         # by name
    - redis-exporter   # by name
  exclude_images:
    - "*/pause:*"      # Kubernetes pause containers
    - "busybox:*"
  include_labels:
    - "com.justanalytics.monitor=true"  # only monitor containers with this label

Docker Compose Example#

# docker-compose.yml
version: "3.8"
services:
  app:
    image: my-app:latest
    labels:
      com.justanalytics.monitor: "true"
      com.justanalytics.service: "web-app"

  redis:
    image: redis:7-alpine
    labels:
      com.justanalytics.monitor: "true"
      com.justanalytics.service: "cache"

  ja-agent:
    image: justanalyticsapp/agent:latest
    pid: host
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      JA_API_KEY: ja_sk_...
      JA_SITE_ID: your-site-id
      JA_URL: https://youranalytics.com

Kubernetes Monitoring#

Prerequisites#

  • JustAnalytics agent running as a DaemonSet (one agent per node)
  • RBAC permissions for the agent service account to read pod/node metrics
  • Kubernetes API server accessible from agent pods

RBAC Configuration#

# kubernetes/rbac.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: justanalytics-agent
  namespace: monitoring
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: justanalytics-agent
rules:
  - apiGroups: [""]
    resources: ["pods", "nodes", "namespaces", "services"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["metrics.k8s.io"]
    resources: ["pods", "nodes"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: justanalytics-agent
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: justanalytics-agent
subjects:
  - kind: ServiceAccount
    name: justanalytics-agent
    namespace: monitoring

Pod Metrics#

| Metric | Description | Unit | |--------|-------------|------| | k8s.pod.cpu.usage | CPU usage | Millicores | | k8s.pod.cpu.request | CPU request | Millicores | | k8s.pod.cpu.limit | CPU limit | Millicores | | k8s.pod.memory.usage | Memory usage | Bytes | | k8s.pod.memory.request | Memory request | Bytes | | k8s.pod.memory.limit | Memory limit | Bytes | | k8s.pod.restarts | Total restart count | Count | | k8s.pod.status | Pod phase | String | | k8s.pod.ready | Ready condition | Boolean |

Node Metrics#

| Metric | Description | Unit | |--------|-------------|------| | k8s.node.cpu.usage | Total node CPU usage | Millicores | | k8s.node.cpu.allocatable | Allocatable CPU | Millicores | | k8s.node.memory.usage | Total node memory usage | Bytes | | k8s.node.memory.allocatable | Allocatable memory | Bytes | | k8s.node.pods.running | Running pods on node | Count | | k8s.node.pods.allocatable | Max pods for node | Count | | k8s.node.conditions | Node conditions (Ready, DiskPressure, etc.) | String |

Cluster-Level Metrics#

| Metric | Description | Unit | |--------|-------------|------| | k8s.cluster.nodes.total | Total nodes in cluster | Count | | k8s.cluster.nodes.ready | Ready nodes | Count | | k8s.cluster.pods.running | Total running pods | Count | | k8s.cluster.pods.pending | Pending pods | Count | | k8s.cluster.pods.failed | Failed pods | Count |

Namespace Filtering#

Monitor only specific namespaces:

# agent.yaml
kubernetes:
  enabled: true
  namespaces:
    - default
    - production
    - staging
  exclude_namespaces:
    - kube-system
    - kube-public
    - monitoring

Resource Usage vs Limits#

The Infrastructure dashboard highlights resource pressure by comparing actual usage to configured requests and limits:

  • Under-provisioned -- usage consistently above 80% of limits (red warning)
  • Right-sized -- usage between 40-80% of limits (green)
  • Over-provisioned -- usage consistently below 20% of limits (yellow suggestion)

The dashboard shows a stacked bar chart for each pod: request, actual usage, and limit, making it easy to spot misconfigurations.

Pod Labels as Tags#

All Kubernetes labels on pods are automatically converted to metric tags:

  • k8s.pod.name -- pod name
  • k8s.namespace -- namespace
  • k8s.node -- node name
  • k8s.deployment -- owning deployment name
  • k8s.labels.* -- all pod labels

Dashboard Overview#

The Infrastructure dashboard provides dedicated views for container and Kubernetes metrics:

Container View#

  • Container list -- sortable table of all containers with CPU, memory, network, status
  • Container detail -- click a container to see time-series charts for all metrics
  • Restart timeline -- visual timeline of container restarts with reasons
  • Health check history -- green/red timeline of health check results

Kubernetes View#

  • Cluster summary -- node count, pod count, resource utilization
  • Node list -- per-node resource usage, conditions, and pod counts
  • Pod list -- per-pod CPU, memory, restart count, and status
  • Namespace breakdown -- resource usage aggregated by namespace
  • Deployment health -- replica count, available vs desired, rollout status

Alerting on Container Metrics#

Create alert rules based on container metrics:

  • Container CPU > 90% for 5 minutes
  • Container memory > 80% of limit for 5 minutes
  • Container restart count > 3 in 30 minutes
  • Kubernetes pod not ready for 5 minutes
  • Node disk pressure detected

Navigate to Monitoring > Alerts and select container/Kubernetes metrics as the alert source.