Python API Reference

The Fabasoft app.telemetry Python API was introduced in the Release 2026 August Release and allows you to instrument any Python application with instrumentation points to see what's going on in complex Python applications.

The Python API can be installed through the provided .whl file and pip. Afterwards, you can include the API in your Python application.

Constants and Configuration (Python)

All of the constants mentioned below are defined in the Python API file fabasoft.swtapipython.apm_const in the class “APMConst”. The environment configuration is defined in fabasoft.swtapipython.apm_sdk, in the class “APM” as a variable.

Version (Python)

APMConst.version contains the version number of the Python API.

Example: print(APMConst.version) // => “26.0.1”

Flags (Python)

Flags are used to specify the type of an event and are passed as argument to every event call.

Log Level (Python)

An event will only be logged if the event-level is lower or equal to the value selected in the session or log-definition.

Predefined Events (Python)

The SDK already provides a set of predefined events used for general purpose. For a full listing of all available predefined events see the generic chapter Predefined Events.

All predefined events are declared and available as global constants in the Python class “APMConst”.

Error/Trace Events:

Use these standard events to mark error, warning or info conditions in your application:

• EVENT_ERROR
• EVENT_WARNING
• EVENT_INFO
• EVENT_TRACE

Predefined Application Value Keys and Names (Python)

View the language agnostic Application Values section for an explanation of the properties listed below.

All predefined application value keys and names are available as public constants in the Python class “APMConst”.

• VALUE_VERSION_KEY with name VALUE_VERSION_NAME

Environment Configuration (Python)

Some settings for the Python SDK are configured directly for the initialized APM class. When the APM class is instantiated as “apm”, the following can be set for “apm.env”:

Configuration Functions (Python)

Besides setting the basic configuration variables (like apm.env.url) you can modify some parameters for your needs with the following setup functions described in the next sub chapters.

Method flush (Python)

Call apm.flush to trigger immediately sending events to the Fabasoft app.telemetry WebAPI service.

Parameters:

• send_all_events: If True all available events are transmitted to the server.
  If False a set of events will be transmitted in an asynchronous manner.

Return Value:

This function does not return any value.

Registration Functions (Python)

Method register_application (Python)

Call this function once to provide information about the context of the application.

Parameters:

• app_name: The name of your application
• app_id: The Id of your application
• app_tier_name: The tier inside the application
• app_tier_id: Id to distinguish multiple services of one application tier

Return Value:

This function does not return any value.

Remarks:

• Your application must be registered before any events can be fired.
• The communication with the Fabasoft app.telemetry WebAPI service is setup when first calling apm.register_application.

Method register_application_value (Python)

Call register_application_value to register additional static information about your application such as the version number.

Parameters:

• value_key: The application defined key of the value or the predefined VALUE_VERSION_KEY. Limited to 256 utf-8 encoded Bytes. Keys starting with “apm:” are reserved for internal use.
• value_name: The display name of the property (VALUE_VERSION_NAME, for the example above). Limited to 512 utf-8 encoded Bytes.
• value: The value of the property. Limited to 32768 utf-8 encoded Bytes.

Return Value:

This function does not return any value.

Method register_module (Python)

Call this function to register modules inside your application.

Parameters:

• module_name Desired name of your module.

Return Value:

• This function returns an object which you need to fire and register events.

Remarks:

• Different modules are shown as different bars during the analysis.

Method register_event (Python)

Call register_event on a registered module instance object to provide information about every event_id used for event tracing.

Parameters:

• event_id: This is the id of the event you want to register.
• description: The description of the event.
• parameter_description: Name of event parameters. If more parameters are used in one event, separate the parameter names by colon (,). For example: "name,count,size"

Return Value:

This function does not return any value.

Remarks:

If an event has more than one parameter you need to separate the parameter_description with colons (,).

Method register_filter_value (Python)

Call apm.register_filter_value for each valid filter value.

Parameters:

• value: value is the raw filter value.
• description: This is the description which is presented in the Client-User-Interface as filter.

Return Value:

This function does not return any value.

Context Handling Functions (Python)

Method create_context (Python)

Call apm.create_context to create a new Software-Telemetry context. If the filter value matches a currently started session filter, logging is started for the current execution flow. Make sure to call apm.release_context when exiting the context.

Parameters:

• context_id: The current context or None. You may call create_context multiple times to provide additional filter parameters. To do this you have to provide the previously created context id as the context_id input parameter in subsequent calls to create_context so that the create_context can be associated with the same request. To start a new context pass None as the context_id to get a new context_id as a return value from the create_context function.
• filter: This value is used to match a filter of a started Software-Telemetry session. You should register filter values used by calling register_filter_value (see “Method register_filter_value (Python)”)

Return Value:

• If the API is active this function returns a new context token, otherwise None will be returned.

Remarks:

• See chapter “Application Properties” for more information on the app.telemetry request concept.
• See “Method release_context (Python)”

Method release_context (Python)

Call apm.release_context to finish logging this request. Make sure to call apm.release_context for every request created with apm.create_context.

Parameters:

• context_id: The current context obtained by the corresponding create_context call.

Return Value:

This function does not return any value.

Remarks:

• If you don't call apm.release_context the request keeps the running status until the request-timeout has been reached.
• See “Method create_context (Python)”

Method get_context (Python)

Call apm.get_context to get a context handle, which can be passed to another thread or process. This context information is used by the analysis components to track the control flow through the distributed environment.

The acquired context handle has to be submitted (either by transmitting over the network or in another way) to the thread/process being called which associates the calling thread with itself by passing the context to the apm.attach_context-method.

Parameters:

