fideslog 1.2.11

The fideslog analytics collection mechanism

Fideslog: Python SDK

Overview

Fideslog is the API server, developer SDK, and supporting infrastructure intended to provide Ethyca with an understanding of user interactions with fides tooling. Analytics are only used either as a factor in Ethyca's internal product roadmap determination process, or as insight into product adoption. Information collected by fideslog is received via HTTPs request, stored in a secure database, and never shared with third parties for any reason unless required by law.

This library is the recommended means by which to automate the submission of analytics data to the fideslog API server from a Python application.

Installation

Install the fideslog Python SDK using a package manager. It is available via PyPI. For a complete list of available release versions and their associated release notes, see the Releases tab in the repository.

pip install fideslog

Usage

Establishing User Consent

:memo: Note	See Ethyca's guidelines for establishing user consent for a list of requirements for collecting analytics.

It is recommended to display the content of the OPT_OUT_COPY constant exposed by the utils.py file as a means of informing users of the application's intent to collect analytics data as early as possible within the usage workflow of the application. If the application uses a CLI interface, the content of the OPT_OUT_PROMPT constant (also exposed by the utils.py file) can be displayed to collect explicit consent.

If the application is stateful, store the user's response within the top-level state-maintaining mechanism.

If the application is stateless, store the user's response within the application's configuration. If the application is configured with a TOML file, it is recommended to enable a [user] section, and store the consent within an analytics_opt_out configuration option. For example:

[user]
analytics_opt_out = false

Identifying the Sending Application

The SDK exposes an AnalyticsClient class from the client.py file. Ideally only a single instance of AnalyticsClient will be necessary to establish the application-level details of all analytics event data emitted by the application.

The utils.py file exposes the generate_client_id() function, which should be used only once per application instance in order to safely generate a fully anonymized, globally unique identifier. For stateless applications, it is recommended to store this value in an analytics_id configuration option, or in an instance-specific database.

Example

from platform import system

from fideslog.sdk.python.client import AnalyticsClient
from fideslog.sdk.python.utils import generate_client_id

CLIENT_ID: str = generate_client_id(b"a_fides_tool")  # utils.py also exposes some helpful bytestrings


def get_version() -> str:
    return "1.0.0"

def in_developer_mode() -> bool:
    return False

client = AnalyticsClient(
    client_id=CLIENT_ID,
    developer_mode=in_developer_mode(),
    extra_data={
        "this data": "will be included with every event sent by this client",
        "include": "any context that every event requires",
        "never include": "identifying information of any kind",
    },
    os=system(),
    product_name="a_fides_tool",
    production_version=get_version(),
)

Sending Analytics Data

The SDK exposes an AnalyticsEvent class from the event.py file. Create a new instance of AnalyticsEvent for every discrete event that should be persisted. Then, use the AnalyticsClient.send() method to make a request to the fideslog API server and persist the event.

Example

Building on the example from the previous section:

from datetime import datetime, timezone
from platform import system

from fideslog.sdk.python.client import AnalyticsClient
from fideslog.sdk.python.event import AnalyticsEvent
from fideslog.sdk.python.utils import generate_client_id

CLIENT_ID: str = generate_client_id(b"a_fides_tool")  # utils.py exposes some helpful bytestrings


def get_version() -> str:
    return "1.0.0"

def in_developer_mode() -> bool:
    return False

def in_docker_container() -> bool:
    return True

def running_on_local_host() -> bool:
    return False

client = AnalyticsClient(
    client_id=CLIENT_ID,
    developer_mode=in_developer_mode(),
    extra_data={
        "this data": "will be included with every event sent by this client",
        "include": "any context that every event requires",
        "never include": "identifying information of any kind",
    },
    os=system(),
    product_name="a_fides_tool",
    production_version=get_version(),
)

cli_command_event = AnalyticsEvent(
    command="cli_command_name sub_command_name",
    docker=in_docker_container(),
    event="cli_command_executed",
    error=None,
    event_created_at=datetime.now(tz=timezone.utc),
    extra_data={
        "this data": "will be included only on this event",
        "it will": "overwrite keys included in the client's extra_data",
        "include": "any context that this event requires",
        "never include": "identifying information of any kind",
    },
    flags=["--dry", "-v"],
    local_host=running_on_local_host(),
    resource_counts={
        "datasets": 7,
        "policies": 26,
        "systems": 9,
    },
    status_code=0,
)

