App Environment Metrics API

The App Environment Metrics API allows you to retrieve real-time resource usage metrics (CPU, memory, containers) for an app environment in Quave Cloud.

Make sure to read the Get Started document to understand how the API works.

Note: This API endpoint accepts only user tokens (not environment tokens).

Get App Environment Metrics

To retrieve metrics for an app environment, send a GET request to the /api/public/v1/app-env/metrics endpoint. You need to provide either appEnvId or envName to identify the environment.

Required Parameters (Either/Or)

You must provide either appEnvId or envName:

Parameter	Type	Description
appEnvId	String	The ID of the app environment to retrieve metrics for.
envName	String	The CLI environment name (alternative to appEnvId).

Response Structure

The response is a JSON object with the following fields:

Field	Type	Description
appEnvId	String	The app environment ID.
timestamp	Date	Timestamp when metrics were retrieved.
resources	Object	CPU and memory usage metrics (see below).
containers	Object	Container count and status (see below).
autoScaling	Object	Autoscaling configuration (see below).

Resources Object

The resources object contains CPU and memory metrics:

{
  "cpu": {
    "allocated": 1.0,      // CPU cores allocated
    "used": 0.65,          // CPU cores currently in use
    "usagePercent": 65,    // Usage percentage (0-100)
    "updatedAt": "2024-01-15T10:30:00.000Z"  // Last metric update
  },
  "memory": {
    "allocated": 512,      // Memory allocated in MB
    "used": 380,          // Memory currently in use in MB
    "usagePercent": 74,    // Usage percentage (0-100)
    "updatedAt": "2024-01-15T10:30:00.000Z"  // Last metric update
  }
}

Containers Object

The containers object provides information about running pods:

Field	Type	Description
desired	Number	Desired number of containers/replicas.
running	Number	Number of containers currently running.
ready	Number	Number of containers that are ready.
updatedAt	Date	Last update timestamp (null if no data available).

AutoScaling Object

The autoScaling object describes autoscaling configuration:

When autoscaling is enabled:

{
  "enabled": true,
  "minReplicas": 1,          // Minimum number of replicas
  "maxReplicas": 4,          // Maximum number of replicas
  "currentReplicas": 2,      // Current replica count
  "targetCPU": 70,           // Target CPU utilization percentage (null if not set)
  "targetMemory": 80         // Target memory utilization percentage (null if not set)
}

When autoscaling is disabled:

{
  "enabled": false
}

Example: Get Metrics (with appEnvId)

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/metrics?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b'

Example: Get Metrics (with envName)

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/metrics?envName=production'

Example Response

{
  "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "resources": {
    "cpu": {
      "allocated": 1.0,
      "used": 0.65,
      "usagePercent": 65,
      "updatedAt": "2024-01-15T10:29:45.000Z"
    },
    "memory": {
      "allocated": 512,
      "used": 380,
      "usagePercent": 74,
      "updatedAt": "2024-01-15T10:29:45.000Z"
    }
  },
  "containers": {
    "desired": 2,
    "running": 2,
    "ready": 2,
    "updatedAt": "2024-01-15T10:29:50.000Z"
  },
  "autoScaling": {
    "enabled": true,
    "minReplicas": 1,
    "maxReplicas": 4,
    "currentReplicas": 2,
    "targetCPU": 70,
    "targetMemory": 80
  }
}

Use Cases

This endpoint is useful for:

1. Performance Monitoring - Track CPU and memory usage in real-time
2. Capacity Planning - Understand resource utilization patterns
3. Alerting - Set up alerts based on resource thresholds
4. Autoscaling Decisions - See how autoscaling is performing
5. Cost Optimization - Identify over-provisioned or under-utilized resources

Understanding Metrics

CPU Metrics:

• allocated is the total CPU cores assigned to the environment
• used is the current CPU usage across all containers
• usagePercent is calculated as (used / allocated) * 100

Memory Metrics:

• allocated is the total memory (MB) assigned to the environment
• used is the current memory consumption across all containers
• usagePercent is calculated as (used / allocated) * 100

Container Metrics:

• desired is the configured replica count (or autoscaler's current target)
• running is the number of pods that are currently running
• ready is the number of pods that have passed health checks
• If running < desired, containers may be starting or failed

Autoscaling:

• When enabled, the autoscaler adjusts currentReplicas based on targetCPU and targetMemory
• Replicas will scale between minReplicas and maxReplicas
• If targetCPU or targetMemory is null, that metric is not used for scaling decisions

Metric Freshness

• Metrics are typically updated every 30-60 seconds
• The updatedAt fields show when each metric was last updated
• If updatedAt is null, that metric has not been collected yet (new environment)

Error Responses

• 400 - Missing required parameters (neither appEnvId nor envName provided)
• 401 - User not authenticated
• 403 - User doesn't have permission to access this app environment
• 404 - App environment not found for the given appEnvId or envName

Notes

Environment Identification:

• You can use either appEnvId or envName to identify the environment
• If both are provided, appEnvId takes precedence

Zero Values:

• If metrics show 0% usage, the environment may be stopped or metrics collection hasn't started
• New environments may take a few minutes to report metrics

High Usage:

• Consistently high CPU/memory usage (>80%) may indicate need for more resources
• If running < desired with high usage, containers may be crashing due to resource limits