# Output

## Choosing output methods

Use the `output_methods` parameter to select where emissions data is sent. It takes a list of `OutputMethod` enum values:

```
from codecarbon import EmissionsTracker, OutputMethod

tracker = EmissionsTracker(
    output_methods=[OutputMethod.CSV, OutputMethod.API],
)
```

Available values: `CSV`, `API`, `LOGGER`, `PROMETHEUS`, `LOGFIRE`, `BOAMPS`, `SCI`. It can also be set in the config file as a comma-separated string, e.g. `output_methods=csv,api`. HTTP output is enabled separately via the `emissions_endpoint` parameter.

> [!WARNING]
>
> **Deprecation**
>
> The individual `save_to_file`, `save_to_api`, `save_to_logger`, `save_to_prometheus` and `save_to_logfire` parameters are deprecated and will be removed in a future version. Use `output_methods` instead. When `output_methods` is provided, the `save_to_*` flags are ignored. Passing any `save_to_*` parameter emits a `FutureWarning` pointing at your `EmissionsTracker(...)` call. See the [deprecations list](<https://docs.codecarbon.io/latest/reference/deprecations/>).

## CSV

The package has an in-built logger that logs data into a CSV file named `emissions.csv` in the `output_dir`, provided as an input parameter (defaults to the current directory), for each experiment tracked across projects.

By default that file is written once at the end of the run. To also append a row on the same live cadence as API/Prometheus (`api_call_interval × measure_power_secs`), set `live_output_file`:

```
from codecarbon import EmissionsTracker

tracker = EmissionsTracker(
    live_output_file="emissions_live.csv",  # or "auto" / "" → emissions_<run_id>.csv
)
```

Use the same name as `output_file` to enable live rows on the primary CSV. Leave `live_output_file` unset to keep the default final-only behavior.

- Every row holds the **running totals** of the run so far (`emissions`, `energy_consumed`, `duration`...), not the amount for the interval. Take the last row of a `run_id` for its total, and do not sum rows of the same run.
- A row is also appended at each `flush()` and at `stop()`. With `api_call_interval=-1` there are no live rows, only those, and CodeCarbon logs a warning.
- With `"auto"`, the file is named after the `run_id` written in it. When the API output is on, that is the API run id.
- Task CSV files (`start_task()`/`stop_task()`) are written only by the CSV output method, not by the interval file.

The columns are written in the field order of the `EmissionsData` dataclass (`codecarbon/output_methods/emissions_data.py`).

The **Provenance** column says where each number comes from: a hardware counter, a model, or configuration.

| Field | Description | Provenance |
| --- | --- | --- |
| timestamp | Time of the experiment in `%Y-%m-%dT%H:%M:%S` format |  |
| project\_name | Name of the project, defaults to `codecarbon` | Config |
| run\_id | ID of the run | Generated (UUID) |
| experiment\_id | ID of the experiment the run belongs to, used by the API | Config |
| duration | Duration of the compute, in seconds | Measured (wall clock) |
| emissions | Emissions as CO₂-equivalents (CO₂eq), in kg | Computed: `energy × carbon intensity`, see the carbon intensity note |
| emissions\_rate | Emissions divided per duration, in Kg/s | Computed: `emissions / duration` |
| cpu\_power | Mean CPU power (W) | Varies by backend, see the CPU backends note. Mean of the per-interval samples, PUE-scaled |
| gpu\_power | Mean GPU power (W) | Derived from the GPU energy-counter delta over each interval, then averaged. PUE-scaled |
| ram\_power | Mean RAM power (W) | Modelled except on a Raspberry Pi 5, see the RAM note. PUE-scaled |
| cpu\_energy | Energy used per CPU (kWh) | Same backend as `cpu_power`, PUE-inflated |
| gpu\_energy | Energy used per GPU (kWh) | Accumulated board-energy counter: NVML `nvmlDeviceGetTotalEnergyConsumption` (`core/gpu_nvidia.py`) or AMD `amdsmi_get_energy_count` (`core/gpu_amd.py`); while the counter cannot be read, the power sampled every second × time. PUE-inflated |
| ram\_energy | Energy used per RAM (kWh) | Modelled RAM power × interval, PUE-inflated |
| energy\_consumed | Sum of cpu\_energy, gpu\_energy and ram\_energy (kWh) | Sum of the three columns above; every term already PUE-inflated |
| water\_consumed | Water footprint of the run, in litres | Computed: `wue × energy_consumed`. `0` unless you set `wue` |
| country\_name | Name of the country where the infrastructure is hosted | IP geolocation (geojs, ipinfo.io fallback), or config in offline mode |
| country\_iso\_code | 3-letter alphabet ISO Code of the respective country | As `country_name` |
| region | Province/State/City where the compute infrastructure is hosted | As `country_name`; on cloud, from the cloud region lookup |
| cloud\_provider | One of aws/azure/gcp | Cloud instance metadata probe |
| cloud\_region | Geographical region (e.g., us-east-2 for aws, brazilsouth for azure, asia-east1 for gcp) | Cloud instance metadata probe |
| os | Operating system (e.g., Windows-10-10.0.19044-SP0) |  |
| python\_version | Python version (e.g., 3.8.10) |  |
| codecarbon\_version | Version of codecarbon used |  |
| cpu\_count | Number of CPUs | `psutil.cpu_count()`: logical threads, not physical cores. Under SLURM, the CPUs allocated to the job (`count_cpus` in `core/util.py`) |
| cpu\_model | Example: Intel(R) Core(TM) i7-1065G7 CPU @ 1.30GHz | CPU model string detected at startup |
| gpu\_count | Number of GPUs | NVML / AMDSMI device enumeration |
| gpu\_model | Example: 1 x NVIDIA GeForce GTX 1080 Ti | NVML / AMDSMI device name |
| longitude | Longitude of the machine | IP geolocation, full precision, see the coordinates note |
| latitude | Latitude of the machine | IP geolocation, full precision, see the coordinates note |
| ram\_total\_size | Total RAM available (GB) | `psutil.virtual_memory().total` |
| tracking\_mode | `machine` or `process` (default: `machine`) | Config |
| cpu\_utilization\_percent | Average CPU utilization during tracking period (%) | Mean of `psutil.cpu_percent()` samples, taken every second |
| gpu\_utilization\_percent | Average GPU utilization during tracking period (%) | Mean of NVML / AMDSMI utilization samples, taken every second |
| ram\_utilization\_percent | Average RAM utilization during tracking period (%) | Mean of `psutil.virtual_memory().percent` samples |
| ram\_used\_gb | Average RAM used during tracking period (GB) | Mean of `psutil.virtual_memory().used` samples |
| on\_cloud | `Y` if on cloud, `N` for private infrastructure | Cloud instance metadata probe (`core/cloud.py`) |
| pue | Power Usage Effectiveness applied to this run (default `1.0`) | Config, see the PUE note |
| wue | Water Usage Effectiveness in L/kWh (default `0`) | Config |

### Notes on provenance

#### CPU backends

`cpu_power` and `cpu_energy` depend entirely on the backend selected at startup. The backend is chosen once, logged at startup, and not recorded in the CSV. Roughly in decreasing order of trustworthiness:

| Backend | Nature | Where |
| --- | --- | --- |
| Intel RAPL (Linux) | Measured, hardware energy counter | `core/rapl.py` |
| Raspberry Pi 5 | Measured, PMIC voltage and current readings | `Raspberry` in `external/hardware.py` |
| Windows EMI | Measured, hardware energy counter | `core/windows_emi.py` |
| `powermetrics` (macOS, needs sudo) | Measured, OS-reported power. Effectively unreachable on Apple Silicon: `psutil` is a hard dependency, so the `cpu_load` path is selected first (`_try_platform_cpu_backend` in `core/resource_tracker.py`) | `core/powermetrics.py` |
| `cpu_load` mode | Modelled: cubic in load with a 10 % TDP floor in `machine` mode, linear `TDP × load/cpu_count` in `process` mode | `CPU._get_power_from_cpu_load` in `external/hardware.py` |
| `constant` mode | Modelled: `TDP × 0.5`, a flat 50 % of TDP | `CPU._get_power_from_cpus` in `external/hardware.py` |

The last two are estimates, and on a lightly loaded or unusual machine they can be far from the truth. The selection order, including which options override which, is on the [methodology page](<https://docs.codecarbon.io/latest/explanation/methodology/index.md>); measured deviation figures are in [accuracy](<https://docs.codecarbon.io/latest/explanation/accuracy/index.md>).

#### RAM

`ram_power` and `ram_energy` are measured only on a Raspberry Pi 5, whose PMIC reports the DRAM rails. Elsewhere, commodity hardware exposes no RAM energy counter, so CodeCarbon estimates a DIMM count from the total RAM size, then applies 5 W per DIMM on x86 (1.5 W on ARM), with decreasing marginal power above four DIMMs and a floor of two DIMMs' worth (`RAM._calculate_ram_power` in `external/ram.py`). Treat these columns as an order-of-magnitude heuristic. If you can measure your own RAM power, override it with `force_ram_power`.

#### Carbon intensity

`emissions` is only as good as the carbon intensity behind it, which comes from a fallback chain documented on the [methodology page](<https://docs.codecarbon.io/latest/explanation/methodology/index.md>). No column records which level answered: check the run's log output if you need to know.

#### PUE

PUE multiplies the per-component energy and power columns, not just the total. In `_do_measurements` (`emissions_tracker.py`) the PUE is applied to each hardware measurement before it is accumulated. With `pue=1.5`, the `cpu_energy` column is therefore 1.5x the energy the CPU actually drew: it is datacenter energy attributed to the CPU, not raw CPU energy. The power columns are scaled the same way, see the note below. `water_consumed` is computed from the already-inflated energy.

#### Coordinates

`latitude` and `longitude` are written at full precision in the CSV. Rounding to one decimal (\~11 km) is applied only when data is sent to the CodeCarbon API (`core/api_client.py`). If the CSV leaves your machine, treat the coordinates as precise.

> [!NOTE]
>
> **PUE and the power columns**
>
> Since v3.3.1, the `pue` multiplier is applied to the reported power columns (`cpu_power`, `gpu_power`, `ram_power`) as well as to the energy columns, so that `energy_consumed` stays reconstructible from the reported power. Before that, only the energy was scaled. With `pue=1.5`, a machine measured at 100 W is reported as 150 W, and that also applies to forced values: `force_cpu_power=100` with `pue=1.5` reports a 150 W CPU. This is intended: the columns describe the power drawn at the facility level, not at the socket.

> [!NOTE]
>
> Developers can enhance the Output interface by implementing a custom class that extends `BaseOutput` at `codecarbon/output.py`. For example, to log into a database.

## Prometheus

[Prometheus](<https://github.com/prometheus/prometheus>) is a systems and service monitoring system. It collects metrics from configured targets at given intervals, evaluates rule expressions, displays the results, and can trigger alerts when specified conditions are observed.

CodeCarbon exposes all its metrics with the suffix `codecarbon_`.

Current version uses pushgateway mode. If your pushgateway server needs auth, set your environment variables `PROMETHEUS_USERNAME` and `PROMETHEUS_PASSWORD` so CodeCarbon can push the metrics.

### How to test locally

Deploy a local version of Prometheus + Prometheus Pushgateway:

```
docker-compose up
```

Run your EmissionsTracker as usual, adding `OutputMethod.PROMETHEUS` to `output_methods`:

```
from codecarbon import OfflineEmissionsTracker, OutputMethod

tracker = OfflineEmissionsTracker(
    project_name="my_project",
    country_iso_code="USA",
    output_methods=[OutputMethod.CSV, OutputMethod.PROMETHEUS],
)
tracker.start()
# Your code here
tracker.stop()
```

Go to [localhost:9090](<http://localhost:9090>). Search for `codecarbon_` to see all metrics.

## Logfire

[Logfire](<https://docs.pydantic.dev/logfire/>) is an observability platform.

CodeCarbon exposes all its metrics with the suffix `codecarbon_`.

### How to use it

Run your EmissionsTracker as usual, adding `OutputMethod.LOGFIRE` to `output_methods`:

```
from codecarbon import OfflineEmissionsTracker, OutputMethod

tracker = OfflineEmissionsTracker(
    project_name="my_project",
    country_iso_code="USA",
    output_methods=[OutputMethod.CSV, OutputMethod.LOGFIRE],
)
tracker.start()
# Your code here
tracker.stop()
```

The first time it will ask you to log in to Logfire. Once you log in and set the default Logfire project, the metrics will appear following the format `codecarbon_*`.

## BoAmps

[BoAmps](<https://github.com/Boavizta/BoAmps>) is a standardized JSON format for reporting AI and ML energy consumption.

### How to use it

Run your EmissionsTracker as usual, adding `OutputMethod.BOAMPS` to `output_methods`:

```
from codecarbon import OfflineEmissionsTracker, OutputMethod

tracker = OfflineEmissionsTracker(
    project_name="my_project",
    country_iso_code="USA",
    output_methods=[OutputMethod.CSV, OutputMethod.BOAMPS],
)
tracker.start()
# Your code here
tracker.stop()
```

CodeCarbon writes a final report named `boamps_report_<run_id>.json` in `output_dir`.

If you need to enrich the report with task metadata, datasets, or publisher information, use the generic `metadata` parameter and put the BoAmps context under the `boamps` key:

```
from codecarbon import OfflineEmissionsTracker, OutputMethoddocs/reference/output.md

tracker = OfflineEmissionsTracker(
  project_name="my_project",
  country_iso_code="USA",
  output_methods=[OutputMethod.BOAMPS],
  metadata={
    "boamps": {
      "task": {
        "taskStage": "training",
        "taskFamily": "classification",
        "algorithms": ["random_forest"],
        "dataset": "my_dataset",
      },
      "quality": "medium",
    },
    "my_other_metadata": {"owner": "ml-team"},
  },
)
tracker.start()
# Your code here
tracker.stop()
```

`metadata` can also be a path to a JSON file (`metadata="metadata.json"`). For backward compatibility, if `metadata` is a dict without a `boamps` key, the full dict is interpreted as BoAmps metadata.

Sample output:

```
{
  "header": {
    "formatVersion": "0.1",
    "formatVersionSpecificationUri": "https://github.com/Boavizta/BoAmps/tree/main/model",
    "reportId": "79e4408f-ec31-476f-a2c5-8ca7f53e6cc7",
    "reportDatetime": "2026-04-09 23:07:42"
  },
  "measures": [
    {
      "measurementMethod": "codecarbon",
      "version": "3.2.6",
      "averageUtilizationCpu": 0.6,
      "powerConsumption": 6.515418096322266e-05,
      "measurementDuration": 7.052794550996623,
      "measurementDateTime": "2026-04-09 23:07:42"
    }
  ],
  "system": {
    "os": "Linux-6.17.0-19-generic-x86_64-with-glibc2.42"
  },
  "software": {
    "language": "python",
    "version": "3.12.12"
  },
  "infrastructure": {
    "infraType": "onPremise",
    "components": [
      {
        "componentName": "Intel(R) Core(TM) Ultra 7 265H",
        "componentType": "cpu",
        "nbComponent": 8
      },
      {
        "componentType": "ram",
        "nbComponent": 1,
        "memorySize": 30.052967071533203
      }
    ]
  },
  "environment": {
    "country": "France",
    "latitude": 48.6,
    "longitude": 2.3
  }
}
```

## HTTP Output

The HTTP Output allows calling a webhook with emission data when the tracker is stopped. Use the `emissions_endpoint` parameter to specify your endpoint.

## CodeCarbon API

You can send all your data to the CodeCarbon API so you have your historical data in one place. By default, nothing is sent to the API. Add `OutputMethod.API` to `output_methods` and configure your API credentials.

## Logger Output

See [Collecting emissions to a logger](<https://docs.codecarbon.io/latest/how-to/logging/index.md>).

## SCI

The [Software Carbon Intensity](<https://sci.greensoftware.foundation/>) specification, standardised as ISO/IEC 21031:2024, expresses a workload's footprint as a rate:

```
SCI = (E * I + M) / R
```

CodeCarbon measures `E` (energy consumed, kWh) and applies `I` (carbon intensity, gCO2eq/kWh). `R` and `M` are declarations:

- `R`, the functional unit: one request, one training run, 1k tokens. There is no default, so if you do not declare one the report is still written, with `sci: null` and a `status` field saying why.
- `M`, the embodied emissions attributable to the run. When you do not declare a figure the report says `"M_source": "not declared"`, so a reader can see the report is a partial one.

### How to use it

Enable the output method and put the declarations under the `sci` key of the generic `metadata` parameter, next to any other output's section (for example `boamps`):

```
tracker = EmissionsTracker(
    output_methods=["csv", "sci"],
    metadata={
        "sci": {
            "functionalUnit": {"name": "inference request", "count": 10000},
            "embodied": {"gCO2e": 42.5, "source": "manufacturer LCA, 4y amortization"},
            "reporter": {"organization": "Acme", "contact": "green@acme.example"},
            "boundary": "Application only; excludes client devices and network.",
        }
    },
)
```

`metadata` can also be a path to a JSON file, which is how to set it from `.codecarbon.config`:

```
[codecarbon]
output_methods = csv,sci
metadata = ./metadata.json
```

A relative `metadata` path is resolved against the current working directory, not the config file's location. The file holds the same `sci` section:

```
{
  "sci": {
    "functionalUnit": {"name": "inference request", "count": 10000},
    "embodied": {"gCO2e": 42.5, "source": "manufacturer LCA, 4y amortization"},
    "reporter": {"organization": "Acme", "contact": "green@acme.example"},
    "boundary": "Application only; excludes client devices and network."
  }
}
```

If `metadata` has no `sci` section, or it cannot be read, the report is still written without the declarations. To load a file holding only the SCI declarations (no `sci` wrapper) when you build the handler yourself, use `SCIOutput.from_file(path)`; `SCIOutput.from_dict(section)` does the same from a dict.

Both `gCO2e` and `gco2e` are accepted for the embodied figure.

> [!WARNING]
>
> **The configuration-only path needs a count in the context file**
>
> `set_functional_unit_count()` needs a reference to the handler, and the handler created by `output_methods = csv,sci` is owned by the tracker. So with configuration alone, `sci` is `null` in every report unless `functionalUnit.count` is hardcoded in the `sci` section of `metadata`. If the count is only known at the end of the run, construct `SCIOutput` yourself and pass it via `output_handlers=[...]`.

CodeCarbon writes a final report named `sci_report_<run_id>.json` in `output_dir`, plus `sci_report_tasks_<run_id>.json` when tasks are used. A report written by `tracker.flush()` is interim: it applies the full declared `M` to the energy measured so far, so its `sci` is higher than the final one, and it is overwritten by the report written at `stop()`. In the task report, `M` is apportioned across tasks by their share of the tasks' summed duration: the declared `M` is the embodied carbon of the device for the whole run, so giving each task the full figure would count it once per task. If the tasks do not cover the whole run, the full `M` is still spread over the tasks alone. Task reports show `"pue": null` because task data does not carry the PUE. `R` is not apportioned, because CodeCarbon cannot know how many functional units fell inside a task, so each task reports `sciShare`, its share of the run-level SCI, instead of `sci`. `I` is derived as `emissions * 1000 / energy_consumed` rather than recomputed, so the report is consistent with the CSV by construction; the PUE that was applied is recorded separately in the provenance block.

Sample output:

```
{
  "specVersion": "ISO/IEC 21031:2024",
  "generatedBy": "codecarbon 3.2.6",
  "runId": "79e4408f-ec31-476f-a2c5-8ca7f53e6cc7",
  "projectName": "my_project",
  "timestamp": "2025-01-15T10:30:00",
  "sci": 0.00845,
  "unit": "gCO2eq per inference request",
  "terms": {
    "E_kWh": 0.1007,
    "I_gCO2e_per_kWh": 417.08,
    "M_gCO2e": 42.5,
    "R": 10000,
    "R_name": "inference request"
  },
  "provenance": {
    "I_source": "codecarbon regional intensity, country_iso_code=FRA",
    "M_source": "manufacturer LCA, 4y amortization",
    "measurementBoundary": "Application only; excludes client devices and network.",
    "durationSeconds": 3600.0,
    "hardware": {"cpu": "Intel Xeon", "gpu": "NVIDIA A100", "ramTotalGB": 64.0},
    "pue": 1
  }
}
```

See [examples/sci\_output.py](<https://github.com/mlco2/codecarbon/blob/master/examples/sci_output.py>) for a runnable example, including the context file format and how to declare the functional unit count from Python.
