Prevent to always create a run

codecarbon/_version.py

@@ -1 +1 @@
-__version__ = "2.8.3"
+__version__ = "2.8.4"

codecarbon/core/api_client.py

@@ -39,33 +39,29 @@ class ApiClient:  # (AsyncClient)
 
     def __init__(
         self,
-        # endpoint_url="https://api.codecarbon.io",
-        endpoint_url="https://dash-dev.cleverapps.io/api",  # beta API
+        endpoint_url="https://api.codecarbon.io",
         experiment_id=None,
         api_key=None,
         access_token=None,
         conf=None,
+        create_run_automatically=True,
     ):
         """
-        :project_id: ID of the existing project
+        :endpoint_url: URL of the API endpoint
+        :experiment_id: ID of the experiment
         :api_key: Code Carbon API_KEY
+        :access_token: Code Carbon API access token
+        :conf: Metadata of the experiment
+        :create_run_automatically: If False, do not create a run. To use API in read only mode.
         """
         # super().__init__(base_url=endpoint_url) # (AsyncClient)
         self.url = endpoint_url
         self.experiment_id = experiment_id
         self.api_key = api_key
         self.conf = conf
         self.access_token = access_token
-        if self.experiment_id is not None:
+        if self.experiment_id is not None and create_run_automatically:
             self._create_run(self.experiment_id)
-        import warnings
-
-        # FIXME: remove this warning in the future, once the release is created
-        warnings.warn(
-            "Beta API will be reworked, and some features will be removed. If you have data persisted through the API, please be warned that it will be erased with the next API release",
-            DeprecationWarning,
-            stacklevel=2,
-        )
 
     def _get_headers(self):
         headers = {"Content-Type": "application/json"}
@@ -203,9 +199,8 @@ def get_project(self, project_id):
     def add_emission(self, carbon_emission: dict):
         assert self.experiment_id is not None
         if self.run_id is None:
