Simple Log Service:Coletar logs do lado do cliente com WebTracking

ou mini program

O WebTracking oferece dois métodos de ingestão. A ingestão autenticada é a abordagem recomendada.

• Ingestão autenticada (recomendada): O frontend obtém um token STS temporário do backend. Esse token fornece credenciais de privilégio mínimo e tempo limitado (AccessKey + SecurityToken) para solicitações de log assinadas no SLS, evitando falsificações e contaminação de dados. Ideal para produção.

• Ingestão não autenticada: O frontend grava logs diretamente em um endpoint público do WebTracking sem credenciais. Embora simples de configurar, exige permissão de gravação anônima. Se as informações do Project ou Logstore vazarem, a contaminação de dados será possível. Recomendado apenas para testes.

Preparar recursos cloud

Crie os recursos cloud necessários para armazenar logs.

Etapa 1: Criar um project

Um project é o contêiner de recursos de nível superior no SLS e isola recursos entre diferentes aplicações.

Procedimento: Faça logon no console do Log Service e clique em Create Project.

Parâmetros:

• Region: Selecione uma região com base na localização das suas fontes de log. Não é possível alterar essa configuração após criar o project.

• Project Name: Insira um nome globalmente exclusivo no Alibaba Cloud. Não é possível alterar esse nome após criar o project.

• Mantenha as demais configurações com os valores padrão e clique em Create.

Etapa 2: Criar um Logstore

Um Logstore armazena os logs de frontend coletados.

Procedimento: Acesse o project desejado. No painel de navegação, escolha Log Storage e clique em +.

Parâmetros:

• Logstore Name: Insira um nome exclusivo dentro do project. Esse nome não pode ser alterado posteriormente. Exemplo: web-tracking-logstore.

• Logstore Type: Selecione Standard ou Query conforme suas necessidades.

• Billing Mode:

  • Pay-by-feature: Adequado para cenários com baixo volume de logs ou para desenvolvimento e testes.

  • Pay-by-ingested-data: Indicado para cenários com volumes de log estáveis que exigem análise de longo prazo.

• Data Retention Period: O padrão é 30 dias. O intervalo suportado varia de 1 a 3.650 dias.

• Mantenha as demais configurações com os valores padrão e clique em OK.

Modo de autenticação STS (Recomendado)

Este método utiliza um service de credenciais no backend para evitar a exposição de chaves no frontend. É a abordagem recomendada para produção.

Como funciona

O frontend solicita uma credencial temporária a um service STS no seu servidor de aplicação. O SDK do WebTracking usa essa credencial para enviar os logs. Por padrão, as credenciais expiram após 60 minutos.

1. A aplicação frontend solicita uma credencial de segurança temporária ao servidor de aplicação para enviar os logs.

2. Após validar a solicitação, o servidor de aplicação usa um usuário RAM pré-configurado para chamar a API AssumeRole do Alibaba Cloud STS e assumir uma função RAM com permissões de gravação no SLS.

3. O STS valida as permissões da função e emite uma credencial de segurança temporária contendo um AccessKey ID, um AccessKey Secret e um security token.

4. O servidor de aplicação retorna a credencial de segurança temporária à aplicação frontend.

5. A aplicação frontend utiliza a credencial de segurança temporária com o SDK do WebTracking para enviar os logs ao Logstore especificado.

# Install the Flask web framework and related Alibaba Cloud SDK libraries
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

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

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. We recommend using a unique identifier for the request source.
role_session_name = '<YOUR_ROLE_SESSION_NAME>'  # e.g., sls-web-session-001

# The region of the STS service, such as cn-hangzhou.
region_id = 'cn-hangzhou'
# ==============================================

@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 initializing CredentialClient, the default credential chain is used.
    # When running the program locally, specify the AccessKey pair by using the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
    # When running on ECS, ECI, or Container Service, specify the instance RAM role by using the ALIBABA_CLOUD_ECS_METADATA environment variable. The SDK automatically obtains the STS temporary credential.
    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 a temporary credential
    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)

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

curl http://<your_instance_public_ip_address>/get_sts_token

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

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

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

const opts = {
  host: "${endpoint}", // The endpoint for your region. Example: cn-hangzhou.log.aliyuncs.com
  project: "${project}", // Your project name.
  logstore: "${logstore}", // Your logstore name.
  time: 10, // The time interval for sending logs, in seconds. Default: 10.
  count: 10, // The number of logs to send in a batch. Default: 10.
  topic: "topic", // A custom log topic.
  source: "source",
  tags: {
    tags: "tags",
  },
};

const stsOpt = {
  accessKeyId: "",
  accessKeySecret: "",
  securityToken: "",
  
  // An asynchronous function to refresh the STS token.
  refreshSTSToken: () =>
    new Promise((resolve, reject) => {
      const xhr = new window.XMLHttpRequest();
      xhr.open("GET", "http://<your_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 credential.
            stsOpt.accessKeyId = credential.AccessKeyId;
            stsOpt.accessKeySecret = credential.AccessKeySecret;
            stsOpt.securityToken = credential.SecurityToken;
            resolve();
          } else {
            reject("Wrong status code.");
          }
        }
      };
    }),
   // (Optional) A custom refresh interval. Default: 5 minutes (300,000 ms).
  // refreshSTSTokenInterval: 300000,
  
  // (Optional) The period before token expiration to trigger a refresh, in milliseconds.
  // stsTokenFreshTime: undefined,
};

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

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

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">Login</button>

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

