Docs

Torch Object Storage

Best Practices

Tracking download behaviors with TOS Browser

TOS Browser provides a link tracking feature that allows you to track download behaviors after objects are shared. This topic describes how to track object download behaviors through the browser.

How it works

You can create trackable links with TOS Browser. When other users log in to TOS Browser via these links and download the corresponding objects, Torch Log Service (TLS) collects data on their download activity. Then, you can search for and analyze this data through TLS to understand the current status of the downloaded objects.

Use cases

Bioinformatics companies that perform gene sequencing accumulate extensive gene data. They must authorize downstream companies to develop testing products. Gene sequencing companies require real-time insights into whether downstream companies have successfully downloaded data during the authorization and delivery process. This information is essential for confirming that the delivery is complete. With this data, companies can promptly adjust object storage types or delete unnecessary data to minimize storage costs. With the link tracking feature in TOS Browser, gene sequencing companies can now monitor the status of data downloads in real time. This feature allows them to verify that downstream companies have fully downloaded the data, offering proactive insight into and visibility of the delivery process.

Prerequisites

You have activated TLS. For instructions, see Getting Started.

Notes

Using the link tracking feature incurs charges for log storage, index storage, write traffic, index traffic, service requests, etc. TLS bills these charges separately. For billing details, see TLS Billing items.

TLS only collects data on object downloads via trackable links through TOS browser, not through any other browsers.

Step 1: Create a TLS topic

Create a TLS project.

In the top menu bar, select the region in which you want to create the TLS project.

In the left navigation pane, select Resource management > Project.

On the Project page, click Create project.

In the Create project dialog, configure Project name, Description, IAM Project, and Tag.

tip

For more information on the parameters for creating a TLS project, see Create project.

Once you have finished configuring, click Create.

Create a TLS topic.

On the Project page, click the project created in the previous step.

In the Topic section, click Create topic.

In the Create topic dialog, configure Topic name, Logs storage time configuration, and other parameters.

tip

For more information on the parameters for creating a TLS topic, see Create topic.

Once you have finished configuring, click Create.

Configure an index.

On the project details page, click the topic created in the previous step.

In the upper-right corner of the topic details page, click Index configuration.

In the Index configuration panel, enable the index feature. Then, select Key-value index, and create the index fields. The following two methods are supported:

Manual configuration

Click Add to manually configure Field name and Field type. For more information, see Field list.

Automatic configuration

First, share objects via TOS Browser to generate logs. Then, TLS can automatically build the index based on the raw logs. In the Index configuration panel, click Automatic configuration. Then, click Cover, and confirm by clicking OK in the box that appears.

tip

For more information, see Key-value index configuration.

Once you have finished configuring, click OK.

In the Prompt dialog, click OK.

Step 2: Share an object

You can create a trackable link using either TOS browser or the Python SDK.

Sharing an object using TOS Browser

On the Buckets page, click the bucket you want to share.

On the Objects page, click ... > Share in the Actions column of the object you want to share.

warning

Only users who are logged in with AK can use the sharing feature. Users who log in with other methods cannot use this feature.

In the Share object dialog, set the URL validity period, enable link tracking, and configure the following parameters.

Parameter	Description
TLS AK	The access key ID (AK) of the Volcano Engine account that uses TLS.
TLS SK	The secret access key (SK) of the Volcano Engine account that uses TLS. For instructions on how to view the AK and SK, see Viewing the Access Key ID and Secret Access Key. warning To prevent security issues caused by key leakage, strictly control access to your AK and SK.
TLS Host	The endpoint that you use to access TLS. For instructions on how to obtain the endpoint, see Endpoint. tip When setting the TLS Host, do not enter https://. Instead, enter tls-cn-beijing.ivolces.com, for example.
TLS Region	The region in which you created the TLS topic. TOS Browser automatically identifies the region based on the TLS Host that you provide.
TLS Topic ID	The ID of the TLS topic. On the topic details page, find the TLS topic ID in the Topic name/ID column.

Click Test sending logs.

After the page displays Logs sent successfully, click Create URL.

In the Share object dialog, copy the URL. Share this link with other users, who can access the object through TOS Browser.

Sharing an object using the Python SDK

