This topic describes how to create a Logtail configuration in the Log Service console and use the Logtail configuration to collect container stdout and stderr in DaemonSet mode.

Prerequisites

  • The Logtail component is installed. For more information, see Install Logtail components in a Kubernetes cluster.
  • A Logstore is created in the project that you use to install the Logtail component. For more information, see Create a Logstore.
  • The container from which you want to collect logs continuously generates logs.
    Important Logtail collects only incremental logs. If a log file on a server is not updated after the applied Logtail configuration is delivered to the server, Logtail does not collect logs from the file. For more information, see Read log files.

Features

Logtail can collect container stdout and stderr, and then upload the stdout and stderr together with container metadata to Log Service. Logtail supports the following features:

  • Collects stdout and stderr.
  • Uses the container label whitelist to specify containers from which logs are collected.
  • Uses the container label blacklist to specify containers from which logs are not collected.
  • Uses the environment variable whitelist to specify containers from which logs are collected.
  • Uses the environment variable blacklist to specify containers from which logs are not collected.
  • Collects multi-line logs. For example, Logtail can collect Java stack logs.
  • Automatically associates container metadata that needs to be uploaded together with the collected container logs. The metadata includes container names, image names, pod names, namespaces, and environment variables.
  • If a container runs in a Kubernetes cluster, Logtail also supports the following features:
    • Uses Kubernetes namespaces, pod names, and container names to specify containers from which logs are collected.
    • Uses the Kubernetes label whitelist to specify containers from which logs are collected.
    • Uses the Kubernetes label blacklist to specify containers from which logs are not collected.
    • Automatically associates Kubernetes labels that need to be uploaded together with the collected container logs.

Implementation

Logtail communicates with the domain socket of Docker. Logtail queries all Docker containers and identifies the containers from which stdout and stderr are collected by using the specified labels and environment variables. Logtail runs the docker logs command to collect logs from the specified containers.

When Logtail collects stdout and stderr from a container, Logtail periodically stores checkpoints to a checkpoint file. If Logtail is stopped and then started, Logtail collects stdout and stderr from the last checkpoint. Implementation

Limits

  • You can use the Log Service console to collect stdout and stderr in DaemonSet mode only if Logtail runs V0.16.0 or later and runs on Linux. For more information about Logtail versions and version updates, see Install Logtail on a Linux server.
  • Logtail collects data from containers that use the Docker engine or containerd engine.
    • Docker: Logtail accesses the Docker engine in the /run/docker.sock directory. Make sure that the directory exists and Logtail has the permissions to access the directory.
    • containerd: Logtail accesses the containerd engine in the /run/containerd/containerd.sock directory. Make sure that the directory exists and Logtail has the permissions to access the directory.
  • By default, the last multi-line log that is collected by Logtail is cached for 3 seconds. This prevents the multi-line log from being split into multiple logs due to output latency. You can change the cache time by modifying the BeginLineTimeoutMs parameter. We recommend that you do not specify a value less than 1000 with millisecond precision. If you specify a value that is less than 1000, an error may occur.
  • If Logtail detects the die event on a container that is stopped, Logtail no longer collects stdout or stderr from the container. If collection latency exists, some stdout and stderr that are collected before the container is stopped may be lost.
  • The logging driver collects stdout and stderr only in the JSON format from containers that use the Docker engine.
  • By default, stdout and stderr that are collected from different containers by using the same Logtail configuration have the same context. In this case, you cannot view the stdout and stderr of a container in the Log Service console by using the context query feature or Livetail feature. To use the features, add the aggregator_context plug-in. For more information, see Configure aggregators.
  • By default, the collected data is stored in the content field. Logtail can process the collected data. For more information, see Use Logtail plug-ins to process data.

Create a Logtail configuration

  1. Log on to the Log Service console.
  2. In the Import Data section, click Kubernetes - Standard Output.
  3. Select a project and a Logstore. Then, click Next.
    In this example, select the project that you use to install the Logtail component and the Logstore that you create.
  4. Click Use Existing Machine Groups.
    After you install the Logtail component, Log Service automatically creates a machine group named k8s-group-${your_k8s_cluster_id}. You can select this machine group.
  5. Select the k8s-group-${your_k8s_cluster_id} machine group from Source Server Groups and move the machine group to Applied Server Groups. Then, click Next.
    Important If the heartbeat status of the machine group is FAIL, you can click Automatic Retry. If the issue persists, see What do I do if a Logtail machine group has no heartbeats?
  6. In the Specify Data Source step, specify a data source and click Next.
    You can specify a data source by using the Log Service console or by using JSON. For more information, see Details of the Logtail configuration.
  7. Preview data, configure indexes, and then click Next.
    By default, full-text indexing is enabled for Log Service. You can also configure field indexes based on collected logs in manual mode or automatic mode. To configure field indexes in automatic mode, click Automatic Index Generation. This way, Log Service automatically creates field indexes. For more information, see Create indexes.
    Important If you want to query and analyze logs, you must enable full-text indexing or field indexing. If you enable both full-text indexing and field indexing, the system uses only field indexes.
  8. Click Log Query. You are redirected to the query and analysis page of your Logstore.
    You must wait approximately 1 minute for the indexes to take effect. Then, you can view the collected logs on the Raw Logs tab. For more information, see Query and analyze logs.

