Migas Client

A Python package to communicate with a migas server.

About

migas (mee-gahs) is a Python client to facilitate communication with a migas server.

Usage

To start communicating with a migas server, the client must first be setup.

import migas; migas.setup()

By default, migas-py will communicate with the official hosted migas server. However it can easily be configured to communicate with any hosted migas server.

import migas; migas.setup(endpoint='your-endpoint')

setup() will populate the internal configuration, which is done at the process level.

API

migas includes the following functions to communicate with the telemetry server:

migas.add_breadcrumb

---

Send a breadcrumb with usage information to the server.

Mandatory

• project - application name
• project_version - application version

Optional

• language (auto-detected)
• language_version (auto-detected)
• process:
  • status
  • status_desc
  • error_type
  • error_desc
• context:
  • user_id (auto-generated)
  • session_id
  • user_type
  • platform (auto-detected)
  • container (auto-detected)
  • is_ci (auto-detected)

add_breadcrumb example

>>> add_breadcrumb('nipreps/migas-py', '0.0.1', status='R', status_desc='Finished long step')
>>>

migas.check_project

---

Check a project version against later developments.

Mandatory

• project
• project_version

check_project example

>>> check_project('nipreps/migas-py', '0.0.1')
{'success': True, 'flagged': False, 'latest': '0.4.0', 'message': ''}

migas.get_usage

---

Check number of uses a project has received from a start date, and optionally an end date. If no end date is specified, the current datetime is used.

get_usage example

>>> get_usage('nipreps/migas-py', '2022-07-01')
{'hits': 7, 'message': '', 'unique': False, 'success': True}

migas.track

---

Begin tracking a process. This function can be used as a decorator (main function), context manager (recommended for tasks), or as a standalone function.

It automatically:

1. Sends an initial "Running" breadcrumb.
2. Registers an atexit handler to send a final breadcrumb on clean termination.
3. Installs signal handlers for SIGINT (Ctrl+C) and SIGTERM to send a final breadcrumb.
4. Supports framework-specific error parsing via error_handlers.

Note: migas.track() is idempotent per-project. If a tracker for the same project and version is already active (e.g., in a nested call), the existing instance is returned to avoid redundant telemetry.

Decorator

import yourpkg
import migas
migas.setup()

@migas.track("your/pkg", yourpkg.__version__)
def main():
    yourpkg.run()

Context Manager

import yourpkg
import migas
migas.setup()

with migas.track("your/pkg", yourpkg.__version__):
    # your code here
    yourpkg.run()

Exceptions raised within the block are captured and reported in the final breadcrumb.

Standalone

import yourpkg
import migas
migas.setup()

migas.track("your/pkg", yourpkg.__version__)

migas.track_exit (Deprecated)

---

Registers an exit function to send a final ping upon termination of the Python interpreter. Note: This function is deprecated in favor of migas.track().

migas.clear_user_id

---

Remove the persistent user identity file and reset the in-memory user ID. After calling this, the next setup() will generate a fresh user ID.

import migas
migas.clear_user_id()

User Control

User identity

To provide stable usage statistics across sessions and — on HPC systems — across nodes, migas derives a user ID from your username and hostname and saves it to:

~/.config/migas/user_id   # or $XDG_CONFIG_HOME/migas/user_id

This file contains only a UUID and no other personal information. It can be deleted at any time without affecting the tools that use migas. To remove it programmatically:

import migas
migas.clear_user_id()

Opting out

Setting MIGAS_OPTOUT disables all telemetry: no data is sent, no user ID is generated, and the persistent identity file is neither read nor written.

export MIGAS_OPTOUT=1

Environment variables

Envvar	Description	Value	Default
MIGAS_OPTOUT	Disable all telemetry	Any	None
MIGAS_TIMEOUT	Seconds to wait for server response	Number >= 0	5
MIGAS_LOG_LEVEL	Logger level	Logging levels	WARNING

Configuration

The internal configuration stores the following telemetry information:

• language and language version
• operating system
• run within a container
• run from continuous integration