All Products
Search

This Product

    Simple Log Service:Runtime management

    Document Center

    Simple Log Service:Runtime management

    Last Updated:Nov 21, 2025

    After installing LoongCollector, you can manage its lifecycle. This topic describes how to modify configurations, upgrade the component, and uninstall it.

    Core components

    Namespace

    Name

    Type

    Function

    kube-system

    loongcollector-operator

    Deployment

    The central controller. It listens for custom resource (CR) events, performs automated management, and creates Simple Log Service (SLS) resources.

    kube-system

    loongcollector-ds

    DaemonSet

    The collection agent that runs on each node. It collects and sends logs.

    loongcollector-operator

    Resource type: Deployment. This is a single-instance controller that manages the configuration and coordination of the entire log collection system.

    Core responsibilities:

    • Centralized configuration management: Listens for the creation, update, and deletion of custom resources.

    • Dynamic configuration delivery: Converts custom resource (CR) rules into specific configurations and sends them to SLS.

    loongcollector-ds

    Resource type: DaemonSet. A loongcollector-ds pod is automatically deployed and runs on each node in the cluster. When a new node joins the cluster, a pod is deployed on it. When a node leaves the cluster, the pod is removed.

    Core responsibilities:

    • Log collection: Reads container logs and host files on nodes by mounting host directories.

    • State persistence: Saves collection progress (checkpoints) to a host path on the node. This prevents log loss or duplication that can be caused by pod restarts or migrations.

    • Configuration hot reloading: Automatically pulls and applies collection configurations from SLS without restarting pods.

    ConfigMap configuration

    Namespace

    Name

    Function

    kube-system

    alibaba-log-configuration

    Stores basic metadata for connecting to SLS.

    kube-system

    loongcollector-config

    The core connection configuration file for LoongCollector. It defines the endpoints for the configuration service and data uploads.

    Collect ACK cluster logs across accounts or regions

    Important

    Managing SLS resources using CRs across accounts is not supported.

    By default, LoongCollector that is installed from the Container Service for Kubernetes (ACK) console collects container logs from the cluster and sends them to an SLS project in the same account and region. To collect logs across Alibaba Cloud accounts or regions, you must modify the configuration.

    1. Log on to the ACK console. Click the target cluster. In the navigation pane on the left, choose Applications > Helm.

    2. On the Helm page, find loongcollector and click Update in the Actions column. On the Update Release page, modify the parameters as described in the following table, leave the other parameters unchanged, and click OK.

      Cluster and project

      Configuration to modify

      Same account, different region

      region: The Region ID of the region where the project is located.

      net: Internet. Service interconnection through the internal network is not available between different regions. Therefore, you must use the Internet to transfer data.

      Different account, same region

      aliUid: The ID of the Alibaba Cloud account that owns SLS. Separate multiple account IDs with commas (,).

      net: Intranet. We recommend that you use the internal network to transfer data within the same region.

      Different account, different region

      aliUid: The ID of the Alibaba Cloud account that owns SLS. Separate multiple account IDs with commas (,).

      region: The Region ID of the region where the project is located.

      net: Internet. Service interconnection through the internal network is not available between different regions. Therefore, you must use the Internet to transfer data.

    Modify the network transfer method (Internet/internal network)

    ACK cluster

    1. Log on to the ACK console. Click the target cluster. In the navigation pane on the left, choose Applications > Helm.

    2. On the Helm page, find loongcollector and click Update in the Actions column. On the Update Release page, modify the net parameter, leave the other parameters unchanged, and click OK.

      • Internet: The public internet.

      • Intranet: internal network

    3. In the navigation pane on the left, click Configurations > ConfigMaps. In the kube-system namespace, click alibaba-log-configuration and check whether the value of log-endpoint is updated:

      • If you set the transfer method to Internet, the value of log-endpoint is ${regionId}.log.aliyuncs.com.

      • If you set the transfer method to Intranet, the value of log-endpoint is ${regionId}-intranet.log.aliyuncs.com.

    Self-managed cluster

    1. Modify the configuration file: Log on to the server that contains the LoongCollector installation package, go to the loongcollector-custom-k8s-package installation folder, and modify the ne parameter in the ./loongcollector/values.yaml configuration file as needed:

      • Internet: Internet

      • Intranet: internal network

    2. Apply the update: Save the file and exit. Then, run the following command to update LoongCollector:

      bash k8s-custom-install.sh update

    3. Verify the update: Run the following command to verify that the configuration is updated:

      kubectl get configmap alibaba-log-configuration  -n kube-system -o yaml

      Check whether the log-endpoint field is updated:

      • If you set the transfer method to Internet, the value of log-endpoint is ${regionId}.log.aliyuncs.com.

      • If you set the transfer method to Intranet, the value of log-endpoint is ${regionId}-intranet.log.aliyuncs.com.

    Configure LoongCollector collection acceleration

    1. Enable the transfer acceleration endpoint for the project:

      1. Log on to the Simple Log Service console. In the Projects list, click the target project.

      2. Click the image icon next to the project name to open the project overview page. Enable the Acceleration Endpoint.

    2. Verify network connectivity: Log on to a cluster node where the LoongCollector component is installed. Run the following command to verify the network connectivity for transfer acceleration. The transfer acceleration feature is effective only for projects for which it is enabled.

      curl ${your-project}.log-global.aliyuncs.com

      If the following result is returned, the network connection is normal:

      {"Error":{"Code":"OLSInvalidMethod","Message":"The script name is invalid : /","RequestId":"XXXXXXXXXXXXXXXXXXX"}}
      The error message is returned because the access link is missing required parameters. This test only verifies network connectivity and does not use a complete link. An error message is expected if the network is normal.

    3. Modify the LoongCollector configuration:

      ACK cluster

      1. Log on to the ACK console. In the cluster list, click the name of the target cluster.

      2. In the navigation pane on the left, click Workloads > DaemonSets. In the kube-system namespace, search for loongcollector-ds and click the name of loongcollector-ds in the search results.

      3. On the loongcollector-ds basic information page, click Edit in the upper-right corner. Then, in the Environments section, set ALICLOUD_LOG_ENDPOINT to log-global.aliyuncs.com.

      4. After you complete the configuration, click Update.

      Self-managed cluster

      1. On a server where kubectl is installed and configured, run the following command to modify loongcollector-config:

        kubectl edit configmap loongcollector-config -n kube-system

      2. Replace the endpoint_list line in the data_servers parameter with log-global.aliyuncs.com.

        # $cat /usr/local/ilogtail/ilogtail_config.json