Make changes to the parameters in the example code below based on your specific situation, and then run the code to create a trackable link.

Configure the following parameters based on your situation:

Parameter			Description
TOS_CONFIG	ak	The access key ID (AK) and secret access key (SK) for the Volcano Engine account that owns the bucket. For instructions on how to view the AK and SK, see Viewing the Access Key ID and Secret Access Key. By default, the example code obtains the AK and SK from the environment variables. Therefore, you must specify your AK and SK using environment variables. See Configuring long-term access credentials for instructions.
			sk
		endpoint	For more information on TOS endpoints, see Regions and endpoints.
		region	For more information on TOS regions, see Regions and endpoints.
LOG_CONFIG	ak	The access key ID (AK) and secret access key (SK) for the Volcano Engine account that uses TLS. For instructions on how to view the AK and SK, see Viewing the Access Key ID and Secret Access Key. By default, the example code obtains the AK and SK from the environment variables. Therefore, you must specify your AK and SK using environment variables. See Configuring long-term access credentials for instructions.
			sk
		topic_id	The ID of the TLS topic. On the topic details page, find the TLS topic ID in the Topic name/ID column.
		endpoint	The endpoint that you use to access TLS. For instructions on how to obtain the endpoint, see Endpoint.
		region	The region in which you created the TLS project and topic.
SHARECONFIG	bucket	The name of the bucket from which you are sharing the object.
		value	The name of the object you want to share.
		expires	The time at which the link expires, measured in seconds.

Step 3: Download the object

Other users can log in to TOS browser using the trackable link to download the object you are sharing. For instructions, see Log in to TOS Browser using a trackable link.

warning

To log in to TOS Browser using a trackable link, your TOS Browser version must be V 1.10.3 or later. Earlier versions do not support this login method.

Step 4: Query logs

After the object has been downloaded via the trackable link, you can query the relevant logs using either the TLS console or the Python SDK.

Field list

The TLS log fields used for tracking object downloads include browserVersion and bucketName. These fields are explained below.

Field name	Field type	Description
browserVersion	text	The version of TOS Browser.
bucketName	text	The name of the bucket from which you are sharing the object.
category	text	Log category.
failedReason	text	The reasons why TLS failed to collect logs on download activities.
fileName	text	The name of the object you are sharing.
fileSize	long	The size of the object, measured in bytes.
logAK	text	The access key ID of the Volcano Engine account that uses TLS.
originShareUrl	text	The trackable link.
system	text	The operating system used by the client.
taskStatus	text	Task status.
updateTime	text	The time when the log was collected.
downloadSize	long	The size of the downloaded object, measured in bytes.

Querying logs using the TLS console

In the top menu bar, select the region in which you created the TLS project.

In the left navigation pane, select Resource management > Project.

On the Project page, click the TLS project you created for the trackable link.

In the Topic section, click the TLS topic you created for the trackable link.

In the input box, enter the following statement: * | Select fileName,taskStatus,updateTime Where originShareUrl='<your URL>' order by updateTime. Then, click Search.

Example:

* | Select fileName,taskStatus,updateTime Where originShareUrl='https://document-share.tos-cn-beijing.volces.com/v2/index.html?token=****&logToken=****' order by updateTime

The query result will then be displayed in the Raw log section.

Querying logs using the Python SDK

Make changes to the parameters in the example code below based on your specific situation, and then run the code to query logs.

Configure the following parameters based on your situation:

Parameter	Description
endpoint	The endpoint that you use to access TLS. For instructions on how to obtain the endpoint, see Endpoint.
region	The region in which you created the TLS project and topic.
access_key_id	The access key ID (AK) and secret access key (SK) for the Volcano Engine account that uses TLS. For instructions on how to view the AK and SK, see Viewing the Access Key ID and Secret Access Key. By default, the example code obtains the AK and SK from the environment variables. Therefore, you must specify your AK and SK using environment variables. See Configuring long-term access credentials for instructions.
access_key_secret
topic_id	The ID of the TLS topic. On the topic details page, find the TLS topic ID in the Topic name/ID column.
org_share_url	The trackable link.
query_range_seconds	The time range for the query, measured in seconds.
limit	The maximum number of log entries that can be retrieved.

Last updated: 2025.11.18 14:49:33