tencent cloud

Feedback

Embedding CLS Console

Last updated: 2022-03-16 17:00:55

    Overview

    CLS allows you to embed the CLS console into an external system so you can conduct log search and analysis without logging in to Tencent Cloud console. This feature offers benefits as follows:

    • Quickly integrate CLS search and analysis capabilities into an external service system (e.g., for business maintenance or operation).
    • Easily share your log data with others without needing to manage additional Tencent Cloud sub-accounts.

    Sample code for an embedded page: cls-iframe-demo.

    Note:

    This example does not include the authentication logic of external systems. After deployment, all users (even if they have not logged in to Tencent cloud) can view the data under their accounts with the role permissions configured in the example. To ensure data privacy and security, please add the authentication logic of external systems or restrict their access to the private network only to ensure that only authorized users can view the page.

    See the figure below for an overview of this feature:
    img

    Prerequisites

    1. Log in to the CAM console to create a CAM role with console login permissions. Set the role entity to root account, e.g. CompanyOpsRole. Grant the CAM role appropriate access permissions using policies, e.g. QcloudCLSReadOnlyAccess for read-only access.
    2. Log in to the CAM console.
    3. Click Roles on the left sidebar to go to the roles list page.
    4. Choose Create Role > Tencent Cloud Account to create a custom role.
    5. Select Current root account **, check **Allow the current role to access console, and click Next.
      img
      Note:

      If the option Allow the current role to access console is not available, submit a ticket to apply for adding the role to the allowlist.

    6. Set access policies for the role, e.g., the read-only policy QcloudCLSReadOnlyAccess, and click Next.
      img
    7. Enter the role name and click Done.
      img
    8. Obtain the access key of the current user. For more information, see Root Account Access Key.

    Directions

    1. Log in to the web server outside Tencent Cloud.

    2. The external web server assigns you the pre-created role created in Prerequisite 1 based on your identity, e.g. CompanyOpsRole.

    3. The web server accesses the Tencent Cloud STS service based on the role name and uses the access key obtained in Prerequisite 2 to call the AssumeRole API to apply for a temporary key of CompanyOpsRole.

    4. Call the AssumeRole API to get the temporary key of CompanyOpsRole.

    5. Generate a login signature using the temporary key with the steps as shown below:

    6. Sorting parameters
      Sort parameters to be signed listed below in ascending alphabetical or numerical order. That is, sort the parameters by their first letters, then by their second letters if their first letters are the same, and so on. You can do this with the aid of sorting functions in programming languages, such as the ksort function in PHP.

      Parameter Required Type Description
      action Yes String Action; fixed as `roleLogin`
      timestamp Yes Int Current timestamp
      nonce Yes Int Random integer. Value range: 10000-100000000
      secretId Yes String Temporary AK returned by STS
    7. Formatting parameters
      Combine the above sorted parameters into the form of "parameter name=parameter value". Example:

      action=roleLogin&nonce=67439&secretId=AKI***PLE×tamp=1484793352
      
    8. Constructing a signature string
      Construct a signature string in the format of “request method + request CVM + request path + ? + request string”.

      Parameter Required Description
      Request CVM and path Yes Fixed as cloud.tencent.com/login/roleAccessCallback
      Request method Yes GET or POST

      Sample signature string

          GETcloud.tencent.com/login/roleAccessCallback?action=roleLogin&nonce=67439&secretId=AKI***PLE×tamp=1484793352
      
    9. Generating a signature string
      Currently, you can sign a string using HMAC-SHA1 or HMAC-SHA256. The sample code in PHP is as follows:

      $secretKey = 'Gu5***1qA';
      $srcStr    = 'GETcloud.tencent.com/login/roleAccessCallback?action=roleLogin&nonce=67439&secretId=×tamp=1484793352';
      $signStr   = base64_encode(hash_hmac('sha1', $srcStr, $secretKey, true));
      echo $signStr;
      

      Sample code for PHP

          <?php
      $secretId  = "AKI***";            //Temporary AK returned by STS
      $secretKey = "Gu5***PLE";         //Temporary SecretKey returned by STS
      $token     = "ADE***fds";         //Security Token returned by STS
      $param["nonce"]     = 11886;      //rand(10000,100000000);
      $param["timestamp"] = 1465185768; //time();
      $param["secretId"]  = $secretId;
      $param["action"]    = "roleLogin";
      ksort($param);
      $signStr = "GETcloud.tencent.com/login/roleAccessCallback?";
      foreach ( $param as $key => $value ) {
          $signStr = $signStr . $key . "=" . $value . "&";
      }
      $signStr   = substr($signStr, 0, -1);
      $signature = base64_encode(hash_hmac("sha1", $signStr, $secretKey, true));
      echo $signature.PHP_EOL;
      
    10. Combine your login information and destination page URL into a login URL.

      1. Get the CLS console search analysis page URL.
        https://console.intl.cloud.tencent.com/cls/search?region=<region>&topic_id=<topic_id>
        

      Parameters in the CLS console search analysis page URL:

      ParameterRequiredTypeDescription
      regionYesStringRegion abbreviation, e.g., ap-shanghai for Shanghai region. For other available region abbreviations, see Available Regions
      topic_idNoStringLog topic ID
      logset_nameNoStringLogset name
      topic_nameNoStringLog topic name
      timeNoStringTime range for log search. Format example: 2021-07-15T10:00:00.000,2021-07-15T12:30:00.000
      queryBase64NoStringSearch and analysis statement, which is base64Url-encoded
      filterNoStringFilter condition, which is base64Url-encoded. For more information, see Filter Parameter Description
      hideWidgetNoBooleanIndicates whether to hide agent/documentation button in the bottom-right corner. `true`: Yes; `false`: No (default)
      hideTopNavNoBooleanIndicates whether to hide the top navigation bar in the Tencent Cloud console. `true`: Yes; `false`: No (default)
      hideLeftNavNoBooleanIndicates whether to hide the left navigation bar in the Tencent Cloud console. `true`: Yes; `false`: No (default)
      hideTopicSelectNoBooleanIndicates whether to hide the log topic selection controls (including the region, logset, and log topic controls). `true`: Yes; `false`: No (default)
      hideHeaderNoBooleanIndicates whether to hide the log topic selection control and the row where the control resides. `true`: Yes; `false`: No (default). This parameter is valid only when `hideTopicSelect` is `true`.
      hideTopTipsNoBooleanIndicates whether to hide the announcements on the top of the page. `true`: Yes; `false`: No (default)
      hideConfigMenuNoBooleanIndicates whether to hide the log topic configuration management menu. `true`: Yes; `false`: No (default)
      hideLogDownloadNoBooleanIndicates whether to hide the raw log download button. `true`: Yes; `false`: No (default)
    Note:

    You can specify the log topic to search using URL parameters in either the following modes:

    • topic_id: use the log topic ID to specify the log topic to search.

    • logset_name+topic_name: use the logset name and log topic name to specify the log topic to search. Note that if the logset or log topic name changes, the URL adopting this mode will become invalid.

    • If the topic_id, logset_name, and topic_name parameters exist at the same time, topic_id prevails.

    The following figure shows the mappings between hidden parameters and page modules:

    1. Splice your login information and destination page URL into a login URL. The parameter values should be URL-encoded.

      https://cloud.tencent.com/login/roleAccessCallback
      ?algorithm=<encryption algorithm for signing; currently only supports SHA1 (used by default) and SHA256
      &secretId=<secretId for signing>
      &token=<Temporary key token>
      &nonce=<nonce for signing>
      ×tamp=<Timestamp for signing>
      &signature=<Signature string>
      &s_url=<Destination URL after login>
      
    2. Use the final URL to access the embedded CLS page of the Tencent Cloud console. The sample below is a URL to the CLS search analysis page:

      https://cloud.tencent.com/login/roleAccessCallback?nonce=52055817&s_url=https%3A%2F%2Fconsole.cloud.tencent.com%2Fcls%2Fsearch%3Fregion%3Dap-guangzhou%26start_time%3D2020-05-26%25252014%25253A01%25253A18%26end_time%3D2020-05-26%25252014%25253A16%25253A18&secretId=AKID-vHJ7WPHcy_RVIOm-QTIktXOf9S9z_k_JackOp3dyQPJwmDrNLQJuiNuw9******&signature=eXeWaDn6iJlcPp1sqqGd6m9%2FQk****×tamp=1592455018&token=5e4vuBHL7fBQPi1V9fvSINw4Vu7PSr9Ic3de78b86109c171eb4e3ea27c137c1fIWKU8JC-LO01L87sIYlfTSaHHXeHcqim7Jg9hBuN2nbdfgeBUPXhmpyAk4G6e9bHFZ-7yNRig7Y33CQHxh6jOesP4VfhRzQprWGRtC5No1ty******-aoj_WJhA55oyvqaqxw2jtTdh8nx9OjJr3tlbIa9oJe7aZYoPbdpFqrF6ZjlCPPap2yQB_SkUsWwDl_9BrK2Km3U2IocdvQ7QxrW0ts1aiBi7xtTSJRcfkBYPYEV_YoJrtkhYW3E4L47imA1bfVAjM9F5uKWzVzsDGDT0aCUU9mqdb4vjJrY8tm-wJKKEe8eiyY9EbkH3VWnFV2YocYNDJqFyjKOWR******
      

    Filter Parameter Description

    Filter parameters are used to generate the filter condition in the query statement box at the bottom of the page, as shown in the figure blow, and are suitable for fixed search criteria.
    img

    Filter parameters are in JSON format in the following structure:

    [{
       "key": "action",
       "grammarName": "INCLUDE",
       "values": [{
           "values": ["test1"]
       }]
    }]
    

    Where:

    • key indicates the field name for key-value search. For full-text search, leave key empty.
    • grammarName indicates the specific filter mode of the filter condition. Supported values include INCLUDE, EXCLUDE, EXISTS, and RANGE.
      FeaturegrammarNameExampleEquivalent Search Statement
      Key-value search - INCLUDEINCLUDE[{"key":"action","grammarName":"INCLUDE","values":[{"values":["test1"]}]}]action:"test1"
      Key-value search - EXCLUDEEXCLUDE[{"key":"action","grammarName":"EXCLUDE","values":[{"values":["test1","test2"]}]}]NOT action:"test1" AND NOT action:"test2"
      Full-text search - INCLUDEINCLUDE_WITHOUT_KEY[{"key":"","grammarName":"INCLUDE_WITHOUT_KEY","values":[{"values":["test3"]}]}]"test3"
      Full-text search - EXCLUDEEXCLUDE_WITHOUT_KEY[{"key":"","grammarName":"EXCLUDE_WITHOUT_KEY","values":[{"values":["test3"]}]}]NOT "test3"
      The field existsEXISTS[{"key":"action","grammarName":"EXISTS","values":[]}]_exists_:action
      The field does not existNOT_EXISTS[{"key":"action","grammarName":"NOT_EXISTS","values":[]}]NOT _exists_:action
      The numeric type field is in the specified rangeRANGE[{"key":"time","grammarName":"RANGE","values":[{"values":["1"]},{"values":["100"]}]}]time:[1 TO 100]
      The numeric type field is outside the specified rangeNOT_RANGE[{"key":"time","grammarName":"NOT_RANGE","values":[{"values":["1"]},{"values":["100"]}]}]NOT time:[1 TO 100]
      The numeric type field is greater than the specified valueMORE_THAN[{"key":"time","grammarName":"MORE_THAN","values":[{"values":["1"]}]}]time:>1
      The numeric type field is greater than or equal to the specified valueMORE_THAN_OR_EQUAL[{"key":"time","grammarName":"MORE_THAN_OR_EQUAL","values":[{"values":["1"]}]}]time:>=1
      The numeric type field is less than the specified valueLESS_THAN[{"key":"time","grammarName":"LESS_THAN","values":[{"values":["1"]}]}]time:<1
      The numeric type field is less than or equal to the specified valueLESS_THAN_OR_EQUAL[{"key":"time","grammarName":"LESS_THAN_OR_EQUAL","values":[{"values":["1"]}]}]time:<=1
    Note:

    Only base64Url-encoded filter parameters can be added to URLs.

    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support