AsyncMetrics

Bases: AsyncBaseRoute

A class for interacting with the Outline VPN server's metrics API asynchronously.

Provides methods to check whether metrics collection is enabled, toggle it, retrieve per-key data transfer statistics, and fetch detailed experimental server metrics.

Parameters:

Name	Type	Description	Default
management_url	str	The management URL used to communicate with the Outline server API.	required
ssl_verify	bool	Flag to enable or disable SSL certificate verification. Default is False.	False

Source code in outline_vpn_api_client/async_client.py

class AsyncMetrics(AsyncBaseRoute):
    """
    A class for interacting with the Outline VPN server's metrics API asynchronously.

    Provides methods to check whether metrics collection is enabled, toggle it,
    retrieve per-key data transfer statistics, and fetch detailed experimental server metrics.

    Args:
        management_url (str): The management URL used to communicate with the Outline server API.
        ssl_verify (bool, optional): Flag to enable or disable SSL certificate verification. Default is False.
    """

    def __init__(self, management_url, ssl_verify=False):
        super().__init__(management_url, ssl_verify)
        self.base_url = f"{self.base_url}/metrics"

    async def check_enabled(self) -> bool:
        """
        Returns whether metrics collection is enabled on the Outline VPN server.

        Returns:
            bool: True if metrics collection is enabled, False otherwise.

        Raises:
            ResponseNotOkException: If the server response indicates an error (status code >= 300).
        """
        async with httpx.AsyncClient(verify=self.ssl_verify) as client:
            response = await client.get(f"{self.base_url}/enabled")
            response_json = response.json()
            _check_response(response, response_json)
        return response_json.get("metricsEnabled")

    async def change_enabled_state(self, state: bool = False) -> bool:
        """
        Enables or disables the sharing of metrics on the Outline VPN server.

        Args:
            state (bool): True to enable metrics sharing, False to disable. Default is False.

        Returns:
            bool: True if the metrics sharing state was successfully updated.

        Raises:
            ResponseNotOkException: If the server response indicates an error (status code >= 300).
        """
        data = {"metricsEnabled": state}
        async with httpx.AsyncClient(verify=self.ssl_verify) as client:
            response = await client.put(f"{self.base_url}/enabled", json=data)
            _check_response(response)
        return True

    async def get_data_transfer(self) -> models.BytesTransferredByUserId:
        """
        Returns the data transferred per access key on the Outline VPN server.

        Returns:
            models.BytesTransferredByUserId: Data transfer information for each access key.

        Raises:
            ResponseNotOkException: If the server response indicates an error (status code >= 300).
        """
        async with httpx.AsyncClient(verify=self.ssl_verify) as client:
            response = await client.get(f"{self.base_url}/transfer")
            response_json = response.json()
            _check_response(response, response_json)
        return models.BytesTransferredByUserId.model_validate(response_json)

    async def get_server_metrics(self, since: datetime) -> models.ServerMetrics:
        """
        Returns detailed server metrics including tunnel time, data transferred,
        bandwidth, locations, and per-access-key statistics.

        This is an experimental endpoint (`GET /experimental/server/metrics`).
        Note: the endpoint and its response format may change in future server versions.

        !!! warning "Experimental endpoint"
            This method uses `GET /experimental/server/metrics`, which is an unstable
            endpoint. Its availability and response format may change or break across
            different Outline server versions. Use with caution in production.

        Note:
            This endpoint requires metrics sharing to be enabled on the server
            (`client.metrics.change_enabled_state(True)`). It will return an error
            if metrics are disabled.

        Args:
            since (datetime): The start of the time range for which to return metrics.

        Returns:
            models.ServerMetrics: Detailed server and per-key metrics.

        Raises:
            ResponseNotOkException: If the server response indicates an error (status code >= 300).

        Example:
            ```python
            from datetime import datetime, timezone, timedelta

            metrics = await client.metrics.get_server_metrics(
                since=datetime.now(timezone.utc) - timedelta(days=30)
            )
            print(metrics.server.dataTransferred.bytes)
            ```
        """
        since_str = since.strftime("%Y-%m-%dT%H:%M:%SZ")
        base = self.base_url.replace("/metrics", "")
        async with httpx.AsyncClient(verify=self.ssl_verify) as client:
            response = await client.get(
                f"{base}/experimental/server/metrics",
                params={"since": since_str},
            )
            response_json = response.json()
            _check_response(response, response_json)
        return models.ServerMetrics.model_validate(response_json)

    def __str__(self):
        return json.dumps({"info": "AsyncMetrics object for managing server metrics"}, ensure_ascii=False)

change_enabled_state(state=False) async

Enables or disables the sharing of metrics on the Outline VPN server.

Parameters:

Name	Type	Description	Default
state	bool	True to enable metrics sharing, False to disable. Default is False.	False

Returns:

Name	Type	Description
bool	bool	True if the metrics sharing state was successfully updated.

Raises:

Type	Description
ResponseNotOkException	If the server response indicates an error (status code >= 300).

Source code in outline_vpn_api_client/async_client.py