Ingestão não autenticada

Este método ativa o WebTracking em um Logstore para conceder acesso público de gravação. Os clientes enviam logs diretamente sem credenciais por meio do SDK, solicitações HTTP ou tags HTML.

Depois de ativar o WebTracking, a interface ACL do Logstore retorna HTTP 200 para solicitações de gravação anônimas. Esse é o comportamento esperado para ingestão anônima de logs e não indica uma vulnerabilidade de segurança grave. No entanto, existe um risco de baixa severidade de contaminação de dados. Para services com requisitos rigorosos de integridade de dados, ative o Modo de autenticação STS. Para desativar o acesso de gravação anônimo, desligue a chave WebTracking nas propriedades do Logstore. Após desativar o WebTracking, certifique-se de que sua aplicação frontend integrou um método de autenticação, como o plugin STS.

Etapa 1: Ativar o WebTracking

1. Faça logon no console do SLS.

2. Na seção Projects, clique no project desejado.

3. Na aba Log Storage > Logstores, localize o Logstore desejado e escolha > Modify.

4. Na página Logstore Attributes, clique em Modify.

5. Ative o WebTracking e clique em Save.

Etapa 2: Configurar ingestão não autenticada e enviar logs

O SLS oferece quatro métodos de integração:

• Integrar o SDK do WebTracking: Importe o SDK do WebTracking no código do seu frontend e chame o método send() para enviar logs estruturados. Este método é ideal para aplicações web modernas e mini programs.

• Solicitação HTTP GET: Anexe os dados do log aos parâmetros da URL e envie-os diretamente com uma solicitação GET. Esta abordagem é simples de implementar e ideal para depuração ou coleta leve de poucos logs.

• Tag HTML (img): Utilize o atributo src da tag <img> para iniciar uma solicitação, com as informações do log codificadas na URL. Este método não requer JavaScript, suporta nativamente solicitações cross-domain e é ideal para páginas estáticas ou rastreamento de e-mail.

• Gravação em lote via OpenAPI: Chame a OpenAPI do SLS enviando uma solicitação POST. Este método é adequado para enviar grandes volumes de dados a partir de um servidor.

# For browsers
npm install --save @aliyun-sls/web-track-browser

# For mini programs
npm install --save @aliyun-sls/web-track-mini

import SlsTracker from '@aliyun-sls/web-track-browser'

const opts = {
  host: '${host}', // The endpoint for SLS in your region. Example: cn-hangzhou.log.aliyuncs.com
  project: '${project}', // The project name.
  logstore: '${logstore}', // The logstore name.
  time: 10, // The time interval for sending logs, in seconds. Default value: 10.
  count: 10, // The number of logs to send in a batch. Default value: 10.
  topic: 'topic',// A custom log topic.
  source: 'source',
  tags: {
    tags: 'tags',
  },
}

const tracker = new SlsTracker(opts)  // Create an SlsTracker object

tracker.send({
  eventType:'view_product',
  productName: 'Tablet',
  price: 500
})

tracker.sendImmediate({
  eventType:'view_product',
  productName: 'Tablet',
  price: 500
})

tracker.sendBatchLogs([
  {
    eventType: 'view_product',
    productName: 'Tablet',
    price: 500
  },
  {
    eventType: 'view_product',
    productName: 'Laptop',
    price: 1200
  }
])

tracker.sendBatchLogsImmediate([
  {
    eventType:'view_product',
    productName: 'Tablet',
    price: 500
  },
  {
    eventType:'view_product',
    productName: 'Laptop',
    price: 1200
  }
])

curl --request GET 'https://${project}.${host}/logstores/${logstore}/track?APIVersion=0.6.0&key1=val1&key2=val2'

<!-- Collect custom fields -->
<img src='https://${project}.${host}/logstores/${logstore}/track.gif?APIVersion=0.6.0&key1=val1&key2=val2'/>
<!-- Also collect User-Agent and Referer -->
<img src='https://${project}.${host}/logstores/${logstore}/track_ua.gif?APIVersion=0.6.0&key1=val1&key2=val2'/>

Etapa 3: Verificar a ingestão de logs

Verifique se os logs do frontend chegaram ao Logstore do SLS.

1. Faça logon no console do SLS.

2. Na lista Projects, clique no project desejado.

3. Na página do Logstore, clique em ao lado do nome do Logstore desejado para expandi-lo.

4. Clique em para acessar a página Search & Analyze.

5. Clique em Enable. No painel que se abre à direita, clique em Automatic Index Generation.

6. O sistema identifica automaticamente a estrutura do log e gera configurações de campo recomendadas. Confirme as configurações e clique em OK.