-            # TODO : raise an Exception ?
-            logger.debug(
-                "ApiClient.add_emission need a run_id : the initial call may "
+            logger.warning(
+                "ApiClient.add_emission() need a run_id : the initial call may "
                 + "have failed. Retrying..."
             )
             self._create_run(self.experiment_id)
@@ -247,14 +242,15 @@ def add_emission(self, carbon_emission: dict):
             return False
         return True
 
-    def _create_run(self, experiment_id):
+    def _create_run(self, experiment_id: str):
         """
         Create the experiment for project_id
-        # TODO : Allow to give an existing experiment_id
         """
         if self.experiment_id is None:
             # TODO : raise an Exception ?
-            logger.error("ApiClient FATAL The API _create_run needs an experiment_id !")
+            logger.error(
+                "ApiClient FATAL The ApiClient._create_run() needs an experiment_id !"
+            )
             return None
         try:
             run = RunCreate(

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 4e0aba649f91939a198f23b5a42c8d17
+config: 72b1bc74f4b0d8a9e438fb97a81dbac2
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_sources/advanced_installation.rst.txt

@@ -0,0 +1,185 @@
+Advanced Installation
+=====================
+
+Install CodeCarbon as a Linux service
+`````````````````````````````````````
+
+To install CodeCarbon as a Linux service, follow the instructions below. It works on Ubuntu or other Debian-based systems using systemd.
+
+Create a dedicated user:
+
+.. code-block::  bash
+
+    sudo useradd -r -s /bin/false codecarbon
+
+Create a directory for the CodeCarbon service:
+
+.. code-block::  bash
+
+    sudo mkdir /opt/codecarbon
+
+Change the ownership of the directory to the user created above:
+
+.. code-block::  bash
+
+    sudo chown codecarbon:codecarbon /opt/codecarbon
+
+Create a virtual environment for CodeCarbon :
+
+.. code-block::  bash
+
+    sudo apt install python3-venv
+    sudo -u codecarbon python3 -m venv /opt/codecarbon/.venv
+
+Install CodeCarbon in the virtual environment:
+
+.. code-block::  bash
+
+    sudo -u codecarbon /opt/codecarbon/.venv/bin/pip install codecarbon
+
+Go to https://dashboard.codecarbon.io/ and create an account to get your API key.
+
+Configure CodeCarbon:
+
+.. code-block::  bash
+
+    sudo -u codecarbon /opt/codecarbon/.venv/bin/codecarbon login
+
+Create a systemd service file:
+
+.. code-block::  bash
+
+    sudo tee /etc/systemd/system/codecarbon.service <<EOF
+    [Unit]
+    Description=CodeCarbon service
+    After=network.target
+
+    [Service]
+    User=codecarbon
+    Group=codecarbon
+    WorkingDirectory=/opt/codecarbon
+    ExecStart=/opt/codecarbon/.venv/bin/codecarbon monitor
+    Restart=always
+
+    [Install]
+    WantedBy=multi-user.target
+    EOF
+
+Give permissions to the ``codecarbon`` group to read the RAPL (Running Average Power Limit) information:
+
+.. code-block::  bash
+
+    sudo chown -R root:codecarbon /sys/class/powercap/intel-rapl/*
+    sudo chmod g+r -R /sys/class/powercap/intel-rapl/*
+
+    sudo apt install sysfsutils
+    echo "mode class/powercap/intel-rapl:0/energy_uj = 0440" >> /etc/sysfs.conf
+    echo "owner class/powercap/intel-rapl:0/energy_uj = root:codecarbon" >> /etc/sysfs.conf
+
+Create the configuration file for CodeCarbon:
+
+.. code-block::  bash
+
+    sudo tee /opt/codecarbon/.codecarbon.config <<EOF
+    [codecarbon]
+    api_endpoint = https://api.codecarbon.io
+    organization_id = <organization_id>
+    project_id = <project_id>
+    experiment_id = <experiment_id>
+    api_key = <api_key>
+    # Verbose logging
+    log_level=WARNING
+    # Measure power every 30 seconds
+    measure_power_secs=30
+    # Send measure to API every 5 minutes (10*30 seconds)
+    api_call_interval=10
+    EOF
+
+Enable and start the service:
+
+.. code-block::  bash
+
+    sudo systemctl enable codecarbon
+    sudo systemctl start codecarbon
+
+Check the traces of the service:
+
+.. code-block::  bash
+
+    journalctl -u codecarbon
+
+
+You are done, CodeCarbon is now running as a service on your machine.
+
+Wait 5 minutes for the first measure to be send to the dashboard at https://dashboard.codecarbon.io/.
+
+
+Deploy CodeCarbon CLI as a Service using Ansible
+````````````````````````````````````````````````
+
+This section describes how to deploy CodeCarbon as a system service using Ansible automation.
+
+It automate the manual installation done in the previous chapter.
+
+What the Playbook Does
+--------------------
+The Ansible playbook automates the following tasks:
+
+* Creates a dedicated system user and group for CodeCarbon
+* Sets up a Python virtual environment
+* Installs CodeCarbon package
+* Configures RAPL permissions for power measurements
+* Creates and configures the systemd service
+* Sets up the CodeCarbon configuration file
+* Starts and enables the service
+
+Prerequisites
+------------
+* Ansible installed on your machine
+* Debian-based target system(s)
+* SSH access to target system(s)
+* CodeCarbon API credentials from the dashboard
+
+Directory Structure
+-----------------
+.. code-block:: text
+
+    codecarbon/deploy/ansible/codecarbon_cli_as_a_service/
+    ├── hosts
+    ├── tasks
+    │   ├── install_codecarbon.yml
+    │   ├── main.yml
+    │   ├── rapl.yml
+    │   └── systemd_service.yml
+    ├── templates
+    │   ├── codecarbon.config.j2
+    │   └── systemd_service.j2
+    └── vars
+        └── main.yml
+
+Quick Start
+----------
+
+1. Set the the target to install in ``hosts``:
+
+   .. code-block:: txt
+
+       yourservername.yourdomain.com   hostname=yourservername ansible_user=root ansible_ssh_private_key_file=~/.ssh/id_ed25519
+
+2. Update the variables in ``vars/main.yml`` with your configuration:
+
+   .. code-block:: yaml
+
+       organization_id: your_org_id
+       project_id: your_project_id
+       experiment_id: your_experiment_id
+       api_key: your_api_key
+
+
+3. Run the playbook:
+
+   .. code-block:: bash
+
+       ansible-playbook -i hosts tasks/main.yml
+
+

docs/_sources/api.rst.txt

@@ -5,7 +5,7 @@ CodeCarbon API
 
 
 CodeCarbon API
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~
 
 .. warning::
     This mode use the CodeCarbon API to upload the timeseries of your emissions on a central server. All data will be public!

docs/_sources/index.rst.txt

@@ -29,6 +29,7 @@ CodeCarbon
    parameters
    examples
    comet
+   advanced_installation
 
 .. toctree::
    :caption: Logging