oraclecloud-cost-tuning

What this skill does

# Oracle Cloud Cost Tuning

## Overview

Track OCI spending programmatically using the Usage API and set up budget alerts before Universal Credits run out unexpectedly. OCI pricing varies by shape, region, and commitment level, and the Cost Analysis tool in the Console is buried and confusing. This skill uses the Usage API to query spend by compartment, service, and shape, creates budgets with alert rules, and covers optimization strategies including Always Free tier resources, preemptible instances, and reserved capacity.

**Purpose:** Get visibility into OCI spending through code, set proactive budget alerts, and identify cost optimization opportunities.

## Prerequisites

- **OCI tenancy** with an API signing key in `~/.oci/config`
- **Python 3.8+** with `pip install oci`
- **Tenancy OCID** (root compartment) for tenancy-wide cost queries
- **IAM policy** granting `read usage-reports` in the tenancy
- **Notification topic OCID** for budget alert delivery (see `oraclecloud-observability`)

## Instructions

### Step 1: Query Usage with the Usage API

The Usage API returns cost and usage data broken down by configurable dimensions:

```python
import oci
from datetime import datetime, timedelta

config = oci.config.from_file("~/.oci/config")
usage_api = oci.usage_api.UsageapiClient(config)

# Query last 30 days of spend by service
response = usage_api.request_summarized_usages(
    oci.usage_api.models.RequestSummarizedUsagesDetails(
        tenant_id=config["tenancy"],
        time_usage_started=(datetime.utcnow() - timedelta(days=30)).isoformat() + "Z",
        time_usage_ended=datetime.utcnow().isoformat() + "Z",
        granularity="DAILY",
        query_type="COST",
        group_by=["service"]
    )
)

total_cost = 0.0
for item in response.data.items:
    cost = item.computed_amount or 0
    total_cost += cost
    if cost > 0:
        print(f"{item.service}: ${cost:.2f} ({item.currency})")

print(f"\nTotal 30-day spend: ${total_cost:.2f}")
```

### Step 2: Break Down Cost by Compartment and Shape

Identify which compartments and shapes are driving your bill:

```python
# Cost by compartment
response = usage_api.request_summarized_usages(
    oci.usage_api.models.RequestSummarizedUsagesDetails(
        tenant_id=config["tenancy"],
        time_usage_started=(datetime.utcnow() - timedelta(days=30)).isoformat() + "Z",
        time_usage_ended=datetime.utcnow().isoformat() + "Z",
        granularity="MONTHLY",
        query_type="COST",
        group_by=["compartmentName", "skuName"]
    )
)

for item in response.data.items:
    cost = item.computed_amount or 0
    if cost > 1.0:  # Filter noise
        print(f"{item.compartment_name} | {item.sku_name}: ${cost:.2f}")
```

### Step 3: Create a Budget with Alert Rules

Budgets warn you before spend exceeds a threshold. Create them via SDK instead of hunting through the Console:

```python
budget_client = oci.budget.BudgetClient(config)

# Create a monthly budget for a specific compartment
budget = budget_client.create_budget(
    oci.budget.models.CreateBudgetDetails(
        compartment_id=config["tenancy"],
        target_type="COMPARTMENT",
        targets=["ocid1.compartment.oc1..example"],
        amount=500.0,
        reset_period="MONTHLY",
        display_name="Dev Environment Budget",
        description="Monthly budget for dev compartment"
    )
).data

print(f"Budget created: {budget.id}")

# Add alert rule at 80% threshold
budget_client.create_alert_rule(
    budget_id=budget.id,
    create_alert_rule_details=oci.budget.models.CreateAlertRuleDetails(
        type="ACTUAL",
        threshold=80.0,
        threshold_type="PERCENTAGE",
        display_name="80% Warning",
        recipients="[email protected]",
        message="Dev budget has reached 80% of $500 monthly limit."
    )
)

# Add critical alert at 95%
budget_client.create_alert_rule(
    budget_id=budget.id,
    create_alert_rule_details=oci.budget.models.CreateAlertRuleDetails(
        type="ACTUAL",
        threshold=95.0,
        threshold_type="PERCENTAGE",
        display_name="95% Critical",
        recipients="[email protected]",
        message="CRITICAL: Dev budget at 95%. Review immediately."
    )
)
print("Alert rules created: 80% warning + 95% critical")
```