7. Após ativar a indexação, aguarde cerca de um minuto para garantir que o índice entre em vigor. Em seguida, consulte os logs.

Cotas e limites

O WebTracking não oferece suporte a listas de permissões de endereços IP ou restrições de origem de acesso. O recurso foi projetado para coletar dados comportamentais e não inclui mecanismos integrados de filtragem de IP de origem ou lista de permissões. Se você precisar de controle de acesso, utilize o Modo de autenticação STS ou direcione os uploads de logs através de um servidor proxy no backend.

Requisitos de rede: O WebTracking exige que os navegadores possam acessar diretamente os endpoints públicos do Alibaba Cloud SLS pela internet. Se políticas de rede ou restrições de cross-origin impedirem o cliente de se conectar diretamente ao endpoint do SLS, o WebTracking não poderá ser utilizado. Nesses casos, considere direcionar os uploads de logs através de um servidor proxy no backend.

Limites de QPS: O WebTracking impõe limites de QPS na ingestão de logs. Para valores específicos, consulte a documentação do produto SLS ou o console. Em cenários de relatórios transfronteiriços, a instabilidade da rede pode causar falhas no upload. Avalie a viabilidade e os riscos de estabilidade de uploads de alta frequência a partir de um único endereço IP (por exemplo, 300 solicitações por segundo) antes de implantar em produção.

Faturamento

O WebTracking em si é gratuito, mas as operações de gravação, armazenamento e consulta de logs geram cobranças.

1. Modos de faturamento

Escolha um modo de faturamento ao criar um Logstore:

• Pay-by-ingested-data: Adequado para casos de uso complexos que exigem armazenamento, análise, processamento e consumo de logs de longo prazo em vários cenários.

• Pay-by-feature: Indicado para casos de uso leves ou graduais que necessitam de controle flexível de custos.

2. Itens faturáveis principais

Pay-by-ingested-data

• Volume de dados brutos ingeridos: Esta é a cobrança principal, faturada com base no tamanho não compactado (em GB) dos seus logs brutos. Essa taxa inclui gravações de dados, indexação, chamadas de API e o primeiro mês (30 dias) de hot storage.

• Taxas de armazenamento: O armazenamento além de 30 dias incorre em taxas adicionais.

Pay-by-feature

• Tráfego de índice: Uma taxa única é aplicada quando os dados são gravados, com base no tamanho não compactado dos logs brutos. Este é um pré-requisito para tornar os logs pesquisáveis.

• Taxas de armazenamento: Faturadas desde o primeiro dia com base no tamanho dos seus dados compactados.

• Tráfego de leitura e gravação, número de leituras e gravações, Shards ativos, entre outros.

FAQ

Importação via CDN

A importação via CDN é ideal para projetos frontend leves, páginas estáticas ou cenários de validação rápida sem um processo de build npm.

Risco de versão desatualizada: A versão mais recente via CDN é a 0.3.5, que pode não incluir recursos disponíveis em lançamentos npm mais recentes.

Como importar:

1. Adicione a seguinte referência de script à tag <head> ou <body> do seu arquivo HTML.

   <script src="https://g.alicdn.com/sls/sls-js-sdk/0.3.5/web-track-browser.js"></script>

2. Após o carregamento do SDK, inicialize a instância do rastreador com o objeto global window.SLS_Tracker:

   if (window.SLS_Tracker) {
     const tracker = new SLS_Tracker({
       host: 'your-project.cn-hangzhou.log.aliyuncs.com',
       project: 'your-project',
       logstore: 'your-logstore',
       time: 10,
       count: 10
     });
   }
   

**Qual é a diferença entre @aliyun-sls/web-browser e @aliyun-sls/web-track-browser?**

Nenhum dos SDKs coleta automaticamente erros de JavaScript ou dados de solicitações de rede. Você deve escrever o código manualmente para capturar e reportar esses eventos.

Escolha @aliyun-sls/web-browser se o seu caso de uso exigir o formato LogGroup para compatibilidade com pipelines de processamento de logs do SLS. Escolha @aliyun-sls/web-track-browser se preferir um formato JSON flexível e de forma livre com menor sobrecarga de desenvolvimento.

Documentação relacionada

• Criar um usuário RAM

• Conceder permissões a um usuário RAM

• Criar uma função RAM que confie em uma conta Alibaba Cloud

• Criar uma política personalizada

• SDK JavaScript do WebTracking para web

• Enviar logs usando o plugin STS para o SDK JavaScript do WebTracking

Apêndice 1: Exemplos de STS em várias linguagens

O Alibaba Cloud fornece exemplos open-source de services STS em Java, Node.js, PHP e Ruby. Cada exemplo chama a API AssumeRole para emitir credenciais temporárias para uma aplicação frontend.

Projetos de exemplo: Java, Node.js, PHP, Ruby

Para usar um exemplo, modifique o arquivo config.json e siga as instruções para a sua linguagem para iniciar o service.

Apêndice 2: Projeto frontend de exemplo