Skip to content

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 
53
54
def get_default_telemetry_filepath():
    return PYREVIT_VERSION_APP_DIR

get_telemetry_state()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py 
57
58
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 
61
62
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 
65
66
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 
69
70
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 
73
74
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 
77
78
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 
81
82
83
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 
86
87
88
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)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py 
91
92
93
94
95
def set_telemetry_file_dir(file_dir):
    if not file_dir or not op.isdir(file_dir):
        disable_telemetry_to_file()
    envvars.set_pyrevit_env_var(envvars.TELEMETRYDIR_ENVVAR, file_dir)
    user_config.telemetry_file_dir = file_dir

set_telemetry_file_path(file_path)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py 
98
99
def set_telemetry_file_path(file_path):
    envvars.set_pyrevit_env_var(envvars.TELEMETRYFILE_ENVVAR, file_path)

set_telemetry_server_url(server_url)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py 
102
103
104
def set_telemetry_server_url(server_url):
    envvars.set_pyrevit_env_var(envvars.TELEMETRYSERVER_ENVVAR, server_url)
    user_config.telemetry_server_url = server_url

set_telemetry_include_hooks(state)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py 
107
108
109
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 
112
113
def disable_telemetry():
    set_telemetry_state(False)

disable_telemetry_to_file()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py 
116
117
def disable_telemetry_to_file():
    set_telemetry_file_path('')

disable_telemetry_to_server()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py 
120
121
def disable_telemetry_to_server():
    set_telemetry_server_url('')

get_apptelemetry_state()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py 
124
125
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 
128
129
130
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 
133
134
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 
137
138
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 
141
142
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 
145
146
147
148
149
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)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py 
152
153
154
def set_apptelemetry_server_url(server_url):
    envvars.set_pyrevit_env_var(envvars.APPTELEMETRYSERVER_ENVVAR, server_url)
    user_config.apptelemetry_server_url = server_url

set_apptelemetry_event_flags(event_flags)

Source code in pyrevitlib/pyrevit/telemetry/__init__.py 
157
158
159
160
161
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 
164
165
def disable_apptelemetry():
    set_apptelemetry_state(False)

disable_apptelemetry_to_server()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py 
168
169
def disable_apptelemetry_to_server():
    set_apptelemetry_server_url('')

get_apptelemetry_event_types()

Source code in pyrevitlib/pyrevit/telemetry/__init__.py 
172
173
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 
176
177
178
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 
181
182
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 
185
186
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 
197
198
199
200
201
202
203
204
205
206
207
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 
210
211
212
213
214
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 
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
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
    set_telemetry_file_dir(telemetry_file_dir)

    # 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
        set_telemetry_server_url(telemetry_server_url)

    # 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
        set_apptelemetry_server_url(apptelemetry_server_url)

    # 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()