TracingSession

Tracing Session resource for Zscaler Digital Experience.

Resource operations

This resource supports the following standard methods: create(), load(), update(), delete(). They operate on the instance state — set properties with dot notation, then call the method with no arguments. Any other action listed below is a custom action that takes explicit keyword arguments and returns a value.

Quick Start

import zssdk
import logging

# Enable debug logging for TracingSession
logging.getLogger('zssdk.zdx').setLevel(logging.DEBUG)
logging.basicConfig(level=logging.DEBUG)

session = zssdk.Session(
    vanity_domain="your-vanity-domain",
    client_id="your-client-id",
    client_secret="your-client-secret",
)

# Get a specific TracingSession
resource = session.zdx.TracingSession(id="your-resource-id")
resource.load()
print(resource)

# Debug output shows HTTP request/response details

Identifiers

Name	Type	Description
id	string	Unique identifier

Actions

create()

Creates and starts a new live troubleshooting session with the specified parameters. Requires 'zdx-ltsession:write' and 'zdx-user-device-name-access:read' permissions.

Creates a new TracingSession. Set properties on the resource instance, then call create() — this method takes no arguments.

Properties for creation:

Name	Type	Required	Description
name	string	Yes	-
access_url	string	No	-
active	boolean	Yes	-
device	EntityResponse	Yes	-
user	EntityResponse	Yes	-
duration_minutes	integer	No	-
parameters	TracingParametersWrapperCollection	Yes	-
notification_enabled	boolean	No	-
shared	boolean	No	-
state	string	Yes	-

Returns: TracingSession

Example:

resource = session.zdx.TracingSession()
resource.name = "example-name"
resource.active = True
resource.device = {"id": 3600, "name": "example-name", "deleted": True, "disabled": True}
resource.user = {"id": 3600, "name": "example-name", "deleted": True, "disabled": True}
resource.parameters = [{"type": "value"}]
resource.state = "value"
resource.create()
print(f"Created with ID: {resource.id}")

delete()

Deletes a specific live troubleshooting session by its ID. Requires 'zdx-ltsession:write' and 'zdx-user-device-name-access:read' permissions.

Deletes a TracingSession by id. Only the id identifier is required; delete() takes no other arguments.

Example:

resource = session.zdx.TracingSession(id="your-resource-id")
resource.delete()

get_tracing_session_count()

Retrieves the count of live troubleshooting sessions based on optional filtering criteria. Requires 'zdx-ltsession:read' permission.

Parameters:

Name	Type	Required	Description
state	string	No	-
search	string	No	-
active	boolean	No	-

Returns: CountResponse

Example:

resource = session.zdx.TracingSession()
result = resource.get_tracing_session_count()
print(result)

get_tracing_session_state()

Retrieves the current state of a specific live troubleshooting session. Requires 'zdx-ltsession:read' permission.

Returns: TracingSessionStateResponse

Example:

resource = session.zdx.TracingSession(id="your-resource-id")
result = resource.get_tracing_session_state()
print(result)

get_tracing_session_status()

Retrieves the status (active/inactive) of a specific live troubleshooting session. Requires 'zdx-ltsession:read' permission.

Example:

resource = session.zdx.TracingSession(id="your-resource-id")
result = resource.get_tracing_session_status()
print(result)

load()

Retrieves detailed information about a specific live troubleshooting session by its ID. Requires 'zdx-ltsession:read' permission.

Fetches an existing TracingSession by id. Only the id identifier is required; load() takes no other arguments.

Returns: TracingSession

Example:

resource = session.zdx.TracingSession(id="your-resource-id")
resource.load()
print(resource.name)

stop_tracing_session()

Stops a running live troubleshooting session by its ID. Requires 'zdx-ltsession:write' and 'zdx-user-device-name-access:read' permissions.

Returns: TracingSessionStateResponse

Example:

resource = session.zdx.TracingSession(id="your-resource-id")
result = resource.stop_tracing_session()
print(result)

update()

Updates an existing live troubleshooting session with the provided parameters. Requires 'zdx-ltsession:write' and 'zdx-user-device-name-access:read' permissions.

Updates an existing TracingSession. Call load() first, modify properties, then call update() — this method takes no arguments.

Properties for update:

Name	Type	Required	Description
name	string	Yes	-
access_url	string	No	-
active	boolean	Yes	-
device	EntityResponse	Yes	-
user	EntityResponse	Yes	-
duration_minutes	integer	No	-
parameters	TracingParametersWrapperCollection	Yes	-
notification_enabled	boolean	No	-
shared	boolean	No	-
state	string	Yes	-

Returns: TracingSession

Example:

resource = session.zdx.TracingSession(id="your-resource-id")
resource.load()
resource.name = "Updated value"
resource.update()

validate_pcap_filter_expression()

Validates a PCAP filter expression for live troubleshooting sessions. This ensures the filter syntax is correct before applying it to a session. Requires 'zdx-ltsession:write' permission.

Parameters:

Name	Type	Required	Description
expression	string	Yes	-

Returns: PcapFilterExpressionResponse

Example:

resource = session.zdx.TracingSession()
result = resource.validate_pcap_filter_expression(expression="value")
print(result)

Attributes

Name	Type	Required	Description
name	string	Yes	-
access_url	string	No	-
active	boolean	Yes	-
device	EntityResponse	Yes	-
user	EntityResponse	Yes	-
duration_minutes	integer	No	-
parameters	TracingParametersWrapperCollection	Yes	-
notification_enabled	boolean	No	-
shared	boolean	No	-
id	long	Yes	-
state	string	Yes	-
created_at_timestamp	long	Yes	-
aborted_at_timestamp	long	No	-
started_at_timestamp	long	No	-
progress_started_at	long	No	-
completed_at_timestamp	long	No	-
device_initiated_at_timestamp	long	No	-
device_started_at_timestamp	long	No	-
device_completed_at_timestamp	long	No	-
create_or_updated_by_user	EntityResponse	No	-
create_or_updated_by_client_app	EntityResponse	No	-

Related

• TracingSession - Data structure definition
• Logging guide - enable verbose logs while debugging this resource