All Products
Search

This Product

    Simple Log Service:UpdateLogtailPipelineConfig

    Document Center

    Simple Log Service:UpdateLogtailPipelineConfig

    Last Updated:Sep 18, 2026

    Updates a Logtail pipeline configuration.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    log:UpdateLogtailPipelineConfig

    update

    *All Resource

    *
    • log:TLSVersion
    		 None

    Request syntax

    PUT /pipelineconfigs/{configName} HTTP/1.1

    Path Parameters

    Parameter

    Type

    Required

    Description

    Example
    configName

    string

    Yes

    The Logtail pipeline configuration name.

    test-config

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    project

    string

    Yes

    The project name.

    test-project
    body

    object

    No

    The Logtail pipeline configuration content.

    aggregators

    array<object>

    No

    The list of aggregation plug-ins.

    Important This parameter takes effect only when extended processing plug-ins are used. A maximum of one aggregation plug-in is allowed.

    object

    No

    The aggregation plug-in.

    configName

    string

    Yes

    The configuration name.

    Important The value must be the same as the outer configName parameter.

    test-config
    flushers

    array<object>

    Yes

    The list of output plug-ins.

    Important Only one Simple Log Service output plug-in is allowed.

    object

    No

    The output plug-in.

    { "Type": "flusher_sls", "Logstore": "test" }
    global

    object

    No

    The general configurations.

    inputs

    array<object>

    Yes

    The list of input plug-ins.

    Important Only one input plug-in can be configured.

    object

    No

    The input plug-in.

    Note

    For file input plug-in parameters, refer to File plug-in. For other input plug-in parameters, refer to Processing plug-ins.

    { "Type": "input_file", "FilePaths": ["/var/log/*.log"] }
    logSample

    string

    No

    The log sample. Multiple log entries are supported.

    2022-06-14 11:13:29.796 | DEBUG | __main__::1 - hello world
    processors

    array<object>

    No

    The list of processing plug-ins.

    Note

    Processing plug-ins are classified into native processing plug-ins and extended processing plug-ins. For more information, refer to Processing plug-ins.

    Important
    Note

    • Native plug-ins can be used only to collect text logs.

    • You cannot add both native plug-ins and extended plug-ins at the same time.

    • When using native plug-ins, the following requirements must be met:

      • The first processing plug-in must be a regex parsing plug-in, delimiter parsing plug-in, JSON parsing plug-in, NGINX mode parsing plug-in, Apache mode parsing plug-in, or IIS mode parsing plug-in.

      • After the first processing plug-in, only one time parsing plug-in, one filter plug-in, and multiple data masking plug-ins are allowed.

    object

    No

    The processing plug-in.

    Note

    For more information, refer to Processing plug-ins.

    { "Type": "processor_parse_json_native", "SourceKey": "content" }
    task

    object

    No

    General configurations

    ParameterTypeRequiredDefault valueExampleDescription
    TopicTypestringNoEmptyfilepathThe topic type. Valid values:

    • filepath: Extracts information from the log file path as the topic. This value takes effect only when the input plug-in is input_file.

    • machine_group_topic: Uses the topic of the machine group to which this configuration is applied as the topic.

    • custom: Uses a custom topic. For more information, refer to Topic.

    TopicFormatstringNo. Required when TopicType is set to filepath or custom.//var/log/(.*).logThe topic format.
    EnableTimestampNanosecondboolNofalsefalseSpecifies whether to enable nanosecond precision for timestamps.
    PipelineMetaTagKeyobjectNoEmpty{"HOST_NAME":"__hostname__"}
    Important Supported only in LoongCollector 3.0.10 and later.
    Controls tags related to LoongCollector metadata. The key is the tag parameter name, and the value is the field name of the tag in the log. When the value is default, the default value is used. When the value is an empty string, the tag is removed. Configurable tags are as follows:

    • HOST_NAME: The hostname. Added by default. Default value: "__hostname__".

    • AGENT_TAG: The custom identifier. Added by default. Default value: "__user_defined_id__".

    • HOST_ID: The host ID. Not added by default. Default value: "__host_id__".

    • CLOUD_PROVIDER: Not added by default. Default value: "__cloud_provider__".

    Input plug-ins.

    File input plug-in

    ParameterTypeRequiredDefault valueExampleDescription
    TypestringYes/input_fileThe plug-in type. Set the value to input_file.
    FilePaths[string]Yes/["/var/log/*.log"]The list of log file paths to collect (only one path is supported). The * and ** wildcards are supported in the path. The ** wildcard can appear only once and can be used only before the file name.
    MaxDirSearchDepthuintNo00The maximum directory depth matched by the ** wildcard in the file path. This parameter takes effect only when the log path contains the ** wildcard. Valid values: 0 to 1000.
    ExcludeFilePaths[string]NoEmpty["/home/admin/*.log"]The file path blocklist. Paths must be absolute paths. The * wildcard is supported.
    ExcludeFiles[string]NoEmpty["app*.log", "password"]The file name blocklist. The * wildcard is supported.
    ExcludeDirs[string]NoEmpty["/home/admin/dir1", "/home/admin/dir2*"]The directory blocklist. Paths must be absolute paths. The * wildcard is supported.
    FileEncodingstringNoutf8utf8The file encoding format. Valid values: utf8 and gbk.
    TailSizeKBuintNo10241024The size from the end of the file at which collection starts when the configuration takes effect for the first time. If the file size is smaller than this value, collection starts from the beginning. Valid values: 0 to 10485760 KB.
    MultilineobjectNoEmpty/The multiline aggregation options.
    Multiline.ModestringNocustomcustomThe multiline aggregation mode. Valid values: custom and JSON.
    Multiline.StartPatternstringRequired when Multiline.Mode is set to customEmpty\d+-\d+-\d+.*The regular expression for the line start.
    EnableContainerDiscoveryboolNofalsetrueSpecifies whether to enable container discovery. This parameter takes effect only when Logtail runs in DaemonSet mode and the file path to collect is a path inside a container.
    ContainerFiltersobjectNoEmpty/The container filter options. Multiple options have an AND relationship. This parameter takes effect only when EnableContainerDiscovery is set to true.
    ContainerFilters.K8sNamespaceRegexstringNoEmptydefaultFor containers deployed in a Kubernetes environment, specifies the namespace condition of the pod to which the target container belongs. If this parameter is not specified, all containers are collected. Regular expression matching is supported.
    ContainerFilters.K8sPodRegexstringNoEmptytest-podFor containers deployed in a Kubernetes environment, specifies the pod name condition of the target container. If this parameter is not specified, all containers are collected. Regular expression matching is supported.
    ContainerFilters.IncludeK8sLabelmapNoEmpty/For containers deployed in a Kubernetes environment, specifies the pod label conditions of the target containers. Multiple conditions have an OR relationship. If this parameter is not specified, all containers are collected. Regular expression matching is supported. The key in the map is the pod label name, and the value is the pod label value:

    • If the value in the map is empty, all pods whose labels contain the specified key are matched.

    • If the value in the map is not empty:

      • If the value starts with ^ and ends with $, pods whose labels contain the specified key and whose corresponding label value matches the value as a regular expression are matched.

      • Otherwise, pods whose labels contain the specified key with the exact specified value are matched.

    ContainerFilters.ExcludeK8sLabelmapNoEmpty/For containers deployed in a Kubernetes environment, specifies the pod label conditions for containers to exclude from collection. Multiple conditions have an OR relationship. If this parameter is not specified, all containers are collected. Regular expression matching is supported. The key in the map is the pod label name, and the value is the pod label value:

    • If the value in the map is empty, all pods whose labels contain the specified key are matched.

    • If the value in the map is not empty:

      • If the value starts with ^ and ends with $, pods whose labels contain the specified key and whose corresponding label value matches the value as a regular expression are matched.

      • Otherwise, pods whose labels contain the specified key with the exact specified value are matched.

    ContainerFilters.K8sContainerRegexstringNoEmptytest-containerFor containers deployed in a Kubernetes environment, specifies the container name condition. If this parameter is not specified, all containers are collected. Regular expression matching is supported.
    ContainerFilters.IncludeEnvmapNoEmpty/Specifies the environment variable conditions of the target containers. Multiple conditions have an OR relationship. If this parameter is not specified, all containers are collected. Regular expression matching is supported. The key in the map is the environment variable name, and the value is the environment variable value:

    • If the value in the map is empty, all containers whose environment variables contain the specified key are matched.

    • If the value in the map is not empty:

      • If the value starts with ^ and ends with $, containers whose environment variables contain the specified key and whose corresponding value matches the value as a regular expression are matched.

      • Otherwise, containers whose environment variables contain the specified key with the exact specified value are matched.

    ContainerFilters.ExcludeEnvmapNoEmpty/Specifies the environment variable conditions for containers to exclude from collection. Multiple conditions have an OR relationship. If this parameter is not specified, all containers are collected. Regular expression matching is supported. The key in the map is the environment variable name, and the value is the environment variable value:

    • If the value in the map is empty, all containers whose environment variables contain the specified key are matched.

    • If the value in the map is not empty:

      • If the value starts with ^ and ends with $, containers whose environment variables contain the specified key and whose corresponding value matches the value as a regular expression are matched.

      • Otherwise, containers whose environment variables contain the specified key with the exact specified value are matched.

    ContainerFilters.IncludeContainerLabelmapNoEmpty/Specifies the container label conditions of the target containers. Multiple conditions have an OR relationship. If this parameter is not specified, the default value is empty, which indicates that all containers are collected. Regular expression matching is supported. The key in the map is the container label name, and the value is the container label value:

    • If the value in the map is empty, all containers whose labels contain the specified key are matched.

    • If the value in the map is not empty:

      • If the value starts with ^ and ends with $, containers whose labels contain the specified key and whose corresponding label value matches the value as a regular expression are matched.

      • Otherwise, containers whose labels contain the specified key with the exact specified value are matched.

    ContainerFilters.ExcludeContainerLabelmapNoEmpty/Specifies the container label conditions for containers to exclude from collection. Multiple conditions have an OR relationship. If this parameter is not specified, the default value is empty, which indicates that all containers are collected. Regular expression matching is supported. The key in the map is the container label name, and the value is the container label value:

    • If the value in the map is empty, all containers whose labels contain the specified key are matched.

    • If the value in the map is not empty:

      • If the value starts with ^ and ends with $, containers whose labels contain the specified key and whose corresponding label value matches the value as a regular expression are matched.

      • Otherwise, containers whose labels contain the specified key with the exact specified value are matched.

    ExternalK8sLabelTagmapNoEmpty/For containers deployed in a Kubernetes environment, specifies additional tags related to pod labels to add to logs. The key in the map is the pod label name, and the value is the corresponding tag name. For example, if you add app: k8s\_label\_app to the map and the pod contains the label app=serviceA, this information is added to the log as a tag, that is, the field __tag__:k8s_label_app: serviceA is added. If the pod does not contain the app label, an empty field __tag__:k8s_label_app: is added.
    ExternalEnvTagmapNoEmpty/For containers deployed in a Kubernetes environment, specifies additional tags related to container environment variables to add to logs. The key in the map is the environment variable name, and the value is the corresponding tag name. For example, if you add VERSION: env\_version to the map and the container contains the environment variable VERSION=v1.0.0, this information is added to the log as a tag, that is, the field __tag__:env_version: v1.0.0 is added. If the container does not contain the VERSION environment variable, an empty field __tag__:env_version: is added.
    CollectingContainersMetaboolNofalsetrueSpecifies whether to enable container metadata preview.
    AppendingLogPositionMetaboolNofalsefalseSpecifies whether to add metadata about the file to which the log entry belongs, including the __tag__:__inode__ field and the __file_offset__ field.
    AllowingIncludedByMultiConfigsboolNofalsefalseSpecifies whether to allow the current configuration to collect files that are already matched by other configurations.
    TagsobjectNoEmpty{"FileInodeTagKey":"__inode__"}
    Important Supported only in LoongCollector 3.0.10 and later.
    Controls tags related to file collection. The key is the tag parameter name, and the value is the field name of the tag in the log. When the value is default, the default value is used. When the value is an empty string, the tag is removed. Configurable tags are as follows:

    • FileInodeTagKey: The file inode. Not added by default. Default value: "__inode__".

    • FilePathTagKey: The file path. Added by default. Default value: "__path__".

    The following parameters take effect only when EnableContainerDiscovery is set to true.

    • K8sNamespaceTagKey: The namespace of the container where the file resides. Added by default. Default value: "_namespace_".

    • K8sPodNameTagKey: The pod name where the file resides. Added by default. Default value: "_pod_name_".

    • K8sPodUidTagKey: The pod UID where the file resides. Added by default. Default value: "_pod_uid_".

    • ContainerNameTagKey: The container name where the file resides. Added by default. Default value: "_container_name_".

    • ContainerIpTagKey: The container IP where the file resides. Added by default. Default value: "_container_ip_".

    • ContainerImageNameTagKey: The container image where the file resides. Added by default. Default value: "_image_name_".

    FileOffsetKeystringNoEmpty__file_offset__
    Important Supported only in LoongCollector 3.0.10 and later.
    The tag for the log position in the file. Not added by default. Default value: __file_offset__. When the value is __default__, the default value is used. When the value is an empty string, the tag is removed. When the EnableLogPositionMeta parameter and the Tags.FileInodeTagKey or FileOffsetKey parameter are both specified, the EnableLogPositionMeta parameter is ignored.

    Container stdout (legacy)

    ParameterTypeRequiredDefault valueExampleDescription
    TypestringYes/service_docker_stdoutThe plug-in type. Set the value to service_docker_stdout.
    StdoutBooleanNotruetrueSpecifies whether to collect standard output (stdout).
    StderrBooleanNotruetrueSpecifies whether to collect standard error output (stderr).
    StartLogMaxOffsetIntegerNo128×1024131072The length of historical data to trace back during the first collection, in bytes. We recommend a value in the range of [131072, 1048576].
    IncludeLabelMap, where LabelKey and LabelValue are of the String typeNoEmpty

    The container label allowlist, which specifies the containers to collect. The default value is empty, which indicates that stdout of all containers is collected. To configure the container label allowlist, LabelKey is required and LabelValue is optional.

    • If LabelValue is empty, all containers whose labels contain the specified LabelKey are matched.

    • If LabelValue is not empty, only containers whose labels contain LabelKey=LabelValue are matched.

      LabelValue uses exact string matching by default, which means the container label value must be identical to LabelValue. If the value starts with ^ and ends with $, regular expression matching is used. For example, setting LabelKey to io.kubernetes.container.name and LabelValue to ^(nginx|cube)$ matches containers named nginx or cube.

    Multiple allowlist entries have an OR relationship. A container is matched if its labels satisfy any allowlist entry.

    ExcludeLabelMap, where LabelKey and LabelValue are of the String typeNoEmpty

    The container label blocklist, which specifies the containers to exclude from collection. The default value is empty, which indicates that no containers are excluded. To configure the container label blocklist, LabelKey is required and LabelValue is optional.

    • If LabelValue is empty, all containers whose labels contain the specified LabelKey are excluded.

    • If LabelValue is not empty, only containers whose labels contain LabelKey=LabelValue are excluded.

      LabelValue uses exact string matching by default, which means the container label value must be identical to LabelValue. If the value starts with ^ and ends with $, regular expression matching is used. For example, setting LabelKey to io.kubernetes.container.name and LabelValue to ^(nginx|cube)$ matches containers named nginx or cube.

    Multiple blocklist entries have an OR relationship. A container is excluded if its labels satisfy any blocklist entry.

    IncludeEnvMap, where EnvKey and EnvValue are of the String typeNoEmpty

    The environment variable allowlist, which specifies the containers to collect. The default value is empty, which indicates that stdout of all containers is collected. To configure the environment variable allowlist, EnvKey is required and EnvValue is optional.

    • If EnvValue is empty, all containers whose environment variables contain the specified EnvKey are matched.

    • If EnvValue is not empty, only containers whose environment variables contain EnvKey=EnvValue are matched.

      EnvValue uses exact string matching by default, which means the environment variable value must be identical to EnvValue. If the value starts with ^ and ends with $, regular expression matching is used. For example, setting EnvKey to NGINX_SERVICE_PORT and EnvValue to `^(80

    ExcludeEnvMap, where EnvKey and EnvValue are of the String typeNoEmpty

    The environment variable blocklist, which specifies the containers to exclude from collection. The default value is empty, which indicates that no containers are excluded. To configure the environment variable blocklist, EnvKey is required and EnvValue is optional.

    • If EnvValue is empty, logs of all containers whose environment variables contain the specified EnvKey are excluded.

    • If EnvValue is not empty, only containers whose environment variables contain EnvKey=EnvValue are excluded.

      EnvValue uses exact string matching by default, which means the environment variable value must be identical to EnvValue. If the value starts with ^ and ends with $, regular expression matching is used. For example, setting EnvKey to NGINX_SERVICE_PORT and EnvValue to ^(80|6379)$ matches containers with service port 80 or 6379.

    Multiple blocklist entries have an OR relationship. A container is excluded if its environment variables satisfy any key-value pair.

    IncludeK8sLabelMap, where LabelKey and LabelValue are of the String typeNoEmpty

    Specifies the containers to collect by using a Kubernetes Label (defined in template.metadata) allowlist. To configure the Kubernetes Label allowlist, LabelKey is required and LabelValue is optional.

    • If LabelValue is empty, all containers whose Kubernetes Labels contain the specified LabelKey are matched.

    • If LabelValue is not empty, only containers whose Kubernetes Labels contain LabelKey=LabelValue are matched.

      LabelValue uses exact string matching by default, which means the Kubernetes Label value must be identical to LabelValue. If the value starts with ^ and ends with $, regular expression matching is used. For example, setting LabelKey to app and LabelValue to ^(test1|test2)$ matches containers whose Kubernetes Labels contain app:test1 or app:test2.

    Multiple allowlist entries have an OR relationship. A container is matched if its Kubernetes Labels satisfy any allowlist entry.

    ExcludeK8sLabelMap, where LabelKey and LabelValue are of the String typeNoEmpty

    Specifies the containers to exclude from collection by using a Kubernetes Label (defined in template.metadata) blocklist. To configure the Kubernetes Label blocklist, LabelKey is required and LabelValue is optional.

    • If LabelValue is empty, all containers whose Kubernetes Labels contain the specified LabelKey are excluded.

    • If LabelValue is not empty, only containers whose Kubernetes Labels contain LabelKey=LabelValue are excluded.

      LabelValue uses exact string matching by default, which means the Kubernetes Label value must be identical to LabelValue. If the value starts with ^ and ends with $, regular expression matching is used. For example, setting LabelKey to app and LabelValue to ^(test1|test2)$ matches containers whose Kubernetes Labels contain app:test1 or app:test2.

    Multiple blocklist entries have an OR relationship. A container is excluded if its Kubernetes Labels satisfy any blocklist entry.

    K8sNamespaceRegexStringNoEmpty^(default|nginx)$Specifies the containers to collect by namespace name. Regular expression matching is supported. For example, setting this parameter to ^(default|nginx)$ matches all containers in the nginx and default namespaces.
    K8sPodRegexStringNoEmpty^(nginx-log-demo.*)$Specifies the containers to collect by pod name. Regular expression matching is supported. For example, setting this parameter to ^(nginx-log-demo.*)$ matches all containers in pods whose names start with nginx-log-demo.
    K8sContainerRegexStringNoEmpty^(container-test)$Specifies the containers to collect by container name (the Kubernetes container name is defined in spec.containers). Regular expression matching is supported. For example, setting this parameter to ^(container-test)$ matches all containers named container-test.

    Data processing parameters

    ParameterTypeRequiredDefault valueExampleDescription
    BeginLineRegexStringNoEmpty

    The regular expression used to match the beginning of a line.

    If this parameter is empty, single-line mode is used.

    If the expression matches the beginning of a line, the line is treated as a new log entry. Otherwise, the line is appended to the previous log entry.

    BeginLineCheckLengthIntegerNoEmpty

    The length for matching the beginning of a line. Unit: bytes.

    Default value: 10 × 1024 bytes.

    If the regular expression for matching the beginning of a line can be determined within the first N bytes, set this parameter to improve matching efficiency.

    BeginLineTimeoutMsIntegerNoEmpty

    The timeout period for matching the beginning of a line. Unit: milliseconds.

    Default value: 3000 milliseconds.

    If no new log entry appears within 3000 milliseconds, the matching ends and the last log entry is uploaded to Simple Log Service.

    MaxLogSizeIntegerNoEmpty

    The maximum length of a log entry. Default value: 0. Unit: bytes.

    Default value: 512 × 1024 bytes.

    If the length of a log entry exceeds this value, the system stops searching for the beginning of the next line and directly uploads the log entry.

    ExternalK8sLabelTagMap, in which LabelKey and LabelValue are of the String typeNoEmpty

    After you configure Kubernetes Label tags (defined in template.metadata), iLogtail adds Kubernetes Label-related fields to logs.

    For example, if you set LabelKey to app and LabelValue to k8s_label_app, and the pod contains the label app=serviceA, iLogtail adds the field k8s_label_app: serviceA to the log. If the pod does not contain a label named app, an empty field k8s_label_app: is added.

    ExternalEnvTagMap, in which EnvKey and EnvValue are of the String typeNoEmpty

    After you configure container environment variable tags, iLogtail adds container environment variable-related fields to logs.

    For example, if you set EnvKey to VERSION and EnvValue to env_version, and the container contains the environment variable VERSION=v1.0.0, the information is added to the log as a tag, which means the field env_version: v1.0.0 is added. If the container does not contain an environment variable named VERSION, an empty field env_version: is added.

    Response elements

    Element

    Type

    Description

    Example

    None defined.

    Examples

    Success response

    JSON format

    {}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.