Details of the Logtail configuration

Configuration by using the Log Service console

In the Specify Data Source step, configure the following parameters. Collect container stdout and stderr
  • Basic Information
    ParameterDescription
    Config NameThe name of the Logtail configuration.
    Standard OutputIf you select Standard Output, Logtail collects container stdout.
    Standard ErrorIf you select Standard Error, Logtail collects container stderr.
    Collection ModeThe mode of collection. You can collect container stdout and stderr in single-line or multi-line mode.

    If you collect container stdout and stderr in multi-line mode, you must configure Regex to Match First Line.

    Regex to Match First LineThe regular expression that is used to match the beginning of the first line of a log. If the beginning of a line matches the specified regular expression, the line is considered the first line of a new log. If the beginning of a line does not match the specified regular expression, the line is considered a part of the previous log.
  • Container Filtering

    A namespace of a Kubernetes cluster and the name of a container in a Kubernetes cluster can be mapped to container labels. The value of the LabelKey parameter for a namespace is io.kubernetes.pod.namespace. The value of the LabelKey parameter for a container name is io.kubernetes.container.name. We recommend that you use the two container labels to filter containers. If the container labels do not meet your business requirements, you can use the environment variable whitelist or the environment variable blacklist to filter containers. For example, the namespace of a pod is backend-prod, and the name of a container in the pod is worker-server. If you want the logs of the worker-server container to be collected, you can specify io.kubernetes.pod.namespace : backend-prod or io.kubernetes.container.name : worker-server in the container label whitelist.

    Important
    • Container labels are retrieved by running the docker inspect command. Container labels are different from Kubernetes labels. For more information, see Obtain container labels.
    • Environment variables are the same as the environment variables that are configured to start containers. For more information, see Obtain environment variables.
    • Do not specify duplicate values for the LabelKey parameter. If you specify duplicate values for the LabelKey parameter, only one of the values takes effect.
    ParameterDescription
    Container Label WhitelistThe container label whitelist. The whitelist specifies the containers from which stdout and stderr are collected. This parameter is empty by default, which indicates that stdout and stderr are collected from all containers. When you configure the container label whitelist, the LabelKey parameter is required, and the LabelValue parameter is optional.
    • If the LabelValue parameter is empty, containers whose container labels contain the keys specified by LabelKey are matched.
    • If the LabelValue parameter is not empty, containers whose container labels consist of the key-value pairs specified by LabelKey and LabelValue are matched.

      By default, string matching is performed for the values of the LabelValue parameter. Containers are matched only if the values of the container labels are the same as the values of the LabelValue parameter. If you specify a value that starts with a caret (^) and ends with a dollar sign ($) for the LabelValue parameter, regular expression matching is performed. For example, if you set the LabelKey parameter to io.kubernetes.container.name and set the LabelValue parameter to ^(nginx|cube)$, a container named nginx and a container named cube are matched.

    Key-value pairs are connected by using the OR operator. If a container has a container label that consists of one of the specified key-value pairs, the container is matched.

    Container Label BlacklistThe container label blacklist. The blacklist specifies the containers from which stdout and stderr are not collected. This parameter is empty by default, which indicates that stdout and stderr are collected from all containers. When you configure the container label blacklist, the LabelKey parameter is required, and the LabelValue parameter is optional.
    • If the LabelValue parameter is empty, containers whose container labels contain the keys specified by LabelKey are filtered out.
    • If the LabelValue parameter is not empty, containers whose container labels consist of the key-value pairs specified by LabelKey and LabelValue are filtered out.

      By default, string matching is performed for the values of the LabelValue parameter. Containers are matched only if the values of the container labels are the same as the values of the LabelValue parameter. If you specify a value that starts with a caret (^) and ends with a dollar sign ($) for the LabelValue parameter, regular expression matching is performed. For example, if you set the LabelKey parameter to io.kubernetes.container.name and set the LabelValue parameter to ^(nginx|cube)$, a container named nginx and a container named cube are matched.

    Key-value pairs are connected by using the OR operator. If a container has a container label that consists of one of the specified key-value pairs, the container is filtered out.

    Environment Variable WhitelistThe environment variable whitelist. The whitelist specifies the containers from which stdout and stderr are collected. This parameter is empty by default, which indicates that stdout and stderr are collected from all containers. When you configure the environment variable whitelist, the EnvKey parameter is required, and the EnvValue parameter is optional.
    • If the EnvValue parameter is empty, containers whose environment variables contain the keys specified by EnvKey are matched.
    • If the EnvValue parameter is not empty, containers whose environment variables consist of the key-value pairs specified by EnvKey and EnvValue are matched.

      By default, string matching is performed for the values of the EnvValue parameter. Containers are matched only if the values of the environment variables are the same as the values of the EnvValue parameter. If you specify a value that starts with a caret (^) and ends with a dollar sign ($) for the EnvValue parameter, regular expression matching is performed. For example, if you set the EnvKey parameter to NGINX_SERVICE_PORT and set the EnvValue parameter to ^(80|6379)$, containers whose port number is 80 and containers whose port number is 6379 are matched.

    Key-value pairs are connected by using the OR operator. If a container has an environment variable that consists of one of the specified key-value pairs, the container is matched.

    Environment Variable BlacklistThe environment variable blacklist. The blacklist specifies the containers from which stdout and stderr are not collected. This parameter is empty by default, which indicates that stdout and stderr are collected from all containers. When you configure the environment variable blacklist, the EnvKey parameter is required, and the EnvValue parameter is optional.
    • If the EnvValue parameter is empty, containers whose environment variables contain the keys specified by EnvKey are filtered out.
    • If the EnvValue parameter is not empty, containers whose environment variables consist of the key-value pairs specified by EnvKey and EnvValue are filtered out.

      By default, string matching is performed for the values of the EnvValue parameter. Containers are matched only if the values of the environment variables are the same as the values of the EnvValue parameter. If you specify a value that starts with a caret (^) and ends with a dollar sign ($) for the EnvValue parameter, regular expression matching is performed. For example, if you set the EnvKey parameter to NGINX_SERVICE_PORT and set the EnvValue parameter to ^(80|6379)$, containers whose port number is 80 and containers whose port number is 6379 are matched.

    Key-value pairs are connected by using the OR operator. If a container has an environment variable that consists of one of the specified key-value pairs, the container is filtered out.

    K8s Label WhitelistThe Kubernetes label whitelist. The whitelist specifies the containers from which stdout and stderr are collected. When you configure the Kubernetes label whitelist, the LabelKey parameter is required, and the LabelValue parameter is optional.
    • If the LabelValue parameter is empty, containers whose Kubernetes labels contain the keys specified by LabelKey are matched.
    • If the LabelValue parameter is not empty, containers whose Kubernetes labels consist of the key-value pairs specified by LabelKey and LabelValue are matched.

      By default, string matching is performed for the values of the LabelValue parameter. Containers are matched only if the values of the Kubernetes labels are the same as the values of the LabelValue parameter. If you specify a value that starts with a caret (^) and ends with a dollar sign ($), regular expression matching is performed. For example, if you set the LabelKey parameter to app and set the LabelValue parameter to ^(test1|test2)$, containers whose Kubernetes labels consist of app:test1 or app:test2 are matched.

    Key-value pairs are connected by using the OR operator. If a container has a Kubernetes label that consists of one of the specified key-value pairs, the container is matched.

    Note
    • Logtail V1.0.34 and later support this parameter.
    • If you change Kubernetes labels when Kubernetes control resources, such as Deployments, are running, the operational pod is not restarted. Therefore, the pod cannot detect the change. This may cause a matching rule to become invalid. When you specify the Kubernetes label whitelist and the Kubernetes label blacklist, we recommend that you use the Kubernetes labels of pods. For more information about Kubernetes labels, see Labels and Selectors.
    K8s Label BlacklistThe Kubernetes label blacklist. The blacklist specifies the containers from which stdout and stderr are not collected. When you configure the Kubernetes label blacklist, the LabelKey parameter is required, and the LabelValue parameter is optional.
    • If the LabelValue parameter is empty, containers whose Kubernetes labels contain the keys specified by LabelKey are filtered out.
    • If the LabelValue parameter is not empty, containers whose Kubernetes labels consist of the key-value pairs specified by LabelKey and LabelValue are filtered out.

      By default, string matching is performed for the values of the LabelValue parameter. Containers are matched only if the values of the Kubernetes labels are the same as the values of the LabelValue parameter. If you specify a value that starts with a caret (^) and ends with a dollar sign ($), regular expression matching is performed. For example, if you set the LabelKey parameter to app and set the LabelValue parameter to ^(test1|test2)$, containers whose Kubernetes labels consist of app:test1 or app:test2 are matched.

    Key-value pairs are connected by using the OR operator. If a container has a Kubernetes label that consists of one of the specified key-value pairs, the container is filtered out.

    Note
    • Logtail V1.0.34 and later support this parameter.
    • If you change Kubernetes labels when Kubernetes control resources, such as Deployments, are running, the operational pod is not restarted. Therefore, the pod cannot detect the change. This may cause a matching rule to become invalid. When you specify the Kubernetes label whitelist and the Kubernetes label blacklist, we recommend that you use the Kubernetes labels of pods. For more information about Kubernetes labels, see Labels and Selectors.
    NamespaceThe namespace. The namespace specifies the containers from which stdout and stderr are collected. Regular expression matching is supported. For example, if you specify "K8sNamespaceRegex":"^(default|nginx)$", all containers in the nginx and default namespaces are matched.
    Note Logtail V1.0.34 and later support this parameter.
    Pod NameThe pod name. The pod name specifies the containers from which stdout and stderr are collected. Regular expression matching is supported. For example, if you specify "K8sPodRegex":"^(nginx-log-demo.*)$",, all containers in the pod whose name starts with nginx-log-demo are matched.
    Note Logtail V1.0.34 and later support this parameter.
    Container NameThe container name. The container name specifies the containers from which stdout and stderr are collected. Regular expression matching is supported. Kubernetes container names are defined in spec.containers. For example, if you specify "K8scontainerRegex":"^(container-test)$", all containers whose name is container-test are matched.
    Note Logtail V1.0.34 and later support this parameter.
  • Field Extension

    For Logtail V1.0.34 or later, we recommend that you specify environment variables or Kubernetes labels for logs as log labels.

    ParameterDescription
    Extension with Environment VariableAfter you configure this parameter, Log Service adds environment variable-related fields to logs. For example, if you set Environment Variable Name to VERSION and set Extended Field Name to env_version, Log Service adds the __tag__:__env_version__: v1.0.0 field to logs if the environment variable configurations of a container include VERSION=v1.0.0.
    Extension with Kubernetes LabelAfter you configure this parameter, Log Service adds Kubernetes label-related fields to logs. For example, if you set K8s Label to app and set Extended Field Name to k8s_label_app, Log Service adds the __tag__:__k8s_label_app__: serviceA field to logs if the label configurations of a Kubernetes cluster include app=serviceA.
  • Advanced Parameters
    ParameterDescription
    Maximum Log Length (Unit: Bytes)The maximum size of a log. Default value: 524288. Unit: bytes. Valid values: [1024,20971520]. Unit: bytes.

    If the size of a log exceeds the value of this parameter, Logtail stops matching the beginning of the first line of the next log and uploads the log to Log Service.

    Maximum Length of Traced Historical Data during First Collection (Unit: Bytes)The maximum size of historical data that can be traced the first time Logtail collects logs from a log file. The default value is 131072 bytes, which is equivalent to 128 KB. Valid values: [131072,1048576]. Unit: bytes.
    First Line Length Matched by Regex (Unit: Bytes)The size of the beginning of the first line of a log that matches the specified regular expression. Default value: 10240. Unit: bytes.

    You can configure this parameter to check whether the beginning of the first line of a log matches the specified regular expression. We recommend that you configure this parameter to improve match efficiency.

    First Line Match Timeout (Unit: Milliseconds)The timeout period for matching the beginning of the first line of a log based on the specified regular expression. Default value: 3000. Unit: milliseconds.

    If no new log is generated within 3,000 milliseconds, Logtail stops matching and uploads the last log to Log Service.

