You need to enable JavaScript to run this app.
导航

ModifyRule

最近更新时间2024.03.01 17:59:30

首次发布时间2022.05.11 11:26:48

调用 ModifyRule 接口修改采集配置。

使用说明

创建采集配置之后,LogCollector 会根据下发的采集配置,将指定目录下的日志按照指定规则进行解析并采集、存储到日志服务中。如果日志路径、日志类型等参数有所变化,应及时修改采集规则。
此接口的调用频率限制为 20 次/s,超出频率限制会报错 ExceedQPSLimit。

说明

不支持修改采集配置对应的日志项目和日志主题。

请求说明

  • 请求方式:PUT
  • 请求地址:https://tls-{Region}.ivolces.com/ModifyRule

请求参数

Body

参数类型是否必选示例值描述
RuleIdStringfa******采集配置的 ID。

RuleName

String

testname

采集配置的名称。

  • 在一个 Topic 中唯一。
  • 长度限制为 3~63 个字符,只能包含小写字母、中文、数字和连字符(-),必须以小写字母、中文、数字开头或结尾。

Paths

Array of String

/

采集路径列表。

  • 最多能够创建 10 个采集路径。
  • 采集路径必须指定为绝对路径,暂不支持相对路径。
  • 当 InputType=0 或 InputType=2 时:

    采集路径支持完整匹配和通配符模式匹配,通配符只支持***?,但是最多只能配置 1 个**通配符。
  • 当 InputType=1 时:

    无需配置采集路径列表。

LogType

String

delimiter_log

采集模式。

  • minimalist_log:单行全文模式。
  • json_log:JSON 模式。
  • delimiter_log:分隔符模式。
  • multiline_log:多行全文模式。
  • fullregex_log:完整正则模式。

ExtractRule

Object of ExtractRule

/

日志提取规则。

如果配置非 minimalist_log 或者非 json_log 的采集的日志类型,那么必须同时配置提取规则。

ExcludePaths

Array of ExcludePath

/

采集黑名单列表。

  • 最多支持创建 10 个采集黑名单。
  • 当 InputType=0 或 InputType=2 时:
    • 当 Type 是 Path 时,Value 表示一个目录。支持完整匹配和通配符模式匹配,通配符只支持“*?,不支持**通配符。
    • 当 Type 是 File 时,Value 表示一个文件名称。支持完整匹配和通配符模式匹配,通配符只支持***?,但是最多只能配置 1 个**通配符。
  • 当 InputType=1 时:

    不允许配置采集黑名单列表。

LogSample

String

/

日志样例。

  • 日志样例的长度最大为 3000 个字符。
  • 日志样例的内容必须匹配采集模式。
    • 单行全文模式和 JSON 模式可以不填写日志样例。
    • 其他模式必须填写日志样例,并且日志样例的内容必须匹配采集模式。
UserDefineRuleObject of UserDefineRule/用户自定义的采集规则。

InputType

Integer

2

采集类型。

  • 0:宿主机日志文件。
  • 1:K8s 容器标准输出。
  • 2:K8s 容器内日志文件。
ContainerRuleObject of ContainerRule/容器采集规则。

Pause

Integer

1

是否暂停采集配置。

  • 1: 暂定采集配置。
  • 0:不暂停采集配置。

ServiceAlias

String

服务别名
仅用于收编vke的采集配置:

ExtractRule

参数类型是否必选示例值描述

Keys

Array of String

[
"time",
"",
"level",
"msg"
]

日志字段名称(Key)列表。

  • 当且仅当 LogType 为 delimiter_log 或 fullregex_log 时有效。
  • 支持配置最多 100 个字段名称。
  • 当 LogType 为 delimiter_log时,不能配置重复的名字段名称,不能指定全部字段名称为空。
  • 当 LogType 为 fullregex_log 时,不能配置重复的名字段名称,不能指定字段名称为空。
QuoteString"引用符。被引用符包裹的内容不会被分隔而是会被解析为一个完整的字段。当且仅当 LogType 为 delimiter_log 时有效。

TimeKey

String

request_time

日志时间字段的字段名称。如果将日志中的指定时间字段作为日志时间戳,则需要填写 TimeKey 和 TimeFormat。

