telemetry

This module manages the telemetry system.

This function is used to setup the telemetry system on pyRevit startup

setup_telemetry()

These functions are used to query information about the logging system

get_telemetry_state()

get_apptelemetry_state()

This module also provides a wrapper class around the command results dictionary that is included with the telemetry record.

Scripts should use the instance of this class provided by the script module. See script.get_results() for examples

Attributes

FILE_LOG_EXT = 'json' module-attribute

FILE_LOG_FILENAME_TEMPLATE = '{}_{}_telemetry.{}' module-attribute

mlogger = get_logger(__name__) module-attribute

consts = PyRevit.PyRevitConsts module-attribute

Functions

get_default_telemetry_filepath()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_default_telemetry_filepath():
    return PYREVIT_VERSION_APP_DIR

get_telemetry_state()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_telemetry_state():
    return envvars.get_pyrevit_env_var(envvars.TELEMETRYSTATE_ENVVAR)

get_telemetry_utc_timestamp()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_telemetry_utc_timestamp():
    return envvars.get_pyrevit_env_var(envvars.TELEMETRYUTCTIMESTAMPS_ENVVAR)

get_telemetry_file_dir()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_telemetry_file_dir():
    return envvars.get_pyrevit_env_var(envvars.TELEMETRYDIR_ENVVAR)

get_telemetry_file_path()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_telemetry_file_path():
    return envvars.get_pyrevit_env_var(envvars.TELEMETRYFILE_ENVVAR)

get_telemetry_server_url()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_telemetry_server_url():
    return envvars.get_pyrevit_env_var(envvars.TELEMETRYSERVER_ENVVAR)

get_telemetry_include_hooks()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_telemetry_include_hooks():
    return envvars.get_pyrevit_env_var(envvars.TELEMETRYINCLUDEHOOKS_ENVVAR)

set_telemetry_state(state)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def set_telemetry_state(state):
    envvars.set_pyrevit_env_var(envvars.TELEMETRYSTATE_ENVVAR, state)
    user_config.telemetry_status = state

set_telemetry_utc_timestamp(state)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def set_telemetry_utc_timestamp(state):
    envvars.set_pyrevit_env_var(envvars.TELEMETRYUTCTIMESTAMPS_ENVVAR, state)
    user_config.telemetry_utc_timestamp = state

set_telemetry_file_dir(file_dir, persist=True)

Set telemetry file directory in env, optionally persisting to config.

Parameters:

Name	Type	Description	Default
file_dir	str	directory path to write telemetry files into	required
persist	bool	if True (default), write the value back to user_config and trigger a save. Pass False from setup_telemetry to avoid the redundant round-trip read-write cycle that previously fed the escape-doubling bug.	True

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def set_telemetry_file_dir(file_dir, persist=True):
    """Set telemetry file directory in env, optionally persisting to config.

    Args:
        file_dir (str): directory path to write telemetry files into
        persist (bool): if True (default), write the value back to
            user_config and trigger a save. Pass False from setup_telemetry
            to avoid the redundant round-trip read-write cycle that
            previously fed the escape-doubling bug.
    """
    if not file_dir or not op.isdir(file_dir):
        disable_telemetry_to_file()
    envvars.set_pyrevit_env_var(envvars.TELEMETRYDIR_ENVVAR, file_dir)
    if persist:
        user_config.telemetry_file_dir = file_dir

set_telemetry_file_path(file_path)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def set_telemetry_file_path(file_path):
    envvars.set_pyrevit_env_var(envvars.TELEMETRYFILE_ENVVAR, file_path)

set_telemetry_server_url(server_url, persist=True)

Set telemetry server URL in env, optionally persisting to config.

Parameters:

Name	Type	Description	Default
server_url	str	telemetry server URL	required
persist	bool	if True (default), write the value back to user_config and trigger a save. Pass False from setup_telemetry to avoid the redundant round-trip read-write cycle that previously fed the escape-doubling bug.	True

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def set_telemetry_server_url(server_url, persist=True):
    """Set telemetry server URL in env, optionally persisting to config.

    Args:
        server_url (str): telemetry server URL
        persist (bool): if True (default), write the value back to
            user_config and trigger a save. Pass False from setup_telemetry
            to avoid the redundant round-trip read-write cycle that
            previously fed the escape-doubling bug.
    """
    envvars.set_pyrevit_env_var(envvars.TELEMETRYSERVER_ENVVAR, server_url)
    if persist:
        user_config.telemetry_server_url = server_url

