carbon-config.yaml

SCI Formula:** $$SCI = (E \times I) + M$$

Where:

• $E$: Energy consumed by the functional unit (kWh).
• $I$: Carbon intensity of the location where energy is consumed (gCO₂eq/kWh).
• $M$: Embodied carbon emissions of the hardware (gCO₂eq).

Architecture Decision: Middleware Instrumentation

To minimize intrusion, carbon calculation should be implemented as middleware in the request lifecycle. This approach captures request-level metadata (region, timestamp, resource usage) and emits carbon metrics alongside standard telemetry.

Rationale:

• Decoupling: Business logic remains unaware of carbon calculations.
• Granularity: Enables per-request or per-job carbon attribution.
• Standardization: Enforces consistent SCI boundaries across services.

Implementation: TypeScript Calculator

The following TypeScript implementation demonstrates a robust SCI calculator that handles dynamic grid intensity and embodied carbon estimation.

import { createHmac } from 'crypto';

// Interfaces for type safety and API contracts
interface GridIntensityResponse {
  latitude: number;
  longitude: number;
  country: string;
  region?: string;
  timezone: string;
  timestamp: string;
  utcOffset: string;
  intensity: {
    total: number; // gCO2eq/kWh
    fossil: number;
    renewable: number;
  };
  isEstimated: boolean;
  estimationMethod?: string;
}

interface SCICalculatorConfig {
  provider: 'aws' | 'azure' | 'gcp' | 'on-prem';
  region: string;
  functionalUnit: string; // e.g., 'per-request', 'per-transaction'
  embodiedCarbonPerKwh?: number; // Estimated M factor based on hardware lifecycle
  gridIntensityApiUrl: string;
  apiKey: string;
}

class CarbonFootprintCalculator {
  private config: SCICalculatorConfig;
  private intensityCache: Map<string, GridIntensityResponse>;

  constructor(config: SCICalculatorConfig) {
    this.config = config;
    this.intensityCache = new Map();
  }

  /**
   * Calculates SCI for a specific event.
   * @param energyKwh Energy consumed in kWh for the functional unit.
   * @param timestamp ISO string of the event time.
   * @returns SCI value in gCO2eq per functional unit.
   */
  async calculateSCI(energyKwh: number, timestamp: string): Promise<number> {
    const intensity = await this.getGridIntensity(timestamp);
    
    // M factor calculation: Embodied carbon amortized over hardware lifetime
    // Simplified model: M = (HardwareManufacturingCO2 / TotalExpectedEnergy)
    // In production, fetch from hardware inventory database.
    const mFactor = this.config.embodiedCarbonPerKwh || this.estimateEmbodiedCarbon();

    // SCI Formula: (E * I) + M
    const sci = (energyKwh * intensity.intensity.total) + mFactor;

    return Math.round(sci * 100) / 100; // Round to 2 decimals
  }

  /**
   * Fetches grid intensity with caching to minimize API calls.
   * Caches by region + hour to allow reuse for batch requests.
   */
  private async getGridIntensity(timestamp: string): Promise<GridIntensityResponse> {
    const hourKey = timestamp.slice(0, 13); // YYYY-MM-DDTHH
    const cacheKey = `${this.config.region}-${hourKey}`;

    if (this.intensityCache.has(cacheKey)) {
      return this.intensityCache.get(cacheKey)!;
    }

    try {
      const response = await fetch(`${this.config.gridIntensityApiUrl}?timestamp=${timestamp}&region=${this.config.region}`, {
        headers: { 'Authorization': `Bearer ${this.config.apiKey}` }
      });

      if (!response.ok) throw new Error(`Grid API error: ${response.status}`);
      
      const data = await response.json();
      this.intensityCache.set(cacheKey, data);
      
      // Evict old cache entries to manage memory
      if (this.intensityCache.size > 1000) {
        const firstKey = this.intensityCache.keys().next().value;
        this.intensityCache.delete(firstKey);
      }

      return data;
    } catch (error) {
      console.error('Failed to fetch grid intensity, falling back to region average.', error);
      return this.getFallbackIntensity();
    }
  }