• context_id: the current context (obtained by create_context).

Return Value:

• If the API is active this function returns a new context-token, otherwise None will be returned.

Remarks:

• See “Passing Context”
• See “Method create_context (Python)”, “Method attach_context (Python)”

Method attach_context (Python)

Call apm.attach_context to restore the context acquired through apm.get_context in another thread, process or execution flow.

Parameters:

• context_id: The current context or None. If you attach to a context within a previously created context using attach_context, pass the existing context_id as an input parameter. To start a new context pass None as the context_id to get a new context_id as a return value from the attach_context function.
• token: The context token which you want to attach to. You get such a context token by calling apm.get_context.

Return Value:

• If the API is active this function returns a new context_id if the context_id parameter was None, otherwise context_id will be returned.

Remarks:

• See “Passing Context”,
• See “Method get_context (Python)”

Method get_sync_mark (Python)

Call apm.get_sync_mark to get a synchronization handle that can be passed to another thread or process to synchronize control flow.

Parameters:

• context_id: This is the context for which you want to get a sync-mark.

Return Value:

• The return value is a Base64-encoded string which represents the token, or None if the API is inactive.

Remarks:

• See “Synchronizing Timeline with SyncMarks
• See “Method set_sync_mark (Python)”

Method set_sync_mark (Python)

Call apm.set_sync_mark to pass a synchronization handle you got from apm.get_sync_mark for synchronizing the sequence of events.

Parameters:

• context_id: This is the context for which you want to set a sync-mark.
• token: The sync-mark token you got from get_sync_mark form another thread/process.

Return Value:

This function does not return any value.

Remarks:

• See “Synchronizing Timeline with SyncMarks
• See “Method get_sync_mark (Python)”

Event Functions (Python)

Method event (Python)

Call event to log events with any number of parameters.

Parameters:

• context_id: This is the context in which the event happens and is to be logged.
• id: id of the event being processed (should have been registered with register_event – see “Method register_event (Python)”).
• level: event detail level for filtering. For the list of available log levels see chapter “Log Level (Python)”.
• flags: flags to mark events with Enter-, Leave- and/or Wait-semantic. More than one flags can be added together with a plus (+). For the list of available flags see chapter “Flags (Python)”.
• params...: You can specify up to 255 parameters after the flags parameter. None parameters are also allowed - even if they are in between normal parameters (None parameters are replaced by empty string parameters if needed).
  Note: do not specify objects as parameters!

Return Value:

This function does not return any value.

Remarks:

• See “Method register_event (Python)”, “Predefined Events (Python)”

Fabasoft app.telemetry Button (Python)

Method report (Python)

Call apm.report to create a new feedback report.

The filter value will be matched to the description using the registered filter values. Use the textual description of the feedback entered by the user or generated by the application to identify the report session later again.

Parameters:

• context_id: This is the context in which the report is generated.
• filter: The raw filter value.
• report_key: A key value must be generated by the calling application and can be used to associate further descriptions to a feedback.
• description: Application generated or entered by the user. The maximum length of the description is 32768 Bytes.

Return Value:

This function does not return any value.

Method report_value (Python)

Call apm.report_value to add a key/value pair to an existing report.

Parameters:

• context_id: This is the context in which the report is generated.
• report_key: match the report_key of the report function to associate the value with the report session.
• key: A key describes the meaning of the value. Only one value can be associated to a key in one report session.
• value: Textual value (max. 32 kBytes).

Return Value:

This function does not return any value.

Method report_content (Python)

Call apm.report_content to add content to an existing report.

Parameters:

• report_key: match the report_key of the report function to associate the content with the report session.
• file_name: A filename describing the content of the file. (max. 256 Bytes) – this is the name of the file in the reported session with which the data is persisted.
• value: This is the content – a string or byte-array to attach to the report.
• encoding (optional): The encoding type of the value content. Supported encoding types are:
  • "plaintext" (=default: if missing or null): string value will be written directly into the target file.
  • "base64": the passed content value must be Base64-encoded and will be decoded as Base64-value on the server for writing into the target file. This encoding allows you to attach binary data, images or similar to the report session.
• mime_type (optional): The MIME-type helps to identify the uploaded file content. You can provide any valid mime type string:
  • "text/plain" (=default: if missing or null)
  • "image/png"
  • "application/octet-stream"
  • etc.

Return Value:

This function does not return any value.

Remarks:

To allow applications to post random content, Fabasoft app.telemetry WebAPI supports posting content directly to the Fabasoft app.telemetry Web-API. Provide the report_key and the file_name as URL-parameters after the "?ReportContent" tag and the send the value as POST-data content.

Status Functions (Python)

Method has_active_context (Python)

Call apm.has_active_context to test, if a software-telemetry session is active for some logging level. This information should be used to avoid costly operations preparing parameters for events that are currently not logged.

Parameters:

• context_id: This is the context for which you want to know if the event will be logged.
• level: The event level of the event you prepare parameters for.

Return Value:

• The return value is True if the event will be logged.

Method is_connected (Python)

Call apm.is_connected to test, if the application has successfully registered to a Fabasoft app.telemetry agent/WebAPI. Your application must not make any assumptions based on the return value of this function as there are many reasons that may lead to a false being returned from this function even though the communication with the WebAPI be possible in general.

Parameters:

This function does not take any arguments.

Return Value:

• This function returns True if the communication to the configured Web-API web service is successful.

Remarks:

• A call to this function does not result in an request to the web service; instead, it returns the result of past communications, depending on when you call this function you may need to trigger a flush before.
• You can check if the API is active by checking apm.env.active. See “Environment Configuration (Python)” for details.