Simple Log Service:Collect client-side logs with WebTracking

1. The frontend application asks the backend service for temporary credentials.

2. The backend service calls the STS AssumeRole API, assuming a Resource Access Management (RAM) role with write permissions to SLS.

3. STS validates the request and returns temporary credentials (AccessKeyId, AccessKeySecret, and SecurityToken), which automatically expire after a set duration (60 minutes by default).

4. The backend service returns the temporary credentials to the frontend application.

5. The WebTracking SDK, a client-side JavaScript library for collecting and sending logs, then uses the credentials to sign requests and uploads logs to SLS.

1. Create a RAM role for the frontend application to assume

This role is a virtual identity without long-term keys, which your application temporarily assumes to obtain permissions to upload logs.

1.1 Create a RAM role

Log on to the RAM console. In the left-side navigation pane, choose Identities > Roles, then click Create Role.

Configuration:

• Principal Type: Select Cloud Account.

• Principal Name: Select the current account or specify another account.

• Click OK and enter the role name sls-web-tracking.

1.2 Create a policy that grants write-only permissions

This policy restricts the role to writing logs only to the specified logstore.

In the left-side navigation pane, choose Permissions > Policies, and then click Create Policy.

Configuration:

• On the JSON tab, paste the following script. Replace <ProjectName> and <LogstoreName> with your actual project name and logstore name.

  {
    "Version":"1",
    "Statement":[
      {
        "Effect":"Allow",
        "Action":[
          "log:PostLogStoreLogs",
          "log:PutLogs"
        ],
        "Resource":[
          "acs:log:*:*:project/<ProjectName>/logstore/<LogstoreName>"
        ]
      }
    ]
  }

• Click OK. Enter the policy name post-logs-policy and click OK.

1.3 Grant the RAM role permission to upload logs

Attach the write permission policy created in the previous step to the role that the frontend will assume.

In the left-side navigation pane, choose Identities > Roles. Click the target role name to go to the role details page. On the Permissions page, click Grant Permission.

Configuration:

• In the Grant Permission panel, search for and select the custom policy created in the previous step (post-logs-policy).

• Click Grant Permissions.

2. Create a RAM user for the backend service

Your backend service will use this user's long-term AccessKey to call the STS service and assume a role.

2.1 Create a RAM user

Log on to the RAM console. In the left-side navigation pane, choose Identities > Users, then click Create User.

Configuration:

• Logon Name: Supports only letters, numbers, periods (.), hyphens (-), and underscores (_), up to 64 characters. For example, sls-token-service.

• Access Mode: Select Using permanent AccessKey to access.

• Keep the default values for other parameters. Click OK to create the user. Save the AccessKey ID and AccessKey Secret.

  The AccessKey Secret is displayed only once upon creation and cannot be retrieved later. Be sure to save it to a secure location immediately.

2.2 Grant the RAM user permission to assume a role

Click the target username to go to the user details page. Switch to the Permissions tab and click Grant Permission.

Configuration:

• In the Policy section, select the AliyunSTSAssumeRoleAccess policy.

• Keep the default values for other parameters. Click Grant Permissions.

Summary: The backend service uses the RAM user (with its AccessKey) to assume the sls-web-tracking role, generating a temporary security credential that is returned to the frontend application. The WebTracking SDK then uses this temporary credential to securely upload logs.

Step 2: Build a backend STS temporary credential service

Build a backend API endpoint that receives credential requests from the frontend and securely returns temporary STS credentials. The following example uses Python and Flask.

For implementations in other languages, such as Java or Node.js, see Appendix 1: STS examples in multiple languages.

1. Prepare the server environment

In a production environment, the STS credential service can be either integrated into an existing application server or deployed as a standalone endpoint. Regardless of the approach, the host server must meet the following requirements:

• The frontend application can access the server over HTTP or HTTPS.

• Python 3 is installed. Version 3.8 or later is recommended.

Run the following command to install the dependencies required to call the Alibaba Cloud STS API.

