Welcome to CloudNode Docs

Quick Start Guide

Follow these steps to connect your first infrastructure node to CloudNode. You'll need an API key from your account dashboard.

1. Install the CloudNode agent

The agent is a lightweight daemon that streams metrics from your host to CloudNode. Install it with a single command:

# Install the CloudNode agent
curl -sSL https://get.cloudnodeanalytics.co.uk/install.sh | bash

# Or via npm
npm install -g @cloudnode/agent

2. Initialise and start the agent

Replace YOUR_API_KEY with the key from your dashboard.

cloudnode init --api-key YOUR_API_KEY --region eu-west-1
cloudnode start

# Verify the agent is running
cloudnode status

Within 60 seconds your node will appear in the CloudNode dashboard under Infrastructure → Nodes.

Nodes & Agents

A node is any compute instance (VM, container host, bare-metal server) running the CloudNode agent. The agent collects:

• CPU, memory, disk, and network utilisation every 10 seconds
• Application log streams from configured paths
• Custom metric pushes via the local HTTP sidecar API

Nodes are grouped into environments (e.g. production, staging). You can define environments in the dashboard or via the API.

Data Retention Policies

Retention policies control how long different types of data are stored and in which storage tier. By default, all plans use the following tiers:

• Hot tier — NVMe SSD, query latency <2ms, 30-day window
• Warm tier — Object storage, query latency <500ms, up to 13 months
• Archive tier — Glacier-class storage, on Enterprise plans, up to 5 years

You can create custom policies per environment using the Retention API:

POST /v1/retention-policies
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "eu-gdpr-standard",
  "hot_days": 30,
  "warm_days": 365,
  "gdpr_erasure": true,
  "environments": ["production"]
}

Dashboard Builder

Dashboards are built from widgets. Available widget types include:

• Time series — line or area chart over any metric
• Stat — single value with optional sparkline and threshold colouring
• Table — sorted results from any metrics query
• Heatmap — frequency distribution over time (useful for latency distributions)
• Alert status — live status badge for an alert rule

Dashboards can be shared via a public link (read-only) or embedded in internal tools using the embed URL with an embed token.

AWS Integration

Use the CloudNode Terraform module or the IAM-based auto-discovery to connect all EC2 instances in an AWS account automatically.

module "cloudnode" {
  source  = "cloudnode/analytics/aws"
  version = "~> 2.0"

  api_key     = var.cloudnode_api_key
  environment = "production"
  regions     = ["eu-west-1", "us-east-1"]
}

GCP Integration

CloudNode supports GCP via a Workload Identity Federation binding — no service account key file is stored. See the GCP setup guide for full instructions.

Azure Integration

Connect Azure subscriptions using Managed Identity. The CloudNode Azure extension is available in the Azure Marketplace.

Kubernetes

Deploy the CloudNode agent as a DaemonSet. A Helm chart is provided:

helm repo add cloudnode https://charts.cloudnodeanalytics.co.uk
helm repo update

helm install cloudnode-agent cloudnode/agent \
  --set apiKey=YOUR_API_KEY \
  --set environment=production \
  --namespace monitoring --create-namespace

API Authentication

All API requests must include an Authorization header with a Bearer token:

GET /v1/nodes
Host: api.cloudnodeanalytics.co.uk
Authorization: Bearer cn_live_abc123xyz...

API keys are scoped to read, write, or admin permissions. Generate keys from Account → API Keys in the dashboard.

REST Endpoints

Base URL: https://api.cloudnodeanalytics.co.uk/v1

• GET /nodes — list all nodes in your account
• GET /nodes/:id/metrics — retrieve time-series metrics for a node
• POST /retention-policies — create a retention policy
• GET /alerts — list alert rules
• POST /alerts — create an alert rule
• GET /dashboards — list dashboards

The full OpenAPI 3.1 specification is available at api.cloudnodeanalytics.co.uk/openapi.json.

GraphQL Schema

The GraphQL endpoint is at https://api.cloudnodeanalytics.co.uk/graphql. Authentication is identical to REST.

query NodeMetrics($nodeId: ID!, $from: DateTime!, $to: DateTime!) {
  node(id: $nodeId) {
    id
    name
    metrics(from: $from, to: $to, resolution: MINUTE) {
      timestamp
      cpuPercent
      memoryUsedBytes
      eventsPerSecond
    }
  }
}

Setting Up Alerts

Alerts are evaluated every 30 seconds against a rolling window of your choosing. To create an alert rule via the API:

POST /v1/alerts
Content-Type: application/json

{
  "name": "High CPU on prod",
  "condition": "avg(cpu_percent, 5m) > 85",
  "environments": ["production"],
  "severity": "critical",
  "channels": ["slack:ops-alerts", "pagerduty:primary"]
}

Exporting Data

Export raw metrics as CSV or NDJSON via the export endpoint. Exports are generated asynchronously and delivered to an S3-compatible bucket or a signed download URL.

GDPR Compliance

CloudNode provides a right-to-erasure API that lets you delete all data associated with a specific user identifier from all storage tiers within 72 hours — meeting the GDPR Article 17 obligation. See our Privacy Policy for data processor details.