{
    "primary_region" : "cn-beijing",
    "config_servers" :
    [
        "http://logtail.cn-beijing.log.aliyuncs.com"
    ],
    "data_servers" :
    [
        {
            "region" : "cn-beijing",
            "endpoint_list": [
                "log-global.aliyuncs.com"
            ]
        }
    ]
}                                                                                                                                                                                   1,1           All

      3. Perform a rolling restart of loongcollector-ds to apply the configuration:

        kubectl rollout restart daemonset loongcollector-ds -n kube-system

    Upgrade LoongCollector

    If you installed LoongCollector in ACK, upgrade the component by performing the following steps:

    Note

    Direct upgrades are not supported for LoongCollector that is installed on self-managed clusters. To upgrade, you must reinstall the LoongCollector component. For more information, see Install LoongCollector.

    1. Log on to the ACK console. In the left navigation pane, click Clusters.

    2. On the Clusters page, find the one you want to manage and click its name. In the left navigation pane, click Add-ons.

    3. On the Logs and Monitoring tab, find loongcollector and click Upgrade.

    4. In the dialog box that appers, click OK.

    Uninstall LoongCollector

    ACK cluster

    1. Log on to the ACK console. In the left navigation pane, click Clusters.

    2. On the Clusters page, find the one you want to manage and click its name. In the left navigation pane, click Add-ons.

    3. On the Logs and Monitoring tab, find loongcollector and click Uninstall.

    4. Follow the on-screen instructions and click OK to complete the uninstallation.

    Self-managed cluster

    1. Run the following command to uninstall LoongCollector and its related resources:

      Important

      By default, this command does not delete the custom resource definition (CRD) resources that are installed by the chart.

      helm uninstall loongcollector -n kube-system
    2. Verify that the dynamic resources related to LoongCollector are cleaned up:
      kubectl get pods -A | grep loongcollector

      If no output is returned, the uninstallation is successful.

    View the LoongCollector status

    Run the following command to view the LoongCollector status.

    kubectl get po -n kube-system | grep loongcollector-ds

    The following example shows a sample output:

    loongcollector-ds-7r8w9                                    1/1     Running     0          3h13m
