Metrics

Bases: BaseRoute

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

This class provides methods to retrieve and check the status of various server metrics. It allows you to determine whether metrics collection is enabled on the server.

Attributes:

Name	Type	Description
base_url	str	The base URL for the metrics endpoint of the Outline server, formed by appending "/metrics" to the management URL.

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 for API requests. Default is False. You should set this flag to False if the server's SSL certificate is self-signed or if no certificate is present.	False

Source code in outline_vpn_api_client/client.py

class Metrics(BaseRoute):
    """
    A class for interacting with the Outline VPN server's metrics API.

    This class provides methods to retrieve and check the status of various server metrics. It allows you to determine
    whether metrics collection is enabled on the server.

    Attributes:
        base_url (str): The base URL for the metrics endpoint of the Outline server, formed by appending "/metrics"
                        to the management URL.

    Args:
        management_url (str): The management URL used to communicate with the Outline server API.
        ssl_verify (bool): Flag to enable or disable SSL certificate verification for API requests. Default is `False`.
                        You should set this flag to `False` if the server's SSL certificate is self-signed or if no certificate is present.
    """
    def __init__(self, management_url, ssl_verify = False):
        super().__init__(management_url, ssl_verify)
        self.base_url = f"{self.base_url}/metrics"

    def __str__(self):
        return json.dumps({'enabled': self.check_enabled()}, ensure_ascii=False, indent=4)

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

        This method sends a request to the server to check if metrics sharing is currently enabled. 
        It parses the response to determine whether metrics are being shared and returns a boolean indicating the status.

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

        Raises:
            ResponseNotOkException: If the server responds with a status code indicating an error (status code >= 300).
        """
        response = requests.get(f"{self.base_url}/enabled", verify=self.ssl_verify)
        response_json: dict = response.json()
        _check_response(response)
        return response_json.get("metricsEnabled")

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

        This method allows you to enable or disable the sharing of metrics. It sends a request to the server to update 
        the state of metrics sharing based on the provided `state` parameter.

        Args:
            state (bool): A boolean indicating whether to enable (`True`) or disable (`False`) metrics sharing. Default is `False`.

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

        Raises:
            ResponseNotOkException: If the server responds with a status code indicating an error (status code >= 300).
        """
        data = {
            "metricsEnabled": state
        }
        response = requests.put(f"{self.base_url}/enabled", json=data, verify=self.ssl_verify)
        _check_response(response)
        return True

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

        This method retrieves information about the amount of data transferred for each access key.
        It sends a request to the server to fetch the data transfer details and returns a dictionary containing 
        the transfer data.

        Returns:
            dict: A dictionary containing data transfer information for each access key.

            The returned dictionary contains the following format:
            {
                "bytesTransferredByUserId": {
                    "user_id_1": data_in_bytes,
                    "user_id_2": data_in_bytes,
                    ...
                }
            }

            Where `user_id_1`, `user_id_2`, etc. are the access key IDs (user IDs), and `data_in_bytes` represents 
            the amount of data transferred by the corresponding access key in bytes.

        Raises:
            ResponseNotOkException: If the server responds with a status code indicating an error (status code >= 300).
        """
        response = requests.get(f"{self.base_url}/transfer", verify=self.ssl_verify)
        response_json = response.json()
        _check_response(response, response_json)
        return models.BytesTransferredByUserId.model_validate(response_json)

    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.

        !!! 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 responds with a status code indicating an error (status code >= 300).

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

            metrics = 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", "")
        response = requests.get(
            f"{base}/experimental/server/metrics",
            params={"since": since_str},
            verify=self.ssl_verify,
        )
        response_json = response.json()
        _check_response(response, response_json)
        return models.ServerMetrics.model_validate(response_json)

change_enabled_state(state=False)

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

This method allows you to enable or disable the sharing of metrics. It sends a request to the server to update the state of metrics sharing based on the provided state parameter.

Parameters:

Name	Type	Description	Default
state	bool	A boolean indicating whether to enable (True) or disable (False) metrics sharing. 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 responds with a status code indicating an error (status code >= 300).

Source code in outline_vpn_api_client/client.py

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

    This method allows you to enable or disable the sharing of metrics. It sends a request to the server to update 
    the state of metrics sharing based on the provided `state` parameter.

    Args:
        state (bool): A boolean indicating whether to enable (`True`) or disable (`False`) metrics sharing. Default is `False`.

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

    Raises:
        ResponseNotOkException: If the server responds with a status code indicating an error (status code >= 300).
    """
    data = {
        "metricsEnabled": state
    }
    response = requests.put(f"{self.base_url}/enabled", json=data, verify=self.ssl_verify)
    _check_response(response)
    return True