# Install the Flask web framework and Alibaba Cloud SDK dependencies
pip3 install Flask==3.1.2
pip3 install aiohttp==3.8.4
pip3 install alibabacloud-credentials==0.3.2
pip3 install alibabacloud-sts20150401==1.1.3
pip3 install alibabacloud-tea==0.3.2
pip3 install alibabacloud-tea-openapi==0.3.7
pip3 install alibabacloud-tea-util==0.3.8
pip3 install alibabacloud-tea-xml==0.0.2

2. Write the backend STS service code

Create an HTTP endpoint /get_sts_token to generate and return STS temporary credentials.

2.1 Create the project directory and file

# Create and enter the project directory
mkdir my_web_sample
cd my_web_sample
touch main.py

2.2 Edit the main.py file

Paste the following code into the main.py file. Replace <YOUR_ROLE_ARN> with the ARN of the RAM role sls-web-tracking. Replace <YOUR_ROLE_SESSION_NAME> with a custom session name, such as role_session_test.

import json
from flask import Flask, render_template
from alibabacloud_tea_openapi.models import Config
from alibabacloud_sts20150401.client import Client as Sts20150401Client
from alibabacloud_sts20150401 import models as sts_20150401_models
from alibabacloud_credentials.client import Client as CredentialClient

app = Flask(__name__)

# ================== User Configuration ==================
# Replace with your RAM role ARN. Format: acs:ram::${accountId}:role/${roleName}
role_arn_for_sls_upload = '<YOUR_ROLE_ARN>'

# Set the role session name. A unique identifier for the request source is recommended.
role_session_name = '<YOUR_ROLE_SESSION_NAME>'  # For example, sls-web-session-001

# The region where the STS service is located, for example, ap-southeast-1.
region_id = 'ap-southeast-1'
# ==============================================

@app.route("/")
def hello_world():
    return render_template('index.html')

@app.route('/get_sts_token', methods=['GET'])
def get_sts_token():
    """
    Endpoint: /get_sts_token
    Method: GET
    Function: Call the STS AssumeRole API to obtain a temporary security token
    Returns: A Credentials object in JSON format
    """
    # If you do not specify parameters when you initialize CredentialClient, the default credential chain is used.
    # When you run the program locally, specify the AccessKey pair using the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
    # When you run the program on ECS, ECI, or Container Service, specify the instance role using the ALIBABA_CLOUD_ECS_METADATA environment variable. The SDK automatically obtains the temporary STS credentials.
    config = Config(
        region_id=region_id,
        credential=CredentialClient()
    )
    sts_client = Sts20150401Client(config=config)

    # Construct the AssumeRole request
    assume_role_request = sts_20150401_models.AssumeRoleRequest(
        role_arn=role_arn_for_sls_upload,
        role_session_name=role_session_name,
    )
      
    # Call STS to obtain temporary credentials
    response = sts_client.assume_role(assume_role_request)
    
    token = json.dumps(response.body.credentials.to_map())
    return token


app.run(host="0.0.0.0", port=80)

3. Start the backend service

Run the following command. Use the AccessKey pair of the RAM user created earlier.

ALIBABA_CLOUD_ACCESS_KEY_ID=<YOUR_AK_ID> 
ALIBABA_CLOUD_ACCESS_KEY_SECRET=<YOUR_AK_SECRET> 
python3 main.py

4. Verify that the endpoint is working

Send a test request:

curl http://<your_server_public_IP_address>/get_sts_token

Sample success response:

{
  "AccessKeyId": "STS.L4xxxxxx",
  "AccessKeySecret": "Dcyyyyyyyy",
  "Expiration": "2025-04-05T10:30:00Z",
  "SecurityToken": "CAISzxxxxxxxxxxx..."
}

Verification points:

• The response includes the AccessKeyId, AccessKeySecret, and SecurityToken fields.

• The AccessKeyId starts with STS., which indicates a temporary credential.

• The Expiration field indicates the expiration time, which should be within a reasonable range.

Step 3: Integrate the WebTracking SDK into your frontend

Integrate the SDK into your frontend application and configure the STS plugin for secure authorization and log upload. For a complete sample project, see Appendix II: Sample frontend application project.

1. Install SDK dependencies