TimeKey 和 TimeFormat 必须成对出现。

LogRegex

String

[(\d+-\d+-\w+:\d+:\d+,\d+)]\s[(\w+)]\s(.*)

整条日志需要匹配的正则表达式。

  • 当且仅当采集的日志类型为 fullregex_log 时有效。
  • 必须是合法的正则表达式。
DelimiterString#日志分隔符。当且仅当 LogType 为 delimiter_log 时有效。

BeginRegex

String

[(\d+-\d+-\w+:\d+:\d+,\d+)]\s[(\w+)]\s(.*)

第一行日志需要匹配的正则表达式。

  • 当且仅当 LogType 为 multiline_log 或 fullregex_log 时有效。
  • 必须是合法的正则表达式。

TimeFormat

String

%Y-%m-%dT%H:%M:%S,%f

时间字段的解析格式。如果将日志中的指定时间字段作为日志时间戳,则需要填写 TimeKey 和 TimeFormat。

  • TimeKey 和 TimeFormat 必须成对出现。
  • 如何配置时间格式,请参考时间格式
LogTemplateObject of LogTemplate{ "Type": "Nginx", "Format": "format main '$remote_addr - $remote_user [$time_local] \"$request\" $request_time $request_length $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\"';" }根据指定的日志模板自动提取日志字段。

UnMatchLogKey

String

LogParseFailed

当上传解析失败的日志时,解析失败的日志的 key 名称。

UnMatchUpLoadSwitch=true 和 UnMatchLogKey 必须成对出现。

FilterKeyRegex

Array of FilterKeyRegex

/

过滤规则列表。

  • 当 LogType 为 minimalist_log 或 multiline_log 时,最多能够配置 1 条过滤规则,并且过滤字段的名字 key 必须为 content
  • 当 LogType 为 delimiter_log、json_log 或 fullregex_log 时,最多能够配置 5 条过滤规则,并且过滤字段的名字 key 不能重复、不能为空。过滤字段的日志内容需要匹配的正则表达式必须是合法的正则表达式,并且长度限制为 256 个字符。

UnMatchUpLoadSwitch

Boolean

true

是否上传解析失败的日志。UnMatchUpLoadSwitch=true 和 UnMatchLogKey 必须成对出现。

  • true:上传解析失败的日志。
  • false:不上传解析失败的日志。

ExcludePath

参数类型是否必选示例值描述

Type

String

Path

采集路径类型。

  • File:文件名称
  • Path:目录

Value

String

/accesslog

采集路径。必须指定为绝对路径。

  • 当 Type 是 Path 时,Value 表示一个目录。
  • 当 Type 是 File 时,Value 表示一个文件名称。

UserDefineRule

参数类型是否必选示例值描述

Fields

JSON Map

{"ClusterID":"dabaad5f-7a10-4771-b3ea-d821f73e****"}

为日志添加常量字段。常量字段需遵循以下限制:

  • 支持上传最多 5 个常量字段。
  • 字段名(Key)不可重复,不可为空。长度限制为 1~128 字符,包括英文字母、数字、和特殊字符(-_./),且不能以下划线开头。
  • 字段值(Value)不可为空,长度最大为 512 KiB。