Configuration by using JSON

In the Plug-in Configuration field, specify information about your Logtail configuration.
Note If your logs cannot be parsed based on your Logtail configuration, you can add the processors configuration in the Plug-in Configuration field to add plug-ins for data processing. For example, you can add plug-ins to extract fields, extract log time, mask data, and filter logs. For more information, see Use Logtail plug-ins to process data. 
{
    "inputs":[
        {
            "type":"service_docker_stdout",
            "detail":{
                "Stdout":true,
                "Stderr":true,
                "IncludeContainerLabel":{
                    "LabelKey":"LabelValue"
                },
                "ExcludeContainerLabel":{
                    "LabelKey":"LabelValue"
                },
                "IncludeK8sLabel":{
                    "LabelKey":"LabelValue"
                },
                "ExcludeK8sLabel":{
                    "LabelKey":"LabelValue"
                },
                "IncludeEnv":{
                    "EnvKey":"EnvValue"
                },
                "ExcludeEnv":{
                    "EnvKey":"EnvValue"
                },
                "ExternalK8sLabelTag":{
                    "EnvKey":"EnvValue"
                },
                "ExternalEnvTag":{
                    "EnvKey":"EnvValue"
                },
                "K8sNamespaceRegex":"^(default|kube-system)$",
                "K8sPodRegex":"^(deploy.*)$",
                "K8sContainerRegex":"^(container1|container2)$"
            }
        }
    ]
}
Configure the following parameters:
  • Data source type

    Set the type of the data source to service_docker_stdout.

  • Parameters related to container filtering
    • For versions earlier than Logtail V1.0.34, you can filter containers only by using environment variables or container labels.

      A namespace of a Kubernetes cluster and the name of a container in a Kubernetes cluster can be mapped to container labels. The value of the LabelKey parameter for a namespace is io.kubernetes.pod.namespace. The value of the LabelKey parameter for a container name is io.kubernetes.container.name. We recommend that you use the two container labels to filter containers. If the container labels do not meet your business requirements, you can use the environment variable whitelist or the environment variable blacklist to filter containers. For example, the namespace of a pod is backend-prod, and the name of a container in the pod is worker-server. If you want the logs of the worker-server container to be collected, you can specify io.kubernetes.pod.namespace : backend-prod or io.kubernetes.container.name : worker-server in the container label whitelist.

      Important
      • Container labels are retrieved by running the docker inspect command. Container labels are different from Kubernetes labels. For more information, see Obtain container labels.
      • Environment variables are the same as the environment variables that are configured to start containers. For more information, see Obtain environment variables.
      • Do not specify duplicate values for the LabelKey parameter. If you specify duplicate values for the LabelKey parameter, only one of the values takes effect.
      ParameterTypeRequiredDescription
      IncludeLabelMap (The values of the LabelKey and LabelValue parameters are strings.) NoThe container label whitelist. The whitelist specifies the containers from which stdout and stderr are collected. This parameter is empty by default, which indicates that stdout and stderr are collected from all containers. When you configure the container label whitelist, the LabelKey parameter is required, and the LabelValue parameter is optional.
      • If the LabelValue parameter is empty, containers whose container labels contain the keys specified by LabelKey are matched.
      • If the LabelValue parameter is not empty, containers whose container labels consist of the key-value pairs specified by LabelKey and LabelValue are matched.

        By default, string matching is performed for the values of the LabelValue parameter. Containers are matched only if the values of the container labels are the same as the values of the LabelValue parameter. If you specify a value that starts with a caret (^) and ends with a dollar sign ($) for the LabelValue parameter, regular expression matching is performed. For example, if you set the LabelKey parameter to io.kubernetes.container.name and set the LabelValue parameter to ^(nginx|cube)$, a container named nginx and a container named cube are matched.

      Key-value pairs are connected by using the OR operator. If a container has a container label that consists of one of the specified key-value pairs, the container is matched.

      ExcludeLabelMap (The values of the LabelKey and LabelValue parameters are strings.) NoThe container label blacklist. The blacklist specifies the containers from which stdout and stderr are not collected. This parameter is empty by default, which indicates that stdout and stderr are collected from all containers. When you configure the container label blacklist, the LabelKey parameter is required, and the LabelValue parameter is optional.
      • If the LabelValue parameter is empty, containers whose container labels contain the keys specified by LabelKey are filtered out.
      • If the LabelValue parameter is not empty, containers whose container labels consist of the key-value pairs specified by LabelKey and LabelValue are filtered out.

        By default, string matching is performed for the values of the LabelValue parameter. Containers are matched only if the values of the container labels are the same as the values of the LabelValue parameter. If you specify a value that starts with a caret (^) and ends with a dollar sign ($) for the LabelValue parameter, regular expression matching is performed. For example, if you set the LabelKey parameter to io.kubernetes.container.name and set the LabelValue parameter to ^(nginx|cube)$, a container named nginx and a container named cube are matched.

      Key-value pairs are connected by using the OR operator. If a container has a container label that consists of one of the specified key-value pairs, the container is filtered out.

      IncludeEnvMap (The values of the EnvKey and EnvValue parameters are strings.) NoThe environment variable whitelist. The whitelist specifies the containers from which stdout and stderr are collected. This parameter is empty by default, which indicates that stdout and stderr are collected from all containers. When you configure the environment variable whitelist, the EnvKey parameter is required, and the EnvValue parameter is optional.
      • If the EnvValue parameter is empty, containers whose environment variables contain the keys specified by EnvKey are matched.
      • If the EnvValue parameter is not empty, containers whose environment variables consist of the key-value pairs specified by EnvKey and EnvValue are matched.

        By default, string matching is performed for the values of the EnvValue parameter. Containers are matched only if the values of the environment variables are the same as the values of the EnvValue parameter. If you specify a value that starts with a caret (^) and ends with a dollar sign ($) for the EnvValue parameter, regular expression matching is performed. For example, if you set the EnvKey parameter to NGINX_SERVICE_PORT and set the EnvValue parameter to ^(80|6379)$, containers whose port number is 80 and containers whose port number is 6379 are matched.

      Key-value pairs are connected by using the OR operator. If a container has an environment variable that consists of one of the specified key-value pairs, the container is matched.

      ExcludeEnvMap (The values of the EnvKey and EnvValue parameters are strings.) NoThe environment variable blacklist. The blacklist specifies the containers from which stdout and stderr are not collected. This parameter is empty by default, which indicates that stdout and stderr are collected from all containers. When you configure the environment variable blacklist, the EnvKey parameter is required, and the EnvValue parameter is optional.
      • If the EnvValue parameter is empty, containers whose environment variables contain the keys specified by EnvKey are filtered out.
      • If the EnvValue parameter is not empty, containers whose environment variables consist of the key-value pairs specified by EnvKey and EnvValue are filtered out.

        By default, string matching is performed for the values of the EnvValue parameter. Containers are matched only if the values of the environment variables are the same as the values of the EnvValue parameter. If you specify a value that starts with a caret (^) and ends with a dollar sign ($) for the EnvValue parameter, regular expression matching is performed. For example, if you set the EnvKey parameter to NGINX_SERVICE_PORT and set the EnvValue parameter to ^(80|6379)$, containers whose port number is 80 and containers whose port number is 6379 are matched.

      Key-value pairs are connected by using the OR operator. If a container has an environment variable that consists of one of the specified key-value pairs, the container is filtered out.

    • For Logtail V1.0.34 or later, we recommend that you use different levels of Kubernetes information, such as pod names, namespaces, container names, and labels to filter containers.
      Note If you change Kubernetes labels when Kubernetes control resources, such as Deployments, are running, the operational pod is not restarted. Therefore, the pod cannot detect the change. This may cause a matching rule to become invalid. When you specify the Kubernetes label whitelist and the Kubernetes label blacklist, we recommend that you use the Kubernetes labels of pods. For more information about Kubernetes labels, see Labels and Selectors.
      ParameterTypeRequiredDescription
      IncludeK8sLabelMap (The values of the LabelKey and LabelValue parameters are strings.) NoThe Kubernetes label whitelist. The whitelist specifies the containers from which stdout and stderr are collected. When you configure the Kubernetes label whitelist, the LabelKey parameter is required, and the LabelValue parameter is optional.
      • If the LabelValue parameter is empty, containers whose Kubernetes labels contain the keys specified by LabelKey are matched.
      • If the LabelValue parameter is not empty, containers whose Kubernetes labels consist of the key-value pairs specified by LabelKey and LabelValue are matched.

        By default, string matching is performed for the values of the LabelValue parameter. Containers are matched only if the values of the Kubernetes labels are the same as the values of the LabelValue parameter. If you specify a value that starts with a caret (^) and ends with a dollar sign ($), regular expression matching is performed. For example, if you set the LabelKey parameter to app and set the LabelValue parameter to ^(test1|test2)$, containers whose Kubernetes labels consist of app:test1 or app:test2 are matched.

      Key-value pairs are connected by using the OR operator. If a container has a Kubernetes label that consists of one of the specified key-value pairs, the container is matched.

      ExcludeK8sLabelMap (The values of the LabelKey and LabelValue parameters are strings.) NoThe Kubernetes label blacklist. The blacklist specifies the containers from which stdout and stderr are not collected. When you configure the Kubernetes label blacklist, the LabelKey parameter is required, and the LabelValue parameter is optional.
      • If the LabelValue parameter is empty, containers whose Kubernetes labels contain the keys specified by LabelKey are filtered out.
      • If the LabelValue parameter is not empty, containers whose Kubernetes labels consist of the key-value pairs specified by LabelKey and LabelValue are filtered out.

        By default, string matching is performed for the values of the LabelValue parameter. Containers are matched only if the values of the Kubernetes labels are the same as the values of the LabelValue parameter. If you specify a value that starts with a caret (^) and ends with a dollar sign ($), regular expression matching is performed. For example, if you set the LabelKey parameter to app and set the LabelValue parameter to ^(test1|test2)$, containers whose Kubernetes labels consist of app:test1 or app:test2 are matched.

      Key-value pairs are connected by using the OR operator. If a container has a Kubernetes label that consists of one of the specified key-value pairs, the container is filtered out.

      K8sNamespaceRegexstringNoThe namespace. The namespace specifies the containers from which stdout and stderr are collected. Regular expression matching is supported. For example, if you specify "K8sNamespaceRegex":"^(default|nginx)$", all containers in the nginx and default namespaces are matched.
      K8sPodRegexstringNoThe pod name. The pod name specifies the containers from which stdout and stderr are collected. Regular expression matching is supported. For example, if you specify "K8sPodRegex":"^(nginx-log-demo.*)$",, all containers in the pod whose name starts with nginx-log-demo are matched.
      K8sContainerRegexstringNoThe container name. The container name specifies the containers from which stdout and stderr are collected. Regular expression matching is supported. Kubernetes container names are defined in spec.containers. For example, if you specify "K8scontainerRegex":"^(container-test)$", all containers whose name is container-test are matched.
  • Parameters related to log labels

    For Logtail V1.0.34 or later, we recommend that you specify environment variables or Kubernetes labels for logs as log labels.

    ParameterTypeRequiredDescription
    ExternalEnvTagMap (The values of the EnvKey and EnvValue parameters are strings.) NoAfter you specify environment variables as log labels, Log Service adds environment variable-related fields to logs. For example, if you set EnvKey to VERSION and set EnvValue to env_version, Log Service adds the __tag__:__env_version__: v1.0.0 field to logs if the environment variable configurations of a container include VERSION=v1.0.0.
    ExternalK8sLabelTagMap (The values of the LabelKey and LabelValue parameters are strings.) NoAfter you specify Kubernetes labels as log labels, Log Service adds Kubernetes label-related fields to logs. For example, if you set LabelKey to app and set LabelValue to k8s_label_app, Log Service adds the __tag__:__k8s_label_app__: serviceA field to logs if the label configurations of a Kubernetes cluster include app=serviceA.
  • Other parameters
    ParameterTypeRequiredDescription
    StdoutbooleanNoSpecifies whether to collect container stdout.
    • true: collects container stdout. This is the default value.
    • false: does not collect container stdout.
    StderrbooleanNoSpecifies whether to collect container stderr.
    • true: collects container stderr. This is the default value.
    • false: does not collect container stderr.
    BeginLineRegexstringNoThe regular expression that is used to match the beginning of the first line of a log.

    This parameter is empty by default, which indicates that each line is regarded as a log.

    Logtail uses a regular expression to match the beginning of the first line of a log. If the beginning of a line matches the specified regular expression, the line is considered the first line of a new log. If the beginning of a line does not match the specified regular expression, the line is considered a part of the previous log.

    BeginLineTimeoutMsintNoThe timeout period for matching the beginning of the first line of a log based on the specified regular expression. Default value: 3000. Unit: milliseconds.

    If no new log is generated within 3,000 milliseconds, Logtail stops matching and uploads the last log to Log Service.

    BeginLineCheckLengthintNoThe size of the beginning of the first line of a log that matches the specified regular expression. Default value: 10240. Unit: bytes.

    You can configure this parameter to check whether the beginning of the first line of a log matches the specified regular expression. We recommend that you configure this parameter to improve the match efficiency.

    MaxLogSizeintNoThe maximum size of a log. Default value: 524288. Unit: bytes. Valid values: [1024,20971520]. Unit: bytes.

    If the size of a log exceeds the value of this parameter, Logtail stops matching the beginning of the first line of the next log and uploads the log to Log Service.

    StartLogMaxOffsetintNoThe maximum size of historical data that can be traced the first time Logtail collects logs from a log file. The default value is 131072 bytes, which is equivalent to 128 KB. Valid values: [131072,1048576]. Unit: bytes.

