Added config documentation (#482)

apps/opik-documentation/documentation/docs/tracing/sdk_configuration.mdx

@@ -0,0 +1,111 @@
+---
+sidebar_position: 5
+sidebar_label: Python SDK Configuration
+toc_min_heading_level: 2
+toc_max_heading_level: 4
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Python SDK Configuration
+
+The recommended approach to configuring the Python SDK is to use the `opik configure` command. This will prompt you for the necessary information and save it to a configuration file.
+
+<Tabs>
+    <TabItem value="Opik Cloud" title="Opik Cloud">
+
+If you are using the Cloud version of the platform, you can configure the SDK by running:
+
+```python
+import opik
+
+opik.configure(use_local=False)
+```
+
+You can also configure the SDK by calling [`configure`](https://www.comet.com/docs/opik/python-sdk-reference/cli.html) from the Command line:
+
+```bash
+opik configure
+```
+
+    </TabItem>
+    <TabItem value="Self-hosting" title="Self-hosting">
+If you are self-hosting the platform, you can configure the SDK by running:
+
+```python
+import opik
+
+opik.configure(use_local=True)
+```
+
+or from the Command line:
+
+```bash
+opik configure --use_local
+```
+
+    </TabItem>
+</Tabs>
+
+The `configure` methods will prompt you for the necessary information and save it to a configuration file (`~/.opik.config`).
+
+## Advanced usage
+
+In addition to the `configure` method, you can also configure the Python SDK in a couple of different ways:
+1. Using a configuration file
+2. Using environment variables
+
+### Using a configuration file
+
+The `configure` method is a helper method to help you create the Opik SDK configuration file but you can also manually create the configuration file.
+
+The Opik configuration file follows the [TOML](https://github.com/toml-lang/toml) format, here is an example configuration file:
+
+<Tabs>
+    <TabItem value="Opik Cloud" title="Opik Cloud">
+
+```toml
+[opik]
+url_override = https://www.comet.com/opik/api
+workspace = <Workspace name>
+api_key = <API Key>
+```
+
+    </TabItem>
+    <TabItem value="Self-hosting" title="Self-hosting">
+```toml
+[opik]
+url_override = http://localhost:5173/api
+workspace = default
+```
+    </TabItem>
+</Tabs>
+
+
+You can find a full list of the the configuration options in the [Configuration values section](/tracing/sdk_configuration#configuration-values) below.
+
+:::tip
+By default, the SDK will look for the configuration file in your home directory (`~/.opik.config`). If you would like to specify a different location, you can do so by setting the `OPIK_CONFIG_PATH` environment variable.
+:::
+
+### Using environment variables
+
+If you do not wish to use a configuration file, you can set environment variables to configure the SDK. The most common configuration values are:
+
+- `OPIK_URL_OVERRIDE`: The URL of the Opik server to use - Defaults to `https://www.comet.com/opik/api`
+- `OPIK_API_KEY`: The API key to use - Only required if you are using the Opik Cloud version of the platform
+- `OPIK_WORKSPACE`: The workspace to use - Only required if you are using the Opik Cloud version of the platform
+
+You can find a full list of the the configuration options in the [Configuration values section](/tracing/sdk_configuration#configuration-values) below.
+
+### Configuration values
+
+Here is a list of the configuration values that you can set:
+
+| Configuration Name | Environment variable | Description |
+| url_override | `OPIK_URL_OVERRIDE` | The URL of the Opik server to use - Defaults to `https://www.comet.com/opik/api` |
+| api_key | `OPIK_API_KEY` | The API key to use - Only required if you are using the Opik Cloud version of the platform |
+| workspace | `OPIK_WORKSPACE` | The workspace to use - Only required if you are using the Opik Cloud version of the platform |
+| project_name | `OPIK_PROJECT_NAME` | The project name to use |
+| default_flush_timeout | `OPIK_DEFAULT_FLUSH_TIMEOUT` | The default flush timeout to use - Defaults to no timeout |

apps/opik-documentation/documentation/sidebars.ts

@@ -30,6 +30,7 @@ const sidebars: SidebarsConfig = {
         "tracing/log_multimodal_traces",
         "tracing/log_distributed_traces",
         "tracing/annotate_traces",
+        "tracing/sdk_configuration",
         {
           type: "category",
           label: "Integrations",

sdks/python/src/opik/config.py

@@ -1,5 +1,6 @@
 import configparser
 import logging
+import os
 import pathlib
 from typing import Any, Dict, Final, List, Literal, Optional, Tuple, Type, Union
 
@@ -38,7 +39,14 @@ def __init__(
         self,
         settings_cls: Type[BaseSettings],
     ):
-        self.ini_data = self._read_files(CONFIG_FILE_PATH_DEFAULT)
+        config_file_path = os.getenv("OPIK_CONFIG_PATH", CONFIG_FILE_PATH_DEFAULT)
+        expanded_path = pathlib.Path(config_file_path).expanduser()
+        if config_file_path != CONFIG_FILE_PATH_DEFAULT and not expanded_path.exists():
+            LOGGER.warning(
+                f"Config file not found at the path '{expanded_path}' provided by the `OPIK_CONFIG_PATH` environment variable."
+            )
+        self.ini_data = self._read_files(expanded_path)
+
         super().__init__(settings_cls, self.ini_data)
 
     def _read_file(self, file_path: pathlib.Path) -> Dict[str, Any]:
@@ -142,7 +150,8 @@ def settings_customise_sources(
 
     @property
     def config_file_fullpath(self) -> pathlib.Path:
-        return pathlib.Path(CONFIG_FILE_PATH_DEFAULT).expanduser()
+        config_file_path = os.getenv("OPIK_CONFIG_PATH", CONFIG_FILE_PATH_DEFAULT)
+        return pathlib.Path(config_file_path).expanduser()
 
     def save_to_file(self) -> None:
         """