PluginObject of Plugin{"processors":[{"json":{"field":"__content__","trim_keys":{"mode":"all","chars":"#"},"trim_values":{"mode":"all","chars":"#"},"allow_overwrite_keys":true,"allow_empty_values":true}LogCollector 插件配置。启用插件配置之后,可以添加一个或多个 LogCollector 处理器插件,解析结构复杂或不固定的日志。
AdvancedObject of Advanced{ "CloseInactive": 10 }LogCollector 扩展配置。

RawLogKey

String

raw

原始日志字段名称。

仅在 EnableRawLog 设置为 true 时生效,RawLogKey 默认为 __raw__,表示原始的日志数据将被封装在 __raw__ 字段中,和解析后的日志数据一起上传到日志服务中。

TailFiles

Boolean

true

LogCollector 采集策略,即指定 LogCollector 采集增量日志还是全量日志。默认为 false,表示采集全量日志。

  • true:增量采集。LogCollector 采集日志时,只采集文件内新增的内容。监控范围内的日志文件写入新的日志时,触发 LogCollector 日志采集行为。对于首次采集的日志文件:
    • 如果新文件不超过 1024 KiB,从新文件的起始位置开始首次采集。
    • 如果新文件大于 1024 KiB,从新文件的末尾位置开始首次采集,即仅采集增量日志。
  • false:(默认)全量采集。LogCollector 从每个文档的起始位置开始采集日志,此时 LogCollector 会采集历史日志数据。

HostnameKey

String

hostname

hostname 字段名称。

仅在 EnableHostname 为 true 时需要设置。

EnableRawLog

Boolean

true

是否上传原始日志。

  • true:上传原始日志。
  • false:(默认)不上传原始日志。

ShardHashKey

Object of ShardHashKey

{ "HashKey": "3C" }

路由日志分区的规则。

  • 未设置此参数,表示使用默认的负载均衡模式写入日志,将数据包写入当前可用的任一 Shard 中。
  • 设置此参数表示采集日志时使用 HashKey 路由 Shard 模式,日志服务会将数据写入到包含指定 Key 值的 Shard 中。

ParsePathRule

Object of ParsePathRule

{ "PathSample": "/data/nginx/log/dabaad5f-7a10/tls/app.log", "Regex": "\\/data\\/nginx\\/log\\/(\\w+)-(\\w+)\\/tls\\/app\\.log", "Keys": ["instance-id", "pod-name"] }

解析采集路径的规则。设置规则后,将通过规则中指定的正则表达式提取采集路径中的字段,并将其作为元数据添加到日志数据中。

说明

采集容器标准输出时,不支持指定该参数。

EnableHostname

Boolean

true

是否上传 hostname 字段,默认为关闭状态。

  • true:在原始日志中增加一个字段,用于记录日志源的 hostname。此时应通过 HostnameKey 指定 hostname 字段名。
  • false:(默认)不添加 hostname 字段。

ContainerRule

参数类型是否必选示例值描述

EnvTag

JSON Map

{
            "Key1": "Value1",
            "Key2": "Value2"
        }

是否将环境变量作为日志标签,添加到原始日志数据中。开启后,日志服务将在日志中新增容器环境变量相关字段,设置多个键值对时,表示添加多个字段。 例如设置 Key 为 source,设置 Value为data_source,假设容器包含环境变量 source=DC,那么将在日志中新增字段 __tag__data_source__: DC

Stream

String

all

采集模式。

  • stdout:采集容器标准输出 stdout。
  • stderr:采集容器标准错误 stderr。
  • all:同时采集容器标准输出 stdout 和容器标准错误 stderr。
KubernetesRuleObject of KubernetesRule{ "NamespaceNameRegex": ".*test.*", "WorkloadType": "Deployment", "WorkloadNameRegex": ".*test.*", "IncludePodLabelRegex": { "Key1": "Value1", "Key2": "Value2" }, "ExcludePodLabelRegex": { "Key1": "Value1", "Key2": "Value2" }, "PodNameRegex": ".*test.*", "LabelTag": { "Key1": "Value1", "Key2": "Value2" } }Kubernetes 容器的采集规则。
ContainerNameRegexString.*test.*待采集的容器名称。若未指定容器名称,表示采集机器组中全部容器。 支持正则匹配,例如设置容器名称为 ^(container-test)$,表示采集所有名称为 container-test 的容器。

ExcludeContainerEnvRegex

JSON Map

{
            "Key1": "Value1",
            "Key2": "Value2"
        }

容器环境变量黑名单用于指定不采集的容器范围,不启用黑名单时表示采集全部容器。 如果启用容器环境变量黑名单,则 Key 必选,Value 可选。

  • Value 为空,表示不采集所有在容器环境变量中包含 Key 的容器。

  • Value 不为空,表示采集时只排除匹配键值对的容器,即只排除在容器环境变量中包含 Key、并且其值匹配 Value 的容器。 Value 支持正则匹配,例如设置 Key 为 module,设置 Value 为 ^(tcp|udp)$,表示不采集在容器环境变量中包含 module:tcp、module:udp 的容器。

  • 多个 Key-Value 对之间的逻辑关系为逻辑,即容器环境变量只要符合任一键值对,就会被排除出采集范围。

  • 启用容器环境变量黑名单时,Key 不能重复。

IncludeContainerEnvRegex

JSON Map

{
            "Key1": "Value1",
            "Key2": "Value2"
        }

容器环境变量白名单通过容器环境变量指定待采集的容器,不启用白名单时表示指定采集全部容器。 启用容器环境变量的白名单时,需要填写键值对。其中 Key 必选,Value 可选。

  • Value 为空:采集所有在容器环境变量中包含 Key 的容器。

  • Value 不为空:只采集在容器环境变量中包含 Key 并且其值匹配 Value 的容器。 Value 支持正则匹配。例如设置 Key 为 module,设置 Value 为 ^(tcp|udp)$,表示只采集在容器环境变量中包含 module:tcp、module:udp 的容器。

  • 多个 Key-Value 对之间的逻辑关系为逻辑,即容器环境变量只要符合任一 Key-Value 对就会被列为采集范围。

  • 启用容器环境变量白名单时,Key 不能重复。

ExcludeContainerLabelRegex

JSON Map

{
            "Key1": "Value1",
            "Key2": "Value2"
        }

容器 Label 黑名单用于指定不采集的容器范围,不启用黑名单时表示采集全部容器。 如果启用容器 Label 黑名单,则 Key 必选,Value 可选。

  • Value 为空,表示不采集所有在容器 Label 中包含 Key 的容器。

  • Value 不为空,表示采集时只排除匹配键值对的容器,即只排除在容器 Label 中包含 Key、并且其值匹配 Value 的容器。 Value支持正则匹配,例如设置 Key 为 app,设置 Value 为 ^(test1|test2)$,表示不采集在容器 Label 中包含 app:test1、app:test2 的容器。

  • 多个 Key-Value 对之间的逻辑关系为逻辑,即容器 Label 只要符合任一键值对,就会被排除出采集范围。

  • 启用容器 Label 黑名单时,Key不能重复。

IncludeContainerLabelRegex

JSON Map

{
            "Key1": "Value1",
            "Key2": "Value2"
        }

容器 Label 白名单通过容器 Label 指定待采集的容器,不启用白名单时指定采集全部容器。 启用容器 Label 的白名单时,需要填写键值对。其中 Key 必选,Value 可选。

  • Value 为空:采集所有在容器 Label 中包含 Key 的容器。

  • Value 不为空:只采集在容器 Label 中包含 Key 并且其值匹配 Value 的容器。 Value 支持正则匹配。例如设置Key 为 app,设置 Value 为 ^(test1|test2)$,表示只采集在容器 Labe l中包含 app:test1、app:test2 的容器。

  • 多个 Key-Value 对之间的逻辑关系为逻辑,即容器 Label 只要符合任一 Key-Value 对就会被列为采集范围。

  • 启用容器 Label 白名单时,Key 不能重复。

LogTemplate

参数类型是否必选示例值描述

Type

String

Nginx

日志模板的类型。支持如下类型:

  • Nginx:Nginx类型的日志模板。
FormatStringlog_format main '$remote_addr - $remote_user [$time_local] "$request" $request_time $request_length $status $body_bytes_sent "$http_referer" "$http_user_agent"';日志模板的格式。

FilterKeyRegex

参数类型是否必选示例值描述
KeyString__content__过滤字段的名称。
RegexString.*ERROR.*过滤字段的日志内容需要匹配的正则表达式。

Plugin

参数类型是否必选示例值描述

processors

Array of JSON Map

{
            "processors":[
                {
                    "json":{
                        "field":"__content__",
                        "trim_keys":{
                            "mode":"all",
                            "chars":"#"
                        },
                        "trim_values":{
                            "mode":"all",
                            "chars":"#"
                        },
                        "allow_overwrite_keys":true,
                        "allow_empty_values":true
                    }
                }
            ]
        }

LogCollector 插件。支持的插件列表及参数说明请参考 LogCollector 插件概述

Advanced

参数类型是否必选示例值描述
CloseEOFBooleantrue读取至日志文件的末尾之后,是否释放该日志文件的句柄。默认为 false。
CloseRemovedBooleantrue日志文件被移除之后,是否释放该日志文件的句柄。默认为 false。
CloseRenamedBooleantrue日志文件被重命名之后,是否释放该日志文件的句柄。默认为 false。

CloseTimeout

Integer

1800

LogCollector 监控日志文件的最大时长。单位为秒,默认为0秒,表示不限制 LogCollector 监控日志文件的时长。

LogCollector 开始监控日志文件时开始计时,超出指定时长后,无论日志文件是否读取完毕,立即释放该日志文件的句柄,结束监控。

CloseInactive

Integer

10

释放日志文件句柄的等待时间。当日志文件超过指定时间仍然没有写入新的日志时,释放该日志文件的句柄。

单位为秒,取值范围为 1~300 秒,默认为 60 秒。

ShardHashKey

参数类型是否必选示例值描述
HashKeyString3C日志组的 HashKey,用于指定当前日志组要写入的分区(Shard)。此参数的取值范围为 [00000000000000000000000000000000-ffffffffffffffffffffffffffffffff)。

ParsePathRule

参数类型是否必选示例值描述

Keys

Array of String

["instance-id","pod-name"]

字段名称列表。 日志服务会根据正则表达式(Regex)将路径样例(PathSample)解析为多个字段,Keys 用于指定每个字段的字段名称。

  • 最多配置 100 个字段名。
  • 字段名不可为空,且不可重复。
RegexString/var/logs/([a-z]*)_any_([a-z]*)/test.log用于提取路径字段的正则表达式。必须和采集路径样例匹配,否则无法成功提取。

PathSample

String

/var/logs/instanceid_any_podname/test.log

实际场景的采集路径样例。

  • 采集路径样例必须是一个绝对路径。
  • 路径样例中不能包含通配符*?**

KubernetesRule

参数类型是否必选示例值描述

LabelTag

JSON Map

{
                "Key1": "Value1",
                "Key2": "Value2"
            }

是否将 Kubernetes Label 作为日志标签,添加到原始日志数据中。开启后,日志服务将在日志中新增 Kubernetes Pod Label 相关字段。设置多个键值对时,表示添加多个字段。 例如设置 Key 为 source,设置 Value 为 data_source,假设 Pod 包含 Labelsource=DC,那么将在日志中新增字段 __tag__data_source__: DC

PodNameRegexString.*test.*Pod名称用于指定待采集的容器。不指定 Pod 名称时,表示采集全部容器。 Pod名称支持正则匹配,例如设置 Pod 名称为 ^(http.*)$,表示采集以 http 开头的 Pod 下面的所有容器。

WorkloadType

String

Deployment

通过工作负载的类型指定采集的容器,仅支持选择一种类型。未指定类型时,表示采集全部类型的容器。 支持的工作负载类型如下:

  • Deployment:无状态负载
  • StatefulSet:有状态负载
  • DaemonSet:守护进程
  • Job:任务
  • CronJob:定时任务
AnnotationTagJSON Map{ "Key1": "Value1", "Key2": "Value2" }是否将 Kubernetes Annotation 作为日志标签,添加到原始日志数据中。开启后,日志服务将在日志中新增 Kubernetes Pod Annotation 相关字段。设置多个键值对时,表示添加多个字段。例如设置 Key 为 sink,设置 Value 为 data_sink,假设 Pod 包含 Annotation sink=ck,那么将在日志中新增字段 __tag__data_sink__: ck
WorkloadNameRegexString.*test.*通过工作负载的名称指定待采集的容器。未指定工作负载名称时,表示采集全部容器。 工作负载名称支持正则匹配。例如设置工作负载名称为 ^(http.*)$,表示采集以 http 开头的工作负载下面的所有容器。
NamespaceNameRegexString.*test.*待采集的 Kubernetes Namespace 名称,不指定 Namespace 名称时表示采集全部容器。 Namespace 名称支持正则匹配。例如设置 Namespace 名称为 ^(tcp|udp)$,表示采集 tcp 命名空间、udp 命名空间下面的所有容器。

ExcludePodLabelRegex

JSON Map

{
                "Key1": "Value1",
                "Key2": "Value2"
            }

通过 Pod Label 黑名单指定不采集的容器,不启用表示采集全部容器。 如果需要设置 Pod Label 黑名单,则 Key 必填,Value 选填。

  • Value 为空,表示采集时排除所有在 Pod Label 中包含 Key 的容器。
  • Value 不为空,表示采集时只排除在 Pod Label 中包含 Key 并且其值匹配 Value 的容器。 Value 支持正则匹配,例如设置 Key 为 module,设置 Value 为 ^(tcp|udp)$,表示不采集在 Pod Label 中包含 module:tcp、module:udp 的容器。

说明

  • 多个 Key-Value 对之间的逻辑关系为逻辑,即 Pod Label 只要符合任一键值对,就会被排除出采集范围。
  • 启用 Pod Label 黑名单时,Key 不能重复。

IncludePodLabelRegex

JSON Map

{
                "Key1": "Value1",
                "Key2": "Value2"
            }

Pod Label 白名单用于指定待采集的容器。未开启 Pod Label 白名单时,表示采集全部容器。 如果需要设置 Pod Label 白名单,则 Key 必填:

  • Value 为空,表示采集所有在 Pod Label 中包含 Key 的容器。
  • Value 不为空,表示只采集在 Pod Label 中包含 Key 并且其值匹配 Value 的容器,支持正则匹配。 Value 支持正则匹配,例如设置 Key 为 module,设置 Value 为 ^(tcp|udp)$,表示只采集在 Pod Label 中包含 module:tcp、module:udp 的容器。

说明

  • 多个 Key-Value 对之间的逻辑关系为逻辑,即 Pod Label 只要符合任一键值对,就会被列为采集范围。
  • 启用 Pod Label 白名单时,Key 不能重复。

返回参数

请求示例

以单行全文模式为例。

PUT https://tls-{Region}.ivolces.com/ModifyRule HTTP/1.1
Content-Type: application/json; charset=utf-8
{
    "RuleId": "4a9**************",
    "RuleName": "testname",
    "Paths": [
        "/data/nginx/log/*/*/*.log"
    ],
    "ExcludePaths": [
        {
            "Type": "File",
            "Value": "/data/nginx/log/*/*/exclude.log"
        },
        {
            "Type": "Path",
            "Value": "/data/nginx/log/*/exclude/"
        }
    ],
    "LogType": "minimalist_log",
    "ExtractRule": {
        "FilterKeyRegex": [
            {
                "Key": "__content__",
                "Regex": ".*ERROR.*"
            }
        ]
    },
    "LogSample": "2018-05-22 15:35:53.850 INFO XXXX",
    "UserDefineRule": {
        "ParsePathRule": {
            "PathSample": "/data/nginx/log/dabaad5f-7a10/tls/app.log",
            "Regex": "\\/data\\/nginx\\/log\\/(\\w+)-(\\w+)\\/tls\\/app\\.log",
            "Keys": [
                "instance-id",
                "pod-name"
            ]
        },
        "ShardHashKey": {
            "HashKey": "3C"
        },
        "EnableRawLog": true,
        "RawLogKey": "raw",
        "Fields": {
            "ClusterID": "dabaad5f-7a10-4771-b3ea-d821f73e****"
        },
        "Advanced": {
            "CloseInactive": 10
        }
    }
}

返回示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{}

错误码

更多信息,请参考通用错误码

状态码错误码错误信息说明
400InvalidArgumentInvalid argument key %s, value %s, please check argument参数不合法。
400PathQuotaExceedPath Quota Exceeded超过采集路径限额。
400ExcludePathQuotaExceedExclude Path Quota Exceeded超过采集黑名单限额。
400ExtractRuleKeyQuotaExceedExtractRule Key Quota Exceeded超过提取规则的用户自定义的字段限额。
400ExtractRuleFilterKeyRegexQuotaExceedExtractRule FilterKeyRegex Quota Exceeded超过提取规则的过滤规则限额。
404RuleNotExistRule %s does not exist采集配置不存在。
409RuleAlreadyExistRule %s already exist采集配置已存在。
500InternalServerErrorWe encountered an unexpected server error, please try again later.服务器内部错误。