  private getFallbackIntensity(): GridIntensityResponse {
    // Fallback to static annual average if API is unavailable
    // Values should be sourced from IPCC or regional grid operators
    const fallbackMap: Record<string, number> = {
      'us-east-1': 420, // Example: Virginia coal mix
      'eu-north-1': 40, // Example: Sweden hydro/nuclear
      'ap-south-1': 750 // Example: India coal dominant
    };
    
    const intensity = fallbackMap[this.config.region] || 500;
    return {
      intensity: { total: intensity, fossil: intensity, renewable: 0 },
      isEstimated: true,
      estimationMethod: 'fallback-annual-average',
      // ... other required fields omitted for brevity
    } as GridIntensityResponse;
  }

  private estimateEmbodiedCarbon(): number {
    // Simplified estimation: ~150 gCO2eq/kWh amortized
    // Real implementation should query hardware asset database
    return 150;
  }
}

// Usage Example
async function instrumentRequest(energyKwh: number, region: string, timestamp: string) {
  const calculator = new CarbonFootprintCalculator({
    provider: 'aws',
    region: region,
    functionalUnit: 'per-request',
    gridIntensityApiUrl: 'https://api.electricitymap.org/v3/latest',
    apiKey: process.env.ELECTRICITY_MAP_API_KEY!,
    embodiedCarbonPerKwh: 150
  });

  const sci = await calculator.calculateSCI(energyKwh, timestamp);
  
  // Emit metric to observability backend
  console.log(`Metric: sci_gco2eq {region="${region}"} ${sci}`);
  return sci;
}

Architecture Integration

1. Telemetry Export: The calculator emits metrics to OpenTelemetry collectors. Configure a custom metric software.carbon.intensity with attributes region, service.name, and functional.unit.
2. Energy Estimation: For serverless functions, use provider-specific estimators. AWS Lambda provides memory-based energy proxies. For containers, correlate CPU/memory usage with PUE (Power Usage Effectiveness) and server efficiency curves.
3. Dashboarding: Create Grafana dashboards that overlay carbon intensity on traffic graphs. This visual correlation helps engineers identify high-carbon traffic patterns.

Pitfall Guide

Production environments introduce complexities that theoretical models often miss. Avoid these common errors to ensure calculation integrity.

1. Ignoring Scope 3 Boundaries

   • Mistake: Calculating only direct electricity usage (Scope 2) and ignoring hardware manufacturing (Scope 3) or network transmission.
   • Impact: Underestimates total footprint by 20-40%.
   • Fix: Include embodied carbon factors in the SCI calculation. Account for network egress energy where possible.

2. Hardcoding Grid Intensity

   • Mistake: Using static values from provider documentation that may be outdated or represent annual averages.
   • Impact: Renders carbon-aware scheduling impossible. Masks temporal optimization opportunities.
   • Fix: Integrate dynamic APIs (e.g., Electricity Maps, WattTime) with caching. Implement fallbacks but flag data quality in metrics.

3. Double Counting in Multi-Tenant Systems

   • Mistake: Aggregating SCI across services without deduplication. If Service A calls Service B, both may calculate emissions for the same compute cycle.
   • Impact: Inflated carbon reporting.
   • Fix: Define clear SCI boundaries. Use distributed tracing to attribute emissions to the root cause or consumer. Implement "pass-through" headers to avoid recalculation.

4. Over-Provisioning for Carbon Safety

   • Mistake: Increasing resource allocation to ensure low latency, ignoring the linear relationship between idle resources and embodied carbon.
   • Impact: Wasted hardware lifecycle and increased energy consumption.
   • Fix: Implement autoscaling policies that consider carbon intensity. Right-size instances based on actual load profiles.

5. Neglecting Network Emissions

   • Mistake: Focusing solely on compute and storage while ignoring data transfer.
   • Impact: Inaccurate for data-heavy applications (video streaming, AI model training).
   • Fix: Include network energy factors in the energy estimation model. Optimize payload sizes and use compression.

6. Lack of Granularity

   • Mistake: Calculating carbon at the account or project level rather than the service or function level.
   • Impact: Unable to identify hotspots or assign responsibility.
   • Fix: Instrument at the lowest practical level. Use tags and labels to break down emissions by feature, team, or environment.