set_telemetry_include_hooks(state)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def set_telemetry_include_hooks(state):
    envvars.set_pyrevit_env_var(envvars.TELEMETRYINCLUDEHOOKS_ENVVAR, state)
    user_config.telemetry_include_hooks = state

disable_telemetry()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def disable_telemetry():
    set_telemetry_state(False)

disable_telemetry_to_file()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def disable_telemetry_to_file():
    set_telemetry_file_path('')

disable_telemetry_to_server()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def disable_telemetry_to_server():
    set_telemetry_server_url('')

get_apptelemetry_state()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_apptelemetry_state():
    return envvars.get_pyrevit_env_var(envvars.APPTELEMETRYSTATE_ENVVAR)

set_apptelemetry_state(state)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def set_apptelemetry_state(state):
    envvars.set_pyrevit_env_var(envvars.APPTELEMETRYSTATE_ENVVAR, state)
    user_config.apptelemetry_status = state

get_apptelemetry_handler()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_apptelemetry_handler():
    return envvars.get_pyrevit_env_var(envvars.APPTELEMETRYHANDLER_ENVVAR)

set_apptelemetry_handler(handler)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def set_apptelemetry_handler(handler):
    envvars.set_pyrevit_env_var(envvars.APPTELEMETRYHANDLER_ENVVAR, handler)

get_apptelemetry_server_url()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_apptelemetry_server_url():
    return envvars.get_pyrevit_env_var(envvars.APPTELEMETRYSERVER_ENVVAR)

get_apptelemetry_event_flags()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_apptelemetry_event_flags():
    # default value is 16 bytes of 0
    flags_hex = \
        user_config.apptelemetry_event_flags or '0x00000000000000000000000000000000'
    return coreutils.hex2int_long(flags_hex)

set_apptelemetry_server_url(server_url, persist=True)

Set app telemetry server URL in env, optionally persisting to config.

Parameters:

Name	Type	Description	Default
server_url	str	app telemetry server URL	required
persist	bool	if True (default), write the value back to user_config and trigger a save. Pass False from setup_telemetry to avoid the redundant round-trip read-write cycle that previously fed the escape-doubling bug.	True

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def set_apptelemetry_server_url(server_url, persist=True):
    """Set app telemetry server URL in env, optionally persisting to config.

    Args:
        server_url (str): app telemetry server URL
        persist (bool): if True (default), write the value back to
            user_config and trigger a save. Pass False from setup_telemetry
            to avoid the redundant round-trip read-write cycle that
            previously fed the escape-doubling bug.
    """
    envvars.set_pyrevit_env_var(envvars.APPTELEMETRYSERVER_ENVVAR, server_url)
    if persist:
        user_config.apptelemetry_server_url = server_url

set_apptelemetry_event_flags(event_flags)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def set_apptelemetry_event_flags(event_flags):
    flags_hex = coreutils.int2hex_long(event_flags)
    user_config.apptelemetry_event_flags = flags_hex
    envvars.set_pyrevit_env_var(
        envvars.APPTELEMETRYEVENTFLAGS_ENVVAR, flags_hex)

disable_apptelemetry()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def disable_apptelemetry():
    set_apptelemetry_state(False)

disable_apptelemetry_to_server()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def disable_apptelemetry_to_server():
    set_apptelemetry_server_url('')

get_apptelemetry_event_types()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_apptelemetry_event_types():
    return list(coreutils.get_enum_values(EventType))

get_apptelemetry_event_state(flags, event_type)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_apptelemetry_event_state(flags, event_type):
    event_idx = get_apptelemetry_event_types().index(event_type)
    return flags & (1<<event_idx)

set_apptelemetry_event_state(flags, event_type)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def set_apptelemetry_event_state(flags, event_type):
    return flags | (1<<int(event_type))

unset_apptelemetry_event_state(flags, event_type)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def unset_apptelemetry_event_state(flags, event_type):
    return flags & ~(1<<int(event_type))

get_status_from_url(server_url)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_status_from_url(server_url):
    server_url = server_url.lower()
    if server_url.endswith('scripts/'):
        server_url = server_url.replace('scripts/', 'status')
    elif server_url.endswith('events/'):
        server_url = server_url.replace('events/', 'status')

    try:
        return json.loads(urlopen(server_url).read())
    except Exception:
        return None