client.send(cli_command_event)

Handling Exceptions

The SDK exposes an AnalyticsError type from the exceptions.py file. In the event that an exception is raised by this library, it will either be a literal AnalyticsError, or inherit from AnalyticsError. In general, it is not recommended to raise these exceptions within application code, to prevent breaking the application and/or user workflow; these exceptions are intended to be written to log output, and otherwise ignored.

Example

Building on the example from the previous section:

from datetime import datetime, timezone
from platform import system

from fideslog.sdk.python.client import AnalyticsClient
from fideslog.sdk.python.event import AnalyticsEvent
from fideslog.sdk.python.exceptions import AnalyticsError
from fideslog.sdk.python.utils import generate_client_id

CLIENT_ID: str = generate_client_id(b"a_fides_tool")  # utils.py exposes some helpful bytestrings


def get_version() -> str:
    return "1.0.0"

def in_developer_mode() -> bool:
    return False

def in_docker_container() -> bool:
    return True

def running_on_local_host() -> bool:
    return False

try:
    client = AnalyticsClient(
        client_id=CLIENT_ID,
        developer_mode=in_developer_mode(),
        extra_data={
            "this data": "will be included with every event sent by this client",
            "include": "any context that every event requires",
            "never include": "identifying information of any kind",
        },
        os=system(),
        product_name="a_fides_tool",
        production_version=get_version(),
    )

    cli_command_event = AnalyticsEvent(
        command="cli_command_name sub_command_name",
        docker=in_docker_container(),
        event="cli_command_executed",
        error=None,
        event_created_at=datetime.now(tz=timezone.utc),
        extra_data={
            "this data": "will be included only on this event",
            "it will": "overwrite keys included in the client's extra_data",
            "include": "any context that this event requires",
            "never include": "identifying information of any kind",
        },
        flags=["--dry", "-v"],
        local_host=running_on_local_host(),
        resource_counts={
            "datasets": 7,
            "policies": 26,
            "systems": 9,
        },
        status_code=0,
    )

    client.send(cli_command_event)

except AnalyticsError as err:   # It is not recommended to raise this exception,
    print(err)                  # to prevent interrupting the application workflow.
else:
    print("Analytics event sent")

Registering Users

The SDK exposes a Registration class from the registration.py file. Create a new instance of Registration for every user that should be registered. Then, use the AnalyticsClient.register() method to make a request to the fideslog API server and register the user.

Example

Building on the example from a previous section:

from platform import system

from fideslog.sdk.python.client import AnalyticsClient
from fideslog.sdk.python.registration import Registration
from fideslog.sdk.python.utils import generate_client_id

CLIENT_ID: str = generate_client_id(b"a_fides_tool")  # utils.py exposes some helpful bytestrings


def get_version() -> str:
    return "1.0.0"

def in_developer_mode() -> bool:
    return False

client = AnalyticsClient(
    client_id=CLIENT_ID,
    developer_mode=in_developer_mode(),
    extra_data={
        "this data": "will be included with every event sent by this client",
        "include": "any context that every event requires",
        "never include": "identifying information of any kind",
    },
    os=system(),
    product_name="a_fides_tool",
    production_version=get_version(),
)

user_registration = Registration(
    email="[e-mail]",
    organization="Example Organization, LLC",
)

client.register(user_registration)

Contributing

We welcome and encourage all types of contributions and improvements! Please see our contribution guide to opening issues for bugs, new features, and security or experience enhancements.

Read about the Fides community or dive into the development guides for information about contributions, documentation, code style, testing and more. Ethyca is committed to fostering a safe and collaborative environment, such that all interactions are governed by the Fides Code of Conduct.

Support

Join the conversation on Slack and Twitter!

License

Fideslog and the fides ecosystem of tools are licensed under the Apache Software License Version 2.0. Fides tools are built on fideslang, the fides language specification, which is licensed under CC by 4.

Fides is created and sponsored by Ethyca: a developer tools company building the trust infrastructure of the internet. If you have questions or need assistance getting started, let us know at [e-mail]!