### Step 4: Forecast Budget with Projected Spend

Set a forecast-based alert that warns you if your current burn rate will exceed the budget:

```python
budget_client.create_alert_rule(
    budget_id=budget.id,
    create_alert_rule_details=oci.budget.models.CreateAlertRuleDetails(
        type="FORECAST",
        threshold=100.0,
        threshold_type="PERCENTAGE",
        display_name="Forecast Overspend",
        recipients="[email protected]",
        message="Projected spend will exceed monthly budget based on current usage."
    )
)
print("Forecast alert created: warns if burn rate exceeds budget")
```

### Step 5: Cost Optimization Strategies

Apply these strategies to reduce OCI spending:

**Always Free tier resources** — run dev/test workloads for free:

- 2 AMD Compute VMs (1/8 OCPU, 1 GB each) or 4 Arm A1 VMs (24 GB total)
- 200 GB total block storage, 10 GB object storage
- 1 Autonomous Database (20 GB), 10 Mbps load balancer
- Monitoring: 500 million ingestion datapoints, 1 billion retrieval datapoints

**Preemptible instances** — up to 50% cheaper for fault-tolerant batch jobs:

```python
compute = oci.core.ComputeClient(config)

compute.launch_instance(
    oci.core.models.LaunchInstanceDetails(
        compartment_id="ocid1.compartment.oc1..example",
        availability_domain="Uocm:US-ASHBURN-AD-1",
        shape="VM.Standard.E4.Flex",
        shape_config=oci.core.models.LaunchInstanceShapeConfigDetails(
            ocpus=4.0,
            memory_in_gbs=16.0
        ),
        preemptible_instance_config=oci.core.models.PreemptibleInstanceConfigDetails(
            preemption_action=oci.core.models.TerminatePreemptionAction(
                type="TERMINATE",
                preserve_boot_volume=False
            )
        ),
        source_details=oci.core.models.InstanceSourceViaImageDetails(
            image_id="ocid1.image.oc1..example",
            source_type="image"
        ),
        create_vnic_details=oci.core.models.CreateVnicDetails(
            subnet_id="ocid1.subnet.oc1..example"
        ),
        display_name="batch-worker-preemptible"
    )
)
print("Preemptible instance launched — up to 50% cost savings")
```

**Reserved capacity** — commit for 1 or 3 years for predictable discounts. Savings vary by shape and term length, typically 30–60% off on-demand pricing.

## Output

Successful completion produces:

- Usage API queries showing cost breakdown by service, compartment, and SKU
- A monthly budget with alert rules at 80% and 95% thresholds
- A forecast-based alert for projected overspend
- Cost optimization patterns: Always Free resources, preemptible instances, and reserved capacity guidance

## Error Handling

| Error | Code | Cause | Solution |
|-------|------|-------|----------|
| NotAuthenticated | 401 | Bad API key or wrong tenancy | Verify `~/.oci/config` fields match your tenancy |
| NotAuthorizedOrNotFound | 404 | Missing `read usage-reports` policy | Add: `Allow group X to read usage-reports in tenancy` |
| TooManyRequests | 429 | Rate limited on Usage API | Reduce query frequency; cache daily results |
| InvalidParameter | 400 | Invalid date range or granularity | Ensure dates are ISO format with Z suffix; use DAILY or MONTHLY |
| InternalError | 500 | OCI Usage API service issue | Check [OCI Status](https://ocistatus.oraclecloud.com) and retry |
| ServiceError status -1 | N/A | Timeout on large cost queries | Narrow date range or reduce `group_by` dimensions |

## Examples

**Quick cost check with OCI CLI:**

```bash
# List all budgets in your tenancy
oci budgets budget list --compartment-id $OCI_TENANCY_OCID

# Get current month spend summary
oci usage-api usage-summary request-summarized-usages \
  --tenant-