_ecologits

EcoLogits

EcoLogits instrumentor to initialize function patching for each provider.

Examples:

EcoLogits initialization example with OpenAI.

from ecologits import EcoLogits
from openai import OpenAI

EcoLogits.init(providers=["openai"])

client = OpenAI(api_key="<OPENAI_API_KEY>")
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Tell me a funny joke!"}
    ]
)

# Get estimated environmental impacts of the inference
print(f"Energy consumption: {response.impacts.energy.value} kWh")
print(f"GHG emissions: {response.impacts.gwp.value} kgCO2eq")

init(providers=None, electricity_mix_zone='WOR', opentelemetry_endpoint=None) staticmethod

Initialization static method. Will attempt to initialize all providers by default.

Parameters:

Name	Type	Description	Default
providers	str | list[str] | None	list of providers to initialize (must select at least one provider).	None
electricity_mix_zone	str	ISO 3166-1 alpha-3 code of the electricity mix zone (WOR by default).	'WOR'
opentelemetry_endpoint	str | None	enable OpenTelemetry with the URL endpoint.	None

Source code in ecologits/_ecologits.py

@staticmethod
def init(
    providers: str | list[str] | None = None,
    electricity_mix_zone: str = "WOR",
    opentelemetry_endpoint: str | None = None
) -> None:
    """
    Initialization static method. Will attempt to initialize all providers by default.

    Args:
        providers: list of providers to initialize (must select at least one provider).
        electricity_mix_zone: ISO 3166-1 alpha-3 code of the electricity mix zone (WOR by default).
        opentelemetry_endpoint: enable OpenTelemetry with the URL endpoint.
    """
    if isinstance(providers, str):
        providers = [providers]
    if providers is None:
        warnings.warn(
            "Initializing EcoLogits without defining providers will soon no longer be supported. For example "
            "with OpenAI, you should use `EcoLogits.init(providers=['openai'])` instead.",
            DeprecationWarning,
            stacklevel=2
        )

        providers = list(_INSTRUMENTS.keys())

    init_instruments(providers)

    EcoLogits.config.electricity_mix_zone = electricity_mix_zone
    EcoLogits.config.providers += providers
    EcoLogits.config.providers = list(set(EcoLogits.config.providers))

    if opentelemetry_endpoint is not None:
        if not is_opentelemetry_installed():
            logger.error("OpenTelemetry package is not installed. Install with "
                         "`pip install ecologits[opentelemetry]`.")
            raise EcoLogitsError("OpenTelemetry package is not installed.")

        from ecologits.utils.opentelemetry import OpenTelemetry

        EcoLogits.config.opentelemetry = OpenTelemetry(endpoint=opentelemetry_endpoint)

label(**labels) staticmethod

Create OpenTelemetry labels. Can be used as a context manager or as a function decorator.

Parameters:

Name	Type	Description	Default
**labels	str	Key-value pairs of OpenTelemetry labels.	{}

Returns:

Type	Description
OpenTelemetryLabels	OpenTelemetryLabels instance.

Examples:

Context manager usage:

with EcoLogits.label(task="summarization"):
    response = client.chat.completions.create(...)

# or in async mode
async with EcoLogits.label(task="summarization"):
    response = await async_client.chat.completions.create(...)

Decorator usage:

@EcoLogits.label(task="summarization")
def text_summarization(text: str) -> str:
    response = client.chat.completions.create(...)
    ...

# or in async mode
@EcoLogits.label(task="summarization")
async def text_summarization(text: str) -> str:
    response = await async_client.chat.completions.create(...)
    ...

Source code in ecologits/_ecologits.py

@staticmethod
def label(**labels: str) -> OpenTelemetryLabels:
    """
    Create OpenTelemetry labels. Can be used as a context manager or as a function decorator.

    Args:
        **labels: Key-value pairs of OpenTelemetry labels.

    Returns:
        OpenTelemetryLabels instance.

    Examples:
        Context manager usage:
        ```python
        with EcoLogits.label(task="summarization"):
            response = client.chat.completions.create(...)

        # or in async mode
        async with EcoLogits.label(task="summarization"):
            response = await async_client.chat.completions.create(...)
        ```

        Decorator usage:
        ```python
        @EcoLogits.label(task="summarization")
        def text_summarization(text: str) -> str:
            response = client.chat.completions.create(...)
            ...

        # or in async mode
        @EcoLogits.label(task="summarization")
        async def text_summarization(text: str) -> str:
            response = await async_client.chat.completions.create(...)
            ...
        ```
    """
    if EcoLogits.config.opentelemetry is None:
        logger.error("You must enable OpenTelemetry to use labels. Initialize with "
                     "opentelemetry_endpoint='http://localhost:4318/v1/metrics' for instance.")
        raise EcoLogitsError("OpenTelemetry is not enabled.")

    from ecologits.utils.opentelemetry import OpenTelemetryLabels

    return OpenTelemetryLabels(**labels)