get_status()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def get_status():
    return get_status_from_url(
        get_telemetry_server_url()
        or get_apptelemetry_server_url()
        )

setup_telemetry(session_id=None)

Sets up the telemetry default config and environment values.

Source code in pyrevitlib/pyrevit/telemetry/__init__.py

def setup_telemetry(session_id=None):
    """Sets up the telemetry default config and environment values."""
    # make sure session id is availabe
    if not session_id:
        session_id = sessioninfo.get_session_uuid()

    # PYREVIT TELEMETRY -------------------------------------------------------
    # utc timestamp
    telemetry_utc_timestamp = user_config.telemetry_utc_timestamp
    set_telemetry_utc_timestamp(telemetry_utc_timestamp)

    # global telemetry toggle
    telemetry_state = user_config.telemetry_status
    set_telemetry_state(telemetry_state)

    # read or setup default values for file telemetry
    # default file path and name for telemetry
    telemetry_file_dir = user_config.telemetry_file_dir
    # persist=False: this is a startup-time push from user_config to env,
    # not a value change. Avoids redundant round-trip writes that
    # previously fed the escape-doubling bug.
    set_telemetry_file_dir(telemetry_file_dir, persist=False)

    # check file telemetry config and setup destination
    if not telemetry_file_dir or coreutils.is_blank(telemetry_file_dir):
        # if no config is provided, disable output
        disable_telemetry_to_file()
    # if config exists, create new telemetry file under the same address
    elif telemetry_state:
        if op.isdir(telemetry_file_dir):
            telemetry_file_name = \
                FILE_LOG_FILENAME_TEMPLATE.format(PYREVIT_FILE_PREFIX,
                                                  session_id,
                                                  FILE_LOG_EXT)
            # if directory is valid
            telemetry_fullfilepath = \
                op.join(telemetry_file_dir, telemetry_file_name)
            set_telemetry_file_path(telemetry_fullfilepath)
            # setup telemetry file or disable if failed
            try:
                _setup_default_logfile(telemetry_fullfilepath)
            except Exception as write_err:
                mlogger.error('Telemetry is active but log file location '
                              'is not accessible. | %s', write_err)
                disable_telemetry_to_file()
        else:
            # if not, show error and disable telemetry
            mlogger.error('Provided telemetry address does not exits or is '
                          'not a directory. Telemetry disabled.')
            disable_telemetry_to_file()

    # read or setup default values for server telemetry
    telemetry_server_url = user_config.telemetry_server_url

    # check server telemetry config and setup destination
    if not telemetry_server_url or coreutils.is_blank(telemetry_server_url):
        # if no config is provided, disable output
        disable_telemetry_to_server()
    else:
        # if config exists, setup server logging
        # persist=False: pure startup-time push from user_config to env.
        set_telemetry_server_url(telemetry_server_url, persist=False)

    # set telemetry script types
    set_telemetry_include_hooks(user_config.telemetry_include_hooks)

    # APP TELEMETRY ------------------------------------------------------------
    # setup default value for telemetry global switch
    apptelemetry_state = user_config.apptelemetry_status
    set_apptelemetry_state(apptelemetry_state)

    # read or setup default values for server telemetry
    apptelemetry_server_url = user_config.apptelemetry_server_url

    # check server telemetry config and setup destination
    if not apptelemetry_server_url \
            or coreutils.is_blank(apptelemetry_server_url):
        # if no config is provided, disable output
        disable_apptelemetry_to_server()
    else:
        # if config exists, setup server logging
        # persist=False: pure startup-time push from user_config to env.
        set_apptelemetry_server_url(apptelemetry_server_url, persist=False)

    # setup events
    new_telemetry_handler = EventTelemetry(session_id, HOST_APP.username)
    telemetry_handler = get_apptelemetry_handler()
    if telemetry_handler:
        # clear existing
        telemetry_events.unregister_all_event_telemetries(telemetry_handler)

    set_apptelemetry_handler(new_telemetry_handler)
    # register handlers only if telemetry system is active
    if apptelemetry_state:
        apptelemetry_event_flags = get_apptelemetry_event_flags()
        # re-register events with new telemetry_handler
        telemetry_events.register_event_telemetry(
            new_telemetry_handler,
            apptelemetry_event_flags
        )

    user_config.save_changes()