.. _output:

Output
======

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.


.. list-table:: Data Fields Logged for Each Experiment
   :widths: 20 80
   :align: center
   :header-rows: 1

   * - Field
     - Description
   * - timestamp
     - Time of the experiment in ``%Y-%m-%dT%H:%M:%S`` format
   * - project_name
     - Name of the project, defaults to ``codecarbon``
   * - run-id
     - id of the run
   * - duration
     - Duration of the compute, in seconds
   * - emissions
     - Emissions as CO₂-equivalents [CO₂eq], in kg
   * - emissions_rate
     - emissions divided per duration, in Kg/s
   * - cpu_power
     - CPU power (W)
   * - gpu_power
     - GPU power (W)
   * - ram_power
     - RAM power (W)
   * - cpu_energy
     - Energy used per CPU (kWh)
   * - gpu_energy
     - Energy used per GPU (kWh)
   * - ram_energy
     - Energy used per RAM (kWh)
   * - energy_consumed
     - sum of cpu_energy, gpu_energy and ram_energy (kWh)
   * - country_name
     - Name of the country where the infrastructure is hosted
   * - country_iso_code
     - 3-letter alphabet ISO Code of the respective country
   * - region
     - Province/State/City where the compute infrastructure is hosted
   * - on_cloud
     - ``Y`` if the infrastructure is on cloud, ``N`` in case of private infrastructure
   * - cloud_provider
     - One of the 3 major cloud providers, ``aws/azure/gcp``
   * - cloud_region
     - | Geographical Region for respective cloud provider,
       | examples ``us-east-2 for aws, brazilsouth for azure, asia-east1 for gcp``
   * - os
     - | os on the device
       | example ``Windows-10-10.0.19044-SP0``
   * - python_version
     - example ``3.8.10``
   * - cpu_count:
     - number of CPU
   * - cpu_model
     - example ``Intel(R) Core(TM) i7-1065G7 CPU @ 1.30GHz``
   * - gpu_count
     - number of GPU
   * - gpu_model
     - example ``1 x NVIDIA GeForce GTX 1080 Ti``
   * - longitude
     - | Longitude, with reduced precision to a range of 11.1 km / 123 km².
       | This is done for privacy protection.
   * - latitude
     - | Latitude, with reduced precision to a range of 11.1 km / 123 km².
       | This is done for privacy protection.
   * - ram_total_size
     -  total RAM available (Go)
   * - Tracking_mode:
     - ``machine`` or ``process``(default to ``machine``)

..  note::

    Developers can enhance the Output interface, based on requirements. For example, to log into a database, by implementing a custom Class
    that is a derived implementation of base class ``BaseOutput`` at ``codecarbon/output.py``

Prometheus
----------

Using CodeCarbon with 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 values `PROMETHEUS_USERNAME` and `PROMETHEUS_PASSWORD` so codecarbon is able to push the metrics.

How to test in local
````````````````````

Deploy a local version of Prometheus + Prometheus Pushgateway

.. code-block:: shell

  docker-compose up


Run your EmissionTracker as usual, but with the parameter `save_to_prometheus` as True.
e.g.

.. code-block:: python

  ...
  tracker = OfflineEmissionsTracker(
              project_name=self.project_name,
              country_iso_code="USA",
              save_to_prometheus=True,
          )
  tracker.start()
  ...


Go to `localhost:9090 <http://localhost:9090>`_. Search for `codecarbon_`. You will see all the metrics there.

HTTP Output
-----------

The HTTP Output allow the call of a webhook with emission data when the tracker is stopped.

CodeCarbon API
--------------

You can send all the data to the CodeCarbon API. So you have all your historical data in one place. By default, nothing is sent to the API.

Logger Output
-------------

See :ref:`Collecting emissions to a logger<Collecting emissions to a logger>`.