loongcollector-ds-gnbwp                                    1/1     Running     0          3h12m
loongcollector-ds-wmjnt                                    1/1     Running     0          3h13m

    View the LoongCollector version

    LoongCollector stores its version information in the loongcollector_version field of the /usr/local/ilogtail/app_info.json file. Run the following command to view the LoongCollector version.

    In the command, loongcollector-ds-7r8w9 is the pod name. Replace it with the actual pod name.

    kubectl exec loongcollector-ds-7r8w9 -n kube-system cat /usr/local/ilogtail/app_info.json

    The following example shows a sample output:

    {
        "compiler" : "GCC 9.3.1",
        "host_id" : "i-2ze40dgx0trvod9bky2u",
        "hostname" : "cn-hangzhou.172.*.*.253",
        "instance_id" : "0EBB2B0E-0A3B-11E8-B0CE-0A58AC140402_172.20.4.2_1517810940",
        "ip" : "172.23.125.253",
        "loongcollector_version" : "3.0.12",
        "os" : "Linux; 5.10.134-18.al8.x86_64; #1 SMP Fri Dec 13 16:56:53 CST 2024; x86_64",
        "update_time" : "2025-06-20 03:31:54"
}

    Parameters

    loongcollector-ds environment variables

    Important

    If you modify the LoongCollector startup parameters using both environment variables and the configuration file, the environment variables take precedence.

    LOONG_REGION String

    Specifies the region where the SLS project is located and the network transfer type.

    Network types include the following:

    • internet: Internet

    • intranet: Alibaba Cloud internal network

    loongcollector-ds.yaml

    # Source: loongcollector/templates/loongcollector-ds.yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: loongcollector-ds
  namespace: kube-system
  labels:
    k8s-app: loongcollector-ds
