Prometheus Integration

CloudWise exposes a /metrics endpoint in Prometheus text exposition format, allowing you to scrape cost-waste signals into your existing Prometheus + Grafana stack.

Tier requirement: Shield (from $19/mo) or above.

---

Quick Start

1. Generate an API Key

1. Navigate to Settings → API Keys in the CloudWise dashboard.
2. Click Create API Key and give it a descriptive name (e.g., "Prometheus scraper").
3. Copy the key (cw_...). It is shown only once.

2. Configure Prometheus

Add a scrape job to your prometheus.yml:

scrape_configs:
  - job_name: 'cloudwise'
    scrape_interval: 5m
    scheme: https
    metrics_path: /api/v1/metrics
    # Option A: API key as query parameter
    params:
      api_key: ['cw_your_api_key_here']
    static_configs:
      - targets: ['api.cloudcostwise.io']

Or use Bearer token auth:

scrape_configs:
  - job_name: 'cloudwise'
    scrape_interval: 5m
    scheme: https
    metrics_path: /api/v1/metrics
    authorization:
      type: Bearer
      credentials: 'cw_your_api_key_here'
    static_configs:
      - targets: ['api.cloudcostwise.io']

3. Import the Grafana Dashboard

CloudWise ships a pre-built Grafana dashboard. Import it from:

• File: Download cloudwise-dashboard.json and import via Grafana UI → Dashboards → Import.
• Manual: In Grafana, go to Dashboards → Import, paste the JSON, and select your Prometheus data source.

---

Metrics Reference

Metric	Type	Labels	Description
cloudwise_waste_monthly_savings	gauge	waste_type, resource_type, confidence, region	Estimated monthly savings in USD per waste category
cloudwise_waste_items_total	gauge	waste_type, resource_type, confidence	Count of active waste findings by type
cloudwise_accounts_total	gauge	—	Number of connected AWS accounts
cloudwise_last_scan_timestamp_seconds	gauge	—	Unix timestamp of the most recent waste scan

Label Values

• waste_type: idle_ec2, unattached_ebs, old_ebs_snapshot, idle_rds, unattached_eip, idle_nat_gateway, idle_load_balancer, no_lifecycle_policy, unused_lambda, gp2_migration, etc.
• resource_type: ec2_instance, ebs_volume, rds_instance, elastic_ip, nat_gateway, load_balancer, lambda_function, etc.
• confidence: high, medium, low
• region: AWS region (e.g., us-east-1)

Label Cardinality

Total estimated series per account: ~500. Well within Prometheus limits.

• waste_type: ~124 possible values
• resource_type: ~12 values
• confidence: 3 values
• region: varies (typically 1–5 per customer)

---

Example PromQL Queries

Total monthly savings opportunity

sum(cloudwise_waste_monthly_savings)

Savings by waste type (top 10)

topk(10, sum by (waste_type)(cloudwise_waste_monthly_savings))

Waste item count by resource type

sum by (resource_type)(cloudwise_waste_items_total)

Alert: savings opportunity exceeds threshold

# Alert when total waste exceeds $5,000/month
groups:
  - name: cloudwise
    rules:
      - alert: HighCloudWaste
        expr: sum(cloudwise_waste_monthly_savings) > 5000
        for: 1h
        labels:
          severity: warning
        annotations:
          summary: "Cloud waste exceeds $5,000/month"
          description: "Total monthly savings opportunity is ${{ $value | humanize }}."

Alert: stale scan data

      - alert: CloudWiseScanStale
        expr: time() - cloudwise_last_scan_timestamp_seconds > 86400
        for: 30m
        labels:
          severity: warning
        annotations:
          summary: "CloudWise scan data is stale"
          description: "Last scan was {{ $value | humanizeDuration }} ago."

---

Authentication

The /metrics endpoint supports two authentication methods:

1. Query parameter: ?api_key=cw_... — simplest for Prometheus configs.
2. Bearer token: Authorization: Bearer cw_... — standard HTTP auth.

Both methods require a valid API key. Keys are managed via Settings → API Keys in the CloudWise dashboard. Each user can have up to 5 active keys.

Security notes:

• API keys are SHA-256 hashed at rest; the plaintext key is shown only at creation.
• Keys can be revoked at any time from the dashboard.
• Each key is scoped to the user's accounts and tier.

---

Scrape Interval

Recommended: 5 minutes. CloudWise waste findings refresh when a new scan completes (typically daily or on-demand). Scraping more frequently than every 5 minutes provides no additional signal and wastes resources.

---

Grafana Dashboard

The pre-built dashboard includes:

• Total Monthly Savings — single-stat panel
• Savings by Waste Type — bar chart
• Waste Items by Category — pie chart
• Accounts Connected — single-stat panel
• Last Scan Timestamp — single-stat panel

Customize the dashboard by duplicating it in Grafana and editing panels to fit your team's needs.

---

Troubleshooting

Issue	Solution
401 Unauthorized	Verify your API key is correct and has not been revoked.
403 Forbidden	The /metrics endpoint requires Shield tier or above. Upgrade at Settings → Subscription.
Empty metrics	Ensure at least one AWS account is connected and a waste scan has completed.
Prometheus timeout	CloudWise responds within 2–3 seconds. Check network connectivity and firewall rules.
Stale data	Scans run daily by default. Trigger a manual scan from the CloudWise dashboard, or check Settings → Scan Schedule.