diff --git a/apps/opik-documentation/documentation/docs/tracing/sdk_configuration.mdx b/apps/opik-documentation/documentation/docs/tracing/sdk_configuration.mdx
new file mode 100644
index 0000000000..734af626f3
--- /dev/null
+++ b/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.
+
+
+
+
+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
+```
+
+
+
+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
+```
+
+
+
+
+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:
+
+
+
+
+```toml
+[opik]
+url_override = https://www.comet.com/opik/api
+workspace =
+api_key =
+```
+
+
+
+```toml
+[opik]
+url_override = http://localhost:5173/api
+workspace = default
+```
+
+
+
+
+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 |
diff --git a/apps/opik-documentation/documentation/sidebars.ts b/apps/opik-documentation/documentation/sidebars.ts
index 9444af02d1..14a4eb5d9a 100644
--- a/apps/opik-documentation/documentation/sidebars.ts
+++ b/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",
diff --git a/sdks/python/src/opik/config.py b/sdks/python/src/opik/config.py
index 011ef89399..c23a5a2ebf 100644
--- a/sdks/python/src/opik/config.py
+++ b/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:
"""