spec:
  selector:
    matchLabels:
      k8s-app: loongcollector-ds
  updateStrategy:
    rollingUpdate:
      maxUnavailable: 30%
    type: RollingUpdate
  template:
    metadata:
      labels:
        k8s-app: loongcollector-ds
        kubernetes.io/cluster-service: "true"
    spec:
      serviceAccountName: loongcollector-ds
      affinity: 
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: type
                operator: NotIn
                values:
                - virtual-kubelet
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
          - labelSelector:
              matchLabels:
                k8s-app: logtail-ds
            topologyKey: kubernetes.io/hostname
      nodeSelector:
        beta.kubernetes.io/os: linux
      
      containers:
      - name: loongcollector
        imagePullPolicy: Always
        image: registry-cn-beijing-vpc.ack.aliyuncs.com/acs/loongcollector:v3.1.1.0-20fa5eb-aliyun         
        resources:
          limits:
            cpu: "2"
            memory: "2048Mi"
          requests:
            cpu: 100m
            memory: 256Mi
        livenessProbe:
          httpGet:
            path: /liveness
            port: 7953
            scheme: HTTP
          initialDelaySeconds: 30
          periodSeconds: 60
        readinessProbe:
          failureThreshold: 3
          httpGet:
            path: /liveness
            port: 7953
            scheme: HTTP
          initialDelaySeconds: 35
          periodSeconds: 60
          successThreshold: 1
          timeoutSeconds: 1

        securityContext:
          allowPrivilegeEscalation: false
          seccompProfile:
            type: RuntimeDefault
          privileged: false
          procMount: Default
        env:
          - name: LOONG_REGION
            value: cn-beijing-internet
          - name: HTTP_PROBE_PORT
            value: "7953"
          - name: "ALIYUN_LOGTAIL_USER_ID"
            value: "15508*******1544"
          - name: "ALICLOUD_LOG_ECS_FLAG"
            value: "true"
          - name: "ALICLOUD_LOG_K8S_FLAG"
            value: "true"
          - name: "ALICLOUD_LOG_DEFAULT_PROJECT"
            value: "yilu-sls-0811"
          - name: "ALICLOUD_LOG_ENDPOINT"
            value: "cn-beijing.log.aliyuncs.com"
          - name: "ALICLOUD_LOG_DEFAULT_MACHINE_GROUP"
            value: "k8s-group-c63e2dea*****************8343e81e"
          - name: "ALIYUN_LOGTAIL_USER_DEFINED_ID"
            value: "$(ALICLOUD_LOG_DEFAULT_MACHINE_GROUP),"
          - name: "ALIYUN_LOGTAIL_CONFIG"
            value: "/usr/local/ilogtail/ilogtail_config.json"
          - name: "_node_name_"
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName
          - name: "_node_ip_"
            valueFrom:
              fieldRef:
                fieldPath: status.hostIP
          - name: working_ip
            valueFrom:
              fieldRef:
                apiVersion: v1
                fieldPath: status.hostIP
          - name: working_hostname
            valueFrom:
              fieldRef:
                apiVersion: v1
                fieldPath: spec.nodeName
          - name: _cluster_id_
            value: "c63e2dea*****************8343e81e"
          # resource limit for logtail self process
          - name: "LOONG_CPU_USAGE_LIMIT"
            value: "2"
          - name: "LOONG_MEM_USAGE_LIMIT"
            value: "2048"
          - name: "ALICLOUD_LOG_DOCKER_ENV_CONFIG"
            value: "true"
          - name: LOONG_MAX_BYTES_PER_SEC
            value: "209715200"
          - name: LOONG_SEND_REQUEST_CONCURRENCY
            value: "15"
          - name: LOONG_PROCESS_THREAD_COUNT
            value: "1"
          - name: ALIYUN_LOG_ENV_TAGS
            value: "_node_name_|_node_ip_|_cluster_id_"
          - name: LOONG_USER_CONFIG_FILE_PATH
            value: "/etc/ilogtail/checkpoint/user_log_config.json"
          - name: LOONG_DOCKER_FILE_CACHE_PATH
            value: "/etc/ilogtail/checkpoint/docker_path_config.json"
          - name: LOONG_CHECK_POINT_FILENAME
            value: "/etc/ilogtail/checkpoint/logtail_check_point"
          - name: LOONG_CHECK_POINT_DUMP_INTERVAL
            value: "60"
          - name: LOONG_BUFFER_FILE_PATH
            value: "/etc/ilogtail/checkpoint"
        volumeMounts:
        - name: run
          mountPath: /var/run/
        - name: root
          mountPath: /logtail_host
          readOnly: true
          mountPropagation: HostToContainer
        - mountPath:  /etc/ilogtail/checkpoint
          name: checkpoint
        - mountPath: /etc/ilogtail/config
          name: pipelineconfig
        - mountPath: /etc/ilogtail/instance_config
          name: instanceconfig
        - mountPath: /usr/local/ilogtail/ilogtail_config.json
          name: loongcollector-config
          subPath: ilogtail_config.json
        - mountPath: /run/nscd
          name: empty
        - name: addon-token
          mountPath: "/var/addon"
          readOnly: true
      terminationGracePeriodSeconds: 30
      tolerations:
      - operator: "Exists"
      dnsPolicy: "ClusterFirstWithHostNet"
      priorityClassName: system-cluster-critical
      volumes:
      - name: run
        hostPath:
          path: /var/run/
      - name: root
        hostPath:
          path: /
      - name: pipelineconfig
        hostPath:
          path: /var/lib/kube-system-logtail-ds/config
          type: DirectoryOrCreate
      - name: instanceconfig
        hostPath:
          path: /var/lib/kube-system-logtail-ds/instance_config
          type: DirectoryOrCreate
      - name: checkpoint
        hostPath:
          path: /var/lib/kube-system-logtail-ds/checkpoint
          type: DirectoryOrCreate
      - name: loongcollector-config
        configMap:
          defaultMode: 420
          name: loongcollector-config
      - name: empty
        emptyDir: {}
      - name: addon-token
        secret:
          secretName: addon.log.token
          optional: true
          items:
          - key: addon.token.config
            path: token-config

    HTTP_PROBE_PORT integer

    The health check port. The default value is 7953.

    ALIYUN_LOGTAIL_USER_ID String

    The user ID. Specify the ID of the Alibaba Cloud account to grant permission to collect container logs from the cluster.

    ALICLOUD_LOG_ECS_FLAG boolean

    Indicates whether the current environment is an Alibaba Cloud ECS environment.

    • true: Runs on an Alibaba Cloud ECS server.

    • false: Runs on a non-Alibaba Cloud ECS server.

    ALICLOUD_LOG_K8S_FLAG boolean

    It is running in a Kubernetes environment.

    • true: Runs in a Kubernetes environment.

    • false: Runs in a non-Kubernetes environment.

    ALICLOUD_LOG_DEFAULT_PROJECT String

    The default SLS project.

    ALICLOUD_LOG_ENDPOINT String

    The SLS access endpoint.

    ALICLOUD_LOG_DEFAULT_MACHINE_GROUP String

    The default machine group name.

    ALIYUN_LOGTAIL_USER_DEFINED_ID String

    The custom ID. If you create a machine group with a custom ID, the ID must be the same as the value of this environment variable.

    ALIYUN_LOGTAIL_CONFIG String

    The path of the startup parameter configuration file. The file must be in the JSON format. For more information, see Startup parameter configuration file.

    ALIYUN_LOG_ENV_TAGS String

    Specifies the metadata tags to automatically inject into logs. This is used with the _node_name_, _node_ip_, and _cluster_id_ environment variables.

    _node_name_ String

    The name of the node where the pod resides.

    _node_ip_ String

    The IP address of the node where the pod resides.

    _cluster_id_ integer

    The unique ID of the Kubernetes cluster.

    working_ip String

    The IP address that LoongCollector uses to report heartbeats and self-monitoring data. The value is the same as _node_ip_.

    working_hostname String

    The name of the node that LoongCollector uses to report heartbeats and self-monitoring data. The value is the same as _node_name_.

    LOONG_CPU_USAGE_LIMIT double

    The CPU usage threshold, calculated per core.

    Valid values: 0.1 to the number of CPU cores on the current machine.

    Warning

    This is a soft limit. The actual CPU usage may exceed the limit. If the limit is exceeded for 5 minutes, circuit breaking protection is triggered and the component automatically restarts.

    LOONG_MEM_USAGE_LIMIT integer

    The memory usage threshold. The default value is 2048. Valid values: 128 MB to 8192 MB. The collection rate, number of monitored directories and files, and send blocking level are related to this parameter. For more information, see Logtail limits.

    Warning

    This is a soft limit. The actual memory usage may exceed the limit. If the limit is exceeded for 5 minutes, circuit breaking protection is triggered and the component automatically restarts.

    ALICLOUD_LOG_DOCKER_ENV_CONFIG boolean

    Specifies whether to allow the creation of collection configurations through container environment variables.

    • true: Allows the creation of collection configurations through environment variables.

    • false: Does not allow the creation of collection configurations through environment variables.

    LOONG_MAX_BYTES_PER_SEC integer

    The traffic limit for sending raw data per second. The default value is 20971520 Byte/s. Valid values: 1024 Byte/s to 52428800 Byte/s.

    Important

    A value greater than 20971520 Byte/s (20 MB/s) indicates no speed limit.

    For example, if you set this parameter to 2097152, the data sending rate is 2 MB/s.

    LOONG_SEND_REQUEST_CONCURRENCY integer

    The number of concurrent asynchronous requests. Valid values: 1 to 50.

    If the write throughput per second (TPS) is high, set a higher number of concurrent requests. Calculate this based on a throughput of 0.5 MB/s to 1 MB/s per concurrent request. The actual value depends on the network latency.

    LOONG_PROCESS_THREAD_COUNT integer

    The number of threads for data processing. The default value is 1. Valid values: 1 to 64.

    In most cases, this can handle data writes of 24 MB/s in minimalist mode or 12 MB/s in full regex mode. You do not need to adjust this parameter by default.

    LOONG_USER_CONFIG_FILE_PATH String

    The LoongCollector collection configuration file. It records the collection configuration information that LoongCollector obtains from SLS. The file is in JSON format and is updated synchronously whenever the Logtail collection configuration is updated. Use this file to confirm whether the collection configuration has been delivered to the server. If the collection configuration file exists and its content is consistent with the collection configuration in SLS, the configuration has been successfully delivered. For more information, see Collection configuration file.

    Important

    We recommend that you do not modify this file, except to manually configure sensitive information such as AccessKey information and database passwords.

    LOONG_DOCKER_FILE_CACHE_PATH

    The container path mapping file. It records the path mappings between container files and host files. The file is in JSON format. For more information, see Container path mapping file.

    Note

    The `docker_path_config.json` file is a record file. Any modifications to it do not take effect. If you delete the file, it is automatically recreated and does not affect normal business operations.

    LOONG_CHECK_POINT_FILENAME String

    The path where the checkpoint file is saved.

    LOONG_CHECK_POINT_DUMP_INTERVAL integer

    The interval for updating the checkpoint file, in seconds.

    LOONG_BUFFER_FILE_PATH String

    The directory where cache files are stored.

    alibaba-log-configuration

    log-project String

    The name of the SLS project. The naming conventions are as follows:

    • The project name can contain only lowercase letters, digits, and hyphens (-).

    • It must start with a lowercase letter and end with a lowercase letter or a digit.

    • The name must be 3 to 63 characters in length.

    alibaba-log-configuration.yaml

    # Source: loongcollector/templates/legacy/alicloud-log-configuration.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: alibaba-log-configuration
  namespace: 
  labels:
    logtail-deployment: v2