check_enabled()

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

This method sends a request to the server to check if metrics sharing is currently enabled. It parses the response to determine whether metrics are being shared and returns a boolean indicating the status.

Returns:

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

Raises:

Type	Description
ResponseNotOkException	If the server responds with a status code indicating an error (status code >= 300).

Source code in outline_vpn_api_client/client.py

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

    This method sends a request to the server to check if metrics sharing is currently enabled. 
    It parses the response to determine whether metrics are being shared and returns a boolean indicating the status.

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

    Raises:
        ResponseNotOkException: If the server responds with a status code indicating an error (status code >= 300).
    """
    response = requests.get(f"{self.base_url}/enabled", verify=self.ssl_verify)
    response_json: dict = response.json()
    _check_response(response)
    return response_json.get("metricsEnabled")

get_data_transfer()

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

This method retrieves information about the amount of data transferred for each access key. It sends a request to the server to fetch the data transfer details and returns a dictionary containing the transfer data.

Returns:

Name	Type	Description
dict	BytesTransferredByUserId	A dictionary containing data transfer information for each access key.
	BytesTransferredByUserId	The returned dictionary contains the following format:
	BytesTransferredByUserId	{ "bytesTransferredByUserId": { "user_id_1": data_in_bytes, "user_id_2": data_in_bytes, ... }
	BytesTransferredByUserId	}
	BytesTransferredByUserId	Where user_id_1, user_id_2, etc. are the access key IDs (user IDs), and data_in_bytes represents
	BytesTransferredByUserId	the amount of data transferred by the corresponding access key in bytes.

Raises:

Type	Description
ResponseNotOkException	If the server responds with a status code indicating an error (status code >= 300).

Source code in outline_vpn_api_client/client.py

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

    This method retrieves information about the amount of data transferred for each access key.
    It sends a request to the server to fetch the data transfer details and returns a dictionary containing 
    the transfer data.

    Returns:
        dict: A dictionary containing data transfer information for each access key.

        The returned dictionary contains the following format:
        {
            "bytesTransferredByUserId": {
                "user_id_1": data_in_bytes,
                "user_id_2": data_in_bytes,
                ...
            }
        }

        Where `user_id_1`, `user_id_2`, etc. are the access key IDs (user IDs), and `data_in_bytes` represents 
        the amount of data transferred by the corresponding access key in bytes.

    Raises:
        ResponseNotOkException: If the server responds with a status code indicating an error (status code >= 300).
    """
    response = requests.get(f"{self.base_url}/transfer", verify=self.ssl_verify)
    response_json = response.json()
    _check_response(response, response_json)
    return models.BytesTransferredByUserId.model_validate(response_json)

get_server_metrics(since)

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

!!! 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 responds with a status code indicating an error (status code >= 300).

Example

from datetime import datetime, timezone, timedelta

metrics = 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/client.py

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.

    !!! 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 responds with a status code indicating an error (status code >= 300).

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

        metrics = 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", "")
    response = requests.get(
        f"{base}/experimental/server/metrics",
        params={"since": since_str},
        verify=self.ssl_verify,
    )
    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: client.metrics.change_enabled_state(True)
• The endpoint behavior and response format may change without notice in future server releases