HCL Commerce Version 9.1.7.0 or later

Using the Must-Gather application

This topic describes the Must-Gather application usage. Must-Gather is used to gather troubleshooting information required to be shared with HCL Support to resolve the HCL Commerce issues.

About this task

Complete the following steps to collect the required troubleshooting data using the Must-Gather application.

Procedure

  1. Ensure that the Elasticsearch container is up and running.
  2. Complete the following steps to access the Must-Gather API and its endpoints using Swagger UI.
    1. Start the Must-Gather container. 
      docker run -e LICENSE=accept -e LOG_ELASTICSEARCH_HOST=LOG_ELASTICSEARCH_HOST -e LOG_ELASTICSEARCH_PORT=LOG_ELASTICSEARCH_PORT -p 42020:42020 -p 42021:42021 9.1.6.0/commerce-mustgather:Image-Version
    2. Optional: Set optional environment variables, or use their default values. 
      NIFI_HOST, NIFI_PORT, REGISTRY_HOST, REGISTRY_PORT, DATA_QUERY_HOST, DATA_QUERY_PORT, AUTH_QUERY_HOST, AUTH_QUERY_PORT, LIVE_QUERY_HOST, LIVE_QUERY_PORT, INGEST_HOST, INGEST_PORT
      Important: These environment variables are required for the Must-Gather application in order to pull configuration data from services.
    3. Using one of the following URLs, check whether you can access Swagger UI to interact with the Must-Gather API and its endpoints:
  3. Once you are able to access the Must-Gather API and its endpoints using any one of the Swagger UI URLs mentioned in step 2.c, use the desired Must-Gather API endpoint to run the same to gather troubleshooting data. the Must-Gather API has individual endpoints for each of the enabled services and a Global endpoint to gather the troubleshooting data from all the enabled services in one go.
    Important:
    • This API and its endpoints are only supported when HCL Commerce is deployed on Kubernetes.
    • Must-Gather is currently enabled only for the search services like Query service, Ingest service, Nifi, Registry, and Elasticsearch (Config only).
  4. Provide parameters for the endpoint to enable the Must-Gather application to filter logs and retrieve troubleshooting data from Elasticsearch. Each of these Must-Gather API endpoints, except for /search/elasticsearch, accepts the following parameters.
    Note:
    • None of these parameters are mandatory.
    • These parameters can be provided in any combination.
    Parameter name Usage
    traceId

    This parameter helps to get the logs of the specific request only.

    Whenever you use Query service or Ingest service endpoints through respective swagger UI, you receive a traceid in the response headers in the following manner:

    Copy this traceid and provide it in the Must-Gather API endpoint to get the logs pertaining to that specific request only.
    Important: This parameter should be used in combination with API level tracing in Query service and Ingest service for best results. For more details, refer to Logging and troubleshooting the Ingest and Query services.
    fromDate and toDate

    These two parameters help to filter logs to retrieve information based on the provided date range.

    Consider the following points while providing the values for these two parameters:
    • The date value is accepted in ISO8601 format which is yyyy-MM-dd.
    • If the fromDate value is not provided, it defaults to the day before the current date.
    • If the toDate value is not provided, it defaults to the current date.
    • toDate value cannot be earlier than the fromDate. value. It should always be greater than the fromDate.
    • If toDate value is provided, then providing fromDate value is mandatory.
    fromTime and toTime

    These two parameters help to filter logs to retrieve information based on the provided time range.

    Consider the following points while providing the values for these two parameters:
    • The time value is accepted in HH:mm:ss (UTC) format.
    • If the fromTime value is not provided, it defaults to the midnight time at the start of the current day which is “00:00”.
    • If the toTime value is not provided, it defaults to the time just before midnight at the end of the current day which is 23:59:59.999999999.
    • If fromDate and toDate values are the same, then toTime value cannot be earlier than the fromTime value.
    logLevel This parameter helps to filter logs and retrieve information based on logLevels in which the log messages are generated from the originating services.
    getConfigs By default, the Must-Gather application also pulls configuration data from respective enabled services. You can choose to disable this option using this parameter and pull just the logs.
    Note:
    • For Query service, the following configuration data is currently pulled:
    • For Ingest service, the following configuration data is currently pulled:
      Note: The run details are retrieved based on time range provided for the fromTime and toTime. Only those run details are returned whose timestamp is within the fromTime and toTime time range.
    • For Elasticsearch, the response of the following endpoints are gathered:
      http://<elasticsearchHost:elasticsearchPort>/_cat/indices?v&s=index
http://<elasticsearchHost:elasticsearchPort>/_cat/shards?v
http://<elasticsearchHost:elasticsearchPort>/_cluster/health?level=indices
http://<elasticsearchHost:elasticsearchPort>/_cat/segments?v
http://<elasticsearchHost:elasticsearchPort>/_aliases
  5. Set the global limit for documents retrieved per service by setting the environment variable MAX_DOCS_PER_SERVICE in the docker container.
    Note: If this variable is not set then the default limit for documents retrieved per service is 10000 documents per service.
  6. Run the Must-Gather API endpoint. A compressed zip archive file containing both the log and configuration data becomes available for you to download.
  7. Share the compressed zip archive file with HCL Support.