TMF628 Performance Management API - Carbon Intensity ServiceΒΆ
A Node.js implementation of the TMF628 Performance Management API, specialized for serving carbon intensity measurements to support carbon-aware workload scheduling and scaling in ODA Canvas.
OverviewΒΆ
This service provides carbon intensity data through a TMF Forum Open API-compliant interface. It serves real-time carbon intensity measurements (in gCO2eq/kWh) for different geographic regions, enabling ODA Components to make carbon-aware decisions for workload placement, scaling, and scheduling.
The implementation follows the TMF628 Performance Management API standard v5.0.0 with extensions to support dynamic data updates and administrative operations.
FeaturesΒΆ
TMF628 Standard Compliance: Implements the TMF Forum Open API v5.0.0 specification
Real-time Data Updates: Hot-reload capability with file watching (configurable)
Dynamic Updates: In-memory updates via PATCH operations without service restart
Flexible Querying: Filter by timestamp, region, with pagination and field selection
Smart Time Matching: Exact timestamp matching with automatic time-of-day fallback
Administrative Operations: Reload data from file and retrieve statistics
ArchitectureΒΆ
βββββββββββββββββββββββββββββββββββββββββββββββββββ
β Express Server (Port 8628) β
β + OpenAPI Validator β
β + Swagger UI (/api-docs) β
βββββββββββββββββββ¬ββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββΌββββββββββββββββββββββββββββββββ
β PerformanceMeasurementController β
β - Route handling β
β - Parameter extraction β
βββββββββββββββββββ¬ββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββΌββββββββββββββββββββββββββββββββ
β PerformanceMeasurementService β
β - Business logic β
β - Filtering & pagination β
β - Data updates β
βββββββββββββββββββ¬ββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββΌββββββββββββββββββββββββββββββββ
β DataLoader β
β - File reading β
β - Hot-reload/watch β
β - In-memory storage β
βββββββββββββββββββ¬ββββββββββββββββββββββββββββββββ
β
carbon-intensity-data.json
API EndpointsΒΆ
Base PathΒΆ
http://localhost:8628/tmf-api/performance/v5
Standard TMF628 OperationsΒΆ
1. List Performance MeasurementsΒΆ
Retrieve a collection of carbon intensity measurements with optional filtering.
Endpoint: GET /performanceMeasurement
Query Parameters:
Parameter |
Type |
Description |
Example |
|---|---|---|---|
|
ISO 8601 DateTime |
Filter measurements by timestamp. Returns measurements where the timestamp falls within the |
|
|
String |
Filter by region tag |
|
|
String |
Comma-separated list of fields to include in response |
|
|
Integer |
Starting index for pagination |
|
|
Integer |
Maximum number of results to return |
|
Example Requests:
# Get all measurements
curl http://localhost:8628/tmf-api/performance/v5/performanceMeasurement
# Filter by timestamp
curl "http://localhost:8628/tmf-api/performance/v5/performanceMeasurement?validForTimestamp=2026-05-30T10:30:00Z"
# Filter by region
curl "http://localhost:8628/tmf-api/performance/v5/performanceMeasurement?region=us-central1-c"
# Combined filters with pagination
curl "http://localhost:8628/tmf-api/performance/v5/performanceMeasurement?region=us-central1-c&validForTimestamp=2026-05-30T10:30:00Z&limit=5"
# Select specific fields
curl "http://localhost:8628/tmf-api/performance/v5/performanceMeasurement?fields=id,performanceIndicatorValue,tag"
Response Example:
[
{
"id": "ci-us-central1-c-001",
"href": "/tmf-api/performance/v5/performanceMeasurement/ci-us-central1-c-001",
"description": "Carbon intensity measurement for us-central1-c region",
"@type": "PerformanceMeasurementAtomic",
"@baseType": "PerformanceMeasurement",
"validFor": {
"startDateTime": "2026-05-30T00:00:00Z",
"endDateTime": "2026-05-30T00:30:00Z"
},
"performanceIndicatorValue": [
{
"performanceIndicatorSpecification": {
"id": "pi-carbon-intensity",
"name": "Carbon Intensity",
"indicatorCategory": "Environmental",
"indicatorUnit": "gCO2eq/kWh",
"@type": "PerformanceIndicatorSpecification"
},
"observedValue": "500"
}
],
"tag": {
"region": "us-central1-c",
"country": "United States",
"gridOperator": "MISO"
}
}
]
Time Filtering Behavior:
The validForTimestamp parameter implements intelligent time matching:
Exact Match: First attempts to find measurements where the timestamp falls within the
validForperiodTime-of-Day Fallback: If no exact match is found, matches by time-of-day only (ignoring the date)
Date Adjustment: When using time-of-day matching, automatically adjusts the returned dates to match the requested date
This enables querying for βwhat is the carbon intensity at 10:30 AM todayβ even if the data file only contains historical dates.
2. Retrieve Performance Measurement by IDΒΆ
Retrieve a specific carbon intensity measurement by its ID.
Endpoint: GET /performanceMeasurement/{id}
Path Parameters:
Parameter |
Type |
Description |
|---|---|---|
|
String |
Unique identifier of the PerformanceMeasurement |
Query Parameters:
Parameter |
Type |
Description |
|---|---|---|
|
String |
Comma-separated list of fields to include in response |
Example Requests:
# Get measurement by ID
curl http://localhost:8628/tmf-api/performance/v5/performanceMeasurement/ci-us-central1-c-001
# Get specific fields only
curl "http://localhost:8628/tmf-api/performance/v5/performanceMeasurement/ci-us-central1-c-001?fields=id,performanceIndicatorValue"
Response Example:
{
"id": "ci-us-central1-c-001",
"href": "/tmf-api/performance/v5/performanceMeasurement/ci-us-central1-c-001",
"description": "Carbon intensity measurement for us-central1-c region",
"@type": "PerformanceMeasurementAtomic",
"@baseType": "PerformanceMeasurement",
"validFor": {
"startDateTime": "2026-05-30T00:00:00Z",
"endDateTime": "2026-05-30T00:30:00Z"
},
"performanceIndicatorValue": [
{
"performanceIndicatorSpecification": {
"id": "pi-carbon-intensity",
"name": "Carbon Intensity",
"indicatorCategory": "Environmental",
"indicatorUnit": "gCO2eq/kWh",
"@type": "PerformanceIndicatorSpecification"
},
"observedValue": "500"
}
],
"tag": {
"region": "us-central1-c",
"country": "United States",
"gridOperator": "MISO"
}
}
Error Response (404):
{
"message": "PerformanceMeasurement with id ci-invalid-id not found"
}
Extended Operations (Non-Standard TMF628)ΒΆ
3. Update Performance MeasurementΒΆ
Dynamically update specific fields of a carbon intensity measurement in-memory without restarting the service.
Endpoint: PATCH /performanceMeasurement/{id}
Path Parameters:
Parameter |
Type |
Description |
|---|---|---|
|
String |
Unique identifier of the PerformanceMeasurement to update |
Request Body:
Partial PerformanceMeasurement object containing only the fields to update. The id and href fields cannot be changed.
Example Request:
curl -X PATCH http://localhost:8628/tmf-api/performance/v5/performanceMeasurement/ci-us-central1-c-001 \
-H "Content-Type: application/json" \
-d '{
"performanceIndicatorValue": [
{
"performanceIndicatorSpecification": {
"id": "pi-carbon-intensity",
"name": "Carbon Intensity",
"indicatorCategory": "Environmental",
"indicatorUnit": "gCO2eq/kWh",
"@type": "PerformanceIndicatorSpecification"
},
"observedValue": "350"
}
]
}'
Example: Update Carbon Intensity Value
# Update just the carbon intensity value
curl -X PATCH http://localhost:8628/tmf-api/performance/v5/performanceMeasurement/ci-us-central1-c-001 \
-H "Content-Type: application/json" \
-d '{
"performanceIndicatorValue": [
{
"performanceIndicatorSpecification": {
"id": "pi-carbon-intensity",
"name": "Carbon Intensity",
"indicatorCategory": "Environmental",
"indicatorUnit": "gCO2eq/kWh",
"@type": "PerformanceIndicatorSpecification"
},
"observedValue": "250"
}
],
"description": "Updated carbon intensity - cleaner energy mix"
}'
Response:
Returns the updated PerformanceMeasurement object with all fields (both updated and unchanged).
Note: Updates are in-memory only. They will be lost if:
The service restarts
The data file is reloaded (manual or via file watching)
The admin reload endpoint is called
Data StructureΒΆ
PerformanceMeasurement SchemaΒΆ
Carbon intensity measurements follow the TMF628 PerformanceMeasurementAtomic structure:
{
"id": "string", // Unique identifier
"href": "string", // Self-reference URL
"description": "string", // Human-readable description
"@type": "PerformanceMeasurementAtomic",
"@baseType": "PerformanceMeasurement",
"validFor": {
"startDateTime": "ISO 8601", // Start of measurement period
"endDateTime": "ISO 8601" // End of measurement period
},
"performanceIndicatorValue": [
{
"performanceIndicatorSpecification": {
"id": "pi-carbon-intensity",
"name": "Carbon Intensity",
"indicatorCategory": "Environmental",
"indicatorUnit": "gCO2eq/kWh",
"@type": "PerformanceIndicatorSpecification"
},
"observedValue": "string" // Carbon intensity value
}
],
"tag": {
"region": "string", // Geographic region identifier
"country": "string", // Country name
"gridOperator": "string" // Electricity grid operator
}
}
Installation and UsageΒΆ
PrerequisitesΒΆ
Node.js 14+ and npm
Local DevelopmentΒΆ
Install dependencies:
npm install
Configure the service:
Edit config.json to customize server settings:
{
"servers": [
{
"url": "http://localhost:8628/tmf-api/performance/v5"
}
],
"OPENAPI": "/openapi",
"tmfid": "TMF628"
}
Start the service:
npm start
The service will start on port 8628 (configurable via environment variable PORT).
Build automation and versioningΒΆ
The build and release process for docker images is described here: /docs/developer/work-with-dockerimages.md
Kubernetes DeploymentΒΆ
Deploy using the provided Helm chart:
helm install carbon-intensity-service ../../../charts/carbon-intensity-service
See the carbon-intensity-service Helm chart for configuration options.
Data Management StrategiesΒΆ
The API supports three approaches for updating carbon intensity data:
Method |
Persistence |
Use Case |
Endpoint |
|---|---|---|---|
File Update + Hot-reload |
Permanent |
Production, scheduled updates |
File modification triggers automatic reload |
PATCH Operation |
In-memory only |
Testing, temporary overrides |
|
Manual Reload |
Loads from file |
Discard in-memory changes |
|
API Endpoints SummaryΒΆ
Method |
Endpoint |
Description |
Standard |
|---|---|---|---|
GET |
|
List carbon intensity measurements |
TMF628 |
GET |
|
Get measurement by ID |
TMF628 |
PATCH |
|
Update measurement (in-memory) |
Extended |
POST |
|
Reload data from file |
Admin |
GET |
|
Get data statistics |
Admin |
GET |
|
Service status |
Info |
GET |
|
Health check |
Info |
GET |
|
Swagger UI |
Docs |
GET |
|
OpenAPI specification |
Docs |
LoggingΒΆ
The service uses Winston for structured logging. Log messages include:
Incoming request details (method, path, URL)
Query parameter values
Data filtering and transformation steps
File reload events
Error conditions with stack traces
Example log output:
info: TMF628 Performance Management basePath: /tmf-api/performance/v5
info: Data loaded from carbon-intensity-data.json: 48 records
info: File watching enabled for real-time data updates
info: Watching file for changes: carbon-intensity-data.json
info: Express server listening on port 8628
info: Request: GET /tmf-api/performance/v5/performanceMeasurement - URL: /tmf-api/performance/v5/performanceMeasurement?region=us-central1-c
info: listPerformanceMeasurement: total 48 measurements
info: Received parameters: validForTimestamp=undefined, region=us-central1-c
info: Filtered by region us-central1-c: 48 measurements