Examples of Logtail configurations for single-line logs

Filter containers based on the environment variable whitelist and the environment variable blacklist

Collect stdout and stderr from the containers whose environment variable configurations include NGINX_SERVICE_PORT=80 but exclude POD_NAMESPACE=kube-system.

  1. Obtain environment variables.

    To view the environment variables of a container, you can log on to the host on which the container resides. For more information, see Obtain environment variables.

    Configuration example of environment variables
  2. Create a Logtail configuration.

    Example: 

    {
    "inputs": [
        {
            "type": "service_docker_stdout",
            "detail": {
                "Stdout": true,
                "Stderr": true,
                "IncludeEnv": {
                    "NGINX_SERVICE_PORT": "80"
                },
                "ExcludeEnv": {
                    "POD_NAMESPACE": "kube-system"
                }
            }
        }
    ]
}

Filter containers based on the container label whitelist and the container label blacklist

Collect stdout and stderr from the containers whose container label is io.kubernetes.container.name=nginx.

  1. Obtain container labels.

    To view the container labels of a container, you can log on to the host on which the container resides. For more information, see Obtain container labels.

    Configuration example of labels
  2. Create a Logtail configuration.

    Example: 

    {
    "inputs": [
        {
            "type": "service_docker_stdout",
            "detail": {
                "Stdout": true,
                "Stderr": true,
                "IncludeLabel": {
                    "io.kubernetes.container.name": "nginx"
                }
            }
        }
    ]
}

Filter containers by using Kubernetes namespaces, pod names, and container names

Collect stdout and stderr from the nginx-log-demo-0 container in pods whose name starts with nginx-log-demo in the default namespace.

  1. Obtain different levels of Kubernetes information.
    1. Obtain information about pods. Kubernetes resources
    2. Obtain information about namespaces. Kubernetes resources
  2. Create a Logtail configuration.
    Example: 
    {
    "inputs": [
        {
            "type": "service_docker_stdout",
            "detail": {
                "Stdout": true,
                "Stderr": true,
                "K8sNamespaceRegex":"^(default)$",
                "K8sPodRegex":"^(nginx-log-demo.*)$",
                "K8sContainerRegex":"^(nginx-log-demo-0)$"
            }
        }
    ]
}

Filter containers by using Kubernetes labels

Collect stdout and stderr from containers whose Kubernetes labels contain the job-name key and a specific value. The value starts with nginx-log-demo.

  1. Obtain Kubernetes labels. Kubernetes resources
  2. Create a Logtail configuration.
    Example: 
    {
    "inputs": [
        {
            "type": "service_docker_stdout",
            "detail": {
                "Stdout": true,
                "Stderr": true,
                "IncludeK8sLabel":{
                    "job-name":"^(nginx-log-demo.*)$"
                }
            }
        }
    ]
}

Examples of Logtail configurations for multi-line logs

Java exception stack logs are multi-line logs. You can create a Logtail configuration to collect the Java exception stack logs based on the following descriptions:
  • Sample logs 
    2021-02-03 14:18:41.968  INFO [spring-cloud-monitor] [nio-8080-exec-4] c.g.s.web.controller.DemoController : service start
2021-02-03 14:18:41.969 ERROR [spring-cloud-monitor] [nio-8080-exec-4] c.g.s.web.controller.DemoController : java.lang.NullPointerException
at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:193)
at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)
at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:199)
at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:96)
...
2021-02-03 14:18:41.968  INFO [spring-cloud-monitor] [nio-8080-exec-4] c.g.s.web.controller.DemoController : service start done
  • Logtail configuration

    Collect the Java exception stack logs of the containers whose container label is app=monitor. The Java exception stack logs start with a date that is in a fixed format. Logtail matches only the first 10 bytes of each line to improve match efficiency. After the logs are collected and sent to Log Service, Log Service uses regular expressions to parse the logs into fields such as time, level, module, thread, and message.

    • inputs is required and is used to configure the data source settings for the Logtail configuration. You must configure inputs based on your data source.
      Important You can specify only one type of data source in inputs.
    • processors is optional and is used to configure the data processing settings for the Logtail configuration. You can specify one or more processing methods. For more information, see Use Logtail plug-ins to process data. 
    {
"inputs": [
  {
    "detail": {
      "BeginLineCheckLength": 10,
      "BeginLineRegex": "\\d+-\\d+-\\d+.*",
      "IncludeLabel": {
        "app": "monitor"
      }
    },
    "type": "service_docker_stdout"
  }
],
"processors": [
    {
        "type": "processor_regex",
        "detail": {
            "SourceKey": "content",
            "Regex": "(\\d+-\\d+-\\d+ \\d+:\\d+:\\d+\\.\\d+)\\s+(\\w+)\\s+\\[([^]]+)]\\s+\\[([^]]+)]\\s+([\\s\\S]*)",
            "Keys": [
                "time",
                "level",
                "module",
                "thread",
                "message"
            ],
            "NoKeyError": true,
            "NoMatchError": true,
            "KeepSource": false
        }
    }
]
}
  • Parsed logs
    For example, if the collected log is 2018-02-03 14:18:41.968 INFO [spring-cloud-monitor] [nio-8080-exec-4] c.g.s.web.controller.DemoController : service start done, the log is parsed into the following fields:
    • _time_ is the log collection time. You can configure the Timezone parameter in the Logtail configuration to specify a time zone for _time_.
    • time is a time value recorded in the log and is extracted from the log. 
    __tag__:__hostname__:logtail-dfgef
_container_name_:monitor
_image_name_:example.com-hangzhou.aliyuncs.xxxxxxxxxxxxxxx
_namespace_:default
_pod_name_:monitor-6f54bd5d74-rtzc7
_pod_uid_:7f012b72-04c7-11e8-84aa-00163f00c369
_source_:stdout
_time_:2018-02-02T14:18:41.979147844Z
time:2018-02-02 02:18:41.968
level:INFO
module:spring-cloud-monitor
thread:nio-8080-exec-4
class:c.g.s.web.controller.DemoController
message:service start done

Log fields

The following table describes the fields that are uploaded by default for each log in a Kubernetes cluster.
FieldDescription
_time_The time at which the log is collected. Example: 2021-02-02T02:18:41.979147844Z.
_source_The type of the log source. Valid values: stdout and stderr.
_image_name_The name of the image.
_container_name_The name of the container.
_pod_name_The name of the pod.
_namespace_The namespace of the pod.
_pod_uid_The unique identifier of the pod.

Troubleshooting

If an exception occurs when you use Logtail to collect logs from containers, such as standard containers and Kubernetes containers, you can troubleshoot the issue based on the following topic:

What do I do if an error occurs when I use Logtail to collect logs from containers?