async def change_enabled_state(self, state: bool = False) -> bool:
    """
    Enables or disables the sharing of metrics on the Outline VPN server.

    Args:
        state (bool): True to enable metrics sharing, False to disable. Default is False.

    Returns:
        bool: True if the metrics sharing state was successfully updated.

    Raises:
        ResponseNotOkException: If the server response indicates an error (status code >= 300).
    """
    data = {"metricsEnabled": state}
    async with httpx.AsyncClient(verify=self.ssl_verify) as client:
        response = await client.put(f"{self.base_url}/enabled", json=data)
        _check_response(response)
    return True

check_enabled() async

Returns whether metrics collection is enabled on the Outline VPN server.

Returns:

Name	Type	Description
bool	bool	True if metrics collection is enabled, False otherwise.

Raises:

Type	Description
ResponseNotOkException	If the server response indicates an error (status code >= 300).

Source code in outline_vpn_api_client/async_client.py

async def check_enabled(self) -> bool:
    """
    Returns whether metrics collection is enabled on the Outline VPN server.

    Returns:
        bool: True if metrics collection is enabled, False otherwise.

    Raises:
        ResponseNotOkException: If the server response indicates an error (status code >= 300).
    """
    async with httpx.AsyncClient(verify=self.ssl_verify) as client:
        response = await client.get(f"{self.base_url}/enabled")
        response_json = response.json()
        _check_response(response, response_json)
    return response_json.get("metricsEnabled")

get_data_transfer() async

Returns the data transferred per access key on the Outline VPN server.

Returns:

Type	Description
BytesTransferredByUserId	models.BytesTransferredByUserId: Data transfer information for each access key.

Raises:

Type	Description
ResponseNotOkException	If the server response indicates an error (status code >= 300).

Source code in outline_vpn_api_client/async_client.py

async def get_data_transfer(self) -> models.BytesTransferredByUserId:
    """
    Returns the data transferred per access key on the Outline VPN server.

    Returns:
        models.BytesTransferredByUserId: Data transfer information for each access key.

    Raises:
        ResponseNotOkException: If the server response indicates an error (status code >= 300).
    """
    async with httpx.AsyncClient(verify=self.ssl_verify) as client:
        response = await client.get(f"{self.base_url}/transfer")
        response_json = response.json()
        _check_response(response, response_json)
    return models.BytesTransferredByUserId.model_validate(response_json)

get_server_metrics(since) async

Returns detailed server metrics including tunnel time, data transferred, bandwidth, locations, and per-access-key statistics.

This is an experimental endpoint (GET /experimental/server/metrics). Note: the endpoint and its response format may change in future server versions.

!!! warning "Experimental endpoint" This method uses GET /experimental/server/metrics, which is an unstable endpoint. Its availability and response format may change or break across different Outline server versions. Use with caution in production.

Note

This endpoint requires metrics sharing to be enabled on the server (client.metrics.change_enabled_state(True)). It will return an error if metrics are disabled.

Parameters:

Name	Type	Description	Default
since	datetime	The start of the time range for which to return metrics.	required

Returns:

Type	Description
ServerMetrics	models.ServerMetrics: Detailed server and per-key metrics.

Raises:

Type	Description
ResponseNotOkException	If the server response indicates an error (status code >= 300).

Example

from datetime import datetime, timezone, timedelta

metrics = await client.metrics.get_server_metrics(
    since=datetime.now(timezone.utc) - timedelta(days=30)
)
print(metrics.server.dataTransferred.bytes)

Source code in outline_vpn_api_client/async_client.py

async def get_server_metrics(self, since: datetime) -> models.ServerMetrics:
    """
    Returns detailed server metrics including tunnel time, data transferred,
    bandwidth, locations, and per-access-key statistics.

    This is an experimental endpoint (`GET /experimental/server/metrics`).
    Note: the endpoint and its response format may change in future server versions.

    !!! warning "Experimental endpoint"
        This method uses `GET /experimental/server/metrics`, which is an unstable
        endpoint. Its availability and response format may change or break across
        different Outline server versions. Use with caution in production.

    Note:
        This endpoint requires metrics sharing to be enabled on the server
        (`client.metrics.change_enabled_state(True)`). It will return an error
        if metrics are disabled.

    Args:
        since (datetime): The start of the time range for which to return metrics.

    Returns:
        models.ServerMetrics: Detailed server and per-key metrics.

    Raises:
        ResponseNotOkException: If the server response indicates an error (status code >= 300).

    Example:
        ```python
        from datetime import datetime, timezone, timedelta

        metrics = await client.metrics.get_server_metrics(
            since=datetime.now(timezone.utc) - timedelta(days=30)
        )
        print(metrics.server.dataTransferred.bytes)
        ```
    """
    since_str = since.strftime("%Y-%m-%dT%H:%M:%SZ")
    base = self.base_url.replace("/metrics", "")
    async with httpx.AsyncClient(verify=self.ssl_verify) as client:
        response = await client.get(
            f"{base}/experimental/server/metrics",
            params={"since": since_str},
        )
        response_json = response.json()
        _check_response(response, response_json)
    return models.ServerMetrics.model_validate(response_json)

Note on get_server_metrics

The get_server_metrics method uses the GET /experimental/server/metrics endpoint, which is experimental and may be unstable or unavailable depending on your Outline server version.

Requirements:

• Metrics sharing must be enabled: await client.metrics.change_enabled_state(True)
• The endpoint behavior and response format may change without notice in future server releases