data:
    log-project: "your-project-name"
    log-endpoint: "cn-beijing.log.aliyuncs.com"    
    log-machine-group: "k8s-group-c63e2*********************8343e81e"
    log-ali-uid: "1550********1544"
    log-config-path: "/etc/ilogtail/conf/cn-beijing/ilogtail_config.json"

    log-endpoint String

    The SLS service endpoint.

    log-machine-group String

    The name of the machine group. The naming conventions are as follows:

    • The name must be unique within the project.

    • It must start and end with a lowercase letter or a digit.

    • It can contain only lowercase letters, digits, hyphens (-), and underscores (_). The name must be 3 to 128 characters in length.

    log-ali-uid integer

    The ID of the Alibaba Cloud account. This grants the account permission to collect container logs from the cluster.

    log-config-path String

    The path of the LoongCollector configuration file.

    loongcollector-config

    primary_region String

    The Region ID of the region where the SLS project is located.

    loongcollector-config.yaml

    # Source: loongcollector/templates/loongcollector-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:  
  name: loongcollector-config
  namespace: kube-system
data:
  ilogtail_config.json: |
    {
        "primary_region" : "cn-beijing",
        "config_servers" :
        [
            "http://logtail.cn-beijing.log.aliyuncs.com"
        ],
        "data_servers" :
        [
            {
                "region" : "cn-beijing",
                "endpoint_list": [
                    "http://cn-beijing.log.aliyuncs.com"
                ]
            }
        ]
    }

    config_servers String

    The configuration server endpoint. LoongCollector obtains collection configurations from this endpoint.

    data_servers

    The data upload endpoint. This is the accepter for logs collected by LoongCollector.

    region

    The region where the data accepter is located.

    endpoint_list

    The server endpoint of the data accepter.

    What to do next

    After you install LoongCollector, see Kubernetes cluster container log collection to understand the core principles, key processes, selection suggestions, and best practices for collecting Kubernetes container logs. Then, choose a suitable method to create a collection configuration: