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.
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
| :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
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.
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(),
)
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.
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)
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.
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")
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.
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="user@example.com",
organization="Example Organization, LLC",
)
client.register(user_registration)
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.
Join the conversation on Slack and Twitter!
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 fides@ethyca.com!
FAQs
The fideslog analytics collection mechanism
We found that fideslog demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.