7. Ignoring Data Center PUE

   • Mistake: Assuming cloud provider efficiency applies uniformly across all regions and hardware generations.
   • Impact: Inaccurate energy conversion from resource usage.
   • Fix: Apply region-specific PUE multipliers. Update PUE factors periodically based on provider disclosures.

Production Bundle

Action Checklist

• Define SCI Boundaries: Document the scope of your calculation (e.g., hardware, software, usage) and functional units.
• Select Intensity Provider: Choose a dynamic grid intensity API and configure API keys with appropriate rate limits.
• Instrument Telemetry: Deploy the carbon calculator middleware to capture energy and intensity data.
• Implement Embodied Carbon: Integrate hardware lifecycle data or use standardized estimation factors.
• Set Carbon Budgets: Define maximum allowable SCI per functional unit and integrate checks into CI/CD pipelines.
• Enable Carbon-Aware Scheduling: Configure batch jobs and non-urgent workloads to defer execution during high-intensity periods.
• Audit and Validate: Periodically compare calculated emissions against provider reports and third-party audits.

Decision Matrix

Use this matrix to select the appropriate calculation strategy based on organizational maturity and constraints.

Scenario	Recommended Approach	Why	Cost Impact
Startup / MVP	Static Region Average + Code Efficiency	Low implementation overhead; sufficient for initial reporting.	Minimal; avoids API costs.
Enterprise Compliance	Dynamic Real-Time SCI + Scope 3	Required for accurate ESG reporting and regulatory compliance.	Medium; API costs and engineering effort.
Batch Processing / AI	Dynamic Shifting + Region Optimization	High compute volume allows significant savings via temporal and spatial shifting.	High reduction; potential infra cost savings.
Real-Time User Facing	Static with Code Optimization	Latency constraints prevent dynamic shifting; focus on efficiency.	Low; optimization reduces compute costs.

Configuration Template

Deploy this configuration to standardize carbon calculation across services.

# carbon-config.yaml
carbon:
  sci:
    version: "1.0" # SCI Specification version
    boundary:
      hardware: true
      software: true
      usage: true
    functional_unit: "per-transaction"
  
  grid_intensity:
    provider: "electricity_maps"
    api_endpoint: "https://api.electricitymap.org/v3/latest"
    cache_ttl_seconds: 3600
    fallback_strategy: "region_annual_average"
    fallback_sources:
      us-east-1: 420
      eu-west-1: 250
      ap-northeast-1: 500

  embodied:
    estimation_method: "hardware_inventory"
    amortization_years: 5
    default_gco2_per_kwh: 150

  telemetry:
    metric_name: "software.carbon.intensity"
    unit: "gCO2eq"
    labels:
      - "service.name"
      - "region"
      - "environment"
      - "functional.unit"

  actions:
    carbon_budget:
      enabled: true
      threshold_gco2: 500 # Per 1000 transactions
      alert_on_breach: true
    scheduling:
      enabled: true
      min_intensity_threshold: 300 # gCO2/kWh
      max_defer_hours: 4

Quick Start Guide

1. Install Dependencies: Add the carbon calculator library to your project repository. Configure the carbon-config.yaml file with your region and API keys.
2. Deploy Middleware: Integrate the calculator into your request pipeline. For Node.js/TypeScript, add the middleware to your Express/Fastify setup. For Python, use framework-specific decorators.
3. Configure Observability: Update your Prometheus/Grafana configuration to scrape the software.carbon.intensity metric. Import the provided dashboard template to visualize SCI trends.
4. Validate: Trigger test traffic and verify that carbon metrics appear in your dashboard with correct region and intensity values. Check logs for fallback events.
5. Set Budgets: Define carbon budgets in your CI/CD pipeline. Configure the pipeline to fail builds that introduce SCI regressions exceeding the defined threshold.

Conclusion

Carbon footprint calculation is no longer optional for engineering teams. It is a critical dimension of system performance, comparable to latency and availability. By implementing dynamic SCI calculation, integrating embodied carbon, and leveraging carbon-aware scheduling, organizations can significantly reduce their environmental impact while optimizing infrastructure costs. The transition requires disciplined measurement, standardized tooling, and a shift in engineering culture to treat carbon as a first-class operational metric.