Use npm to install the WebTracking SDK and its STS plugin:

npm install --save @aliyun-sls/web-track-browser
npm install --save @aliyun-sls/web-sts-plugin

2. Initialize the SDK and configure STS authentication

In your frontend project (such as in index.js), initialize the SlsTracker instance and configure its STS plugin.

2.1 Import core modules

import SlsTracker from "@aliyun-sls/web-track-browser";
import createStsPlugin from "@aliyun-sls/web-sts-plugin";

2.2 Configure basic SLS information

Fill in the following parameters based on your actual resource information:

const opts = {
  host: "${endpoint}", // The endpoint of your service region. For example, ap-southeast-1.log.aliyuncs.com
  project: "${project}", // Project name
  logstore: "${logstore}", // Logstore name
  time: 10, // The interval for sending logs, in seconds. Default is 10.
  count: 10, // The number of logs to send in a batch. Default is 10.
  topic: "topic", // Custom log topic
  source: "source",
  tags: {
    tags: "tags",
  },
};

2.3 Configure the STS plugin for secure authorization

To avoid exposing long-term AccessKeys on the client, the application instead fetches STS credentials from a backend service. The provided STS plugin automates the process of dynamically refreshing these credentials before they expire.

const stsOpt = {
  accessKeyId: "",
  accessKeySecret: "",
  securityToken: "",
  
  // Asynchronous function to refresh the STS credentials
  refreshSTSToken: () =>
    new Promise((resolve, reject) => {
      const xhr = new window.XMLHttpRequest();
      xhr.open("GET", "http://<your_ECS_instance_public_IP_address>/get_sts_token", true);
      xhr.send();
      
      xhr.onreadystatechange = () => {
        if (xhr.readyState === 4) {
          if (xhr.status === 200) {
            let credential = JSON.parse(xhr.response);
            // Update the temporary credentials
            stsOpt.accessKeyId = credential.AccessKeyId;
            stsOpt.accessKeySecret = credential.AccessKeySecret;
            stsOpt.securityToken = credential.SecurityToken;
            resolve();
          } else {
            reject("Wrong status code.");
          }
        }
      };
    }),
   // (Optional) Custom refresh interval. Default is 5 minutes (300,000 ms).
  // refreshSTSTokenInterval: 300000,
  
  // (Optional) Set how long before token expiration to refresh (in milliseconds).
  // stsTokenFreshTime: undefined,
};

2.4 Initialize the tracker instance and enable the STS plugin

// Create a tracker instance
const tracker = new SlsTracker(opts);

// Create and register the STS plugin
const stsPlugin = createStsPlugin(stsOpt);
tracker.useStsPlugin(stsPlugin);

3. Send logs from your application code

document.getElementById("loginButton").addEventListener("click", () => {
  const username = document.getElementById("username").value;
  
  tracker.send({
    eventType: "login",
    username: username,
  });
  
  console.log("Login event tracked for:", username);
});

<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="UTF-8" />
  <title>User Behavior Monitoring Example</title>
</head>
<body>
  <input type="text" id="username" placeholder="Enter username" />
  <button id="loginButton">Log On</button>

  <!-- Use a modular script -->
  <script type="module" src="/static/js/index.js"></script>
</body>
</html>

1. Start the frontend service and access the frontend page at http://<your_server_public_IP_address>.

2. Simulate a user action (for example, click the login button).

3. Open the developer tools in your browser by pressing F12:

   • On the Console tab, check whether the output displays Login event tracked for: xxx.

   • On the Network tab, check for a successful POST request to cn-xxx.log.aliyuncs.com.

Verify that client-side logs have been written to the logstore.

1. Log on to the SLS console.

2. In the Projects section, click the target project.

3. On the Logstores page, click the icon next to the target logstore name to expand it.

4. Click the icon to go to the Search & Analyze page.

5. Click Enable. In the panel that opens on the right, click Automatic Index Generation.

6. The system automatically identifies the log structure and recommends field configurations. Confirm the settings and click OK.

7. After the index is enabled, wait about 1 minute for it to take effect. Then query the logs.