数据转换类插件配置方法与示例-日志服务-阿里云

数据转换类插件用于将原始日志进行格式转换、IP地理化、日志转指标/链路等场景。

数据安全插件概览

日志服务提供以下多种类型的数据转换类插件，请按需要进行选择。

插件名称	类型	功能说明
转换IP地址	拓展	将IP转为地理位置（国家/省/市/经纬度）
Log转为Metric	拓展	将日志转换为SLS指标数据
Log转为Trace	拓展	将日志转换为SLS链路追踪数据

功能入口

当您需要使用Logtail插件处理日志时，您可以在创建或修改Logtail配置时，添加插件。具体操作，请参见处理插件概述。

转换IP地址插件

使用processor_geoip插件将日志中的IP地址转换为地理位置（国家、省份、城市、经纬度）。此处介绍processor_geoip插件的参数说明和配置示例。

配置说明

说明

Logtail安装包中没有GeoIP数据库，需要手动下载GeoIP数据库到Logtail所在服务器并配置，建议下载精确到City粒度的数据库。更多信息，请参见MaxMind GeoLite2。
请确保数据库格式为MMDB类型。
表单配置方式：采集文本日志和容器标准输出时可用。
JSON配置方式：采集文本日志时不可用。

表单配置方式

参数说明

配置处理器类型为转换IP地址，相关参数说明如下表所示。

参数	说明
原始字段	待进行IP地址转换的原始字段名。
GeoIP数据库路径	GeoIP数据库的全路径。例如`/user/data/GeoLite2-City_20180102/GeoLite2-City.mmdb`。
保留原始字段	选中该选项后，解析后的日志中将保留原始字段。
原始字段缺失报错	选中该选项后，如果原始日志中无您所指定的原始字段，系统将报错。
解析失败报错	选中该选项后，如果IP地址无效或在数据库中未匹配到该IP地址，系统将报错。
语言	语言属性。默认值为zh-CN。重要请确保您的GeoIP数据库中包含对应的语言。

配置示例

将日志中的IP地址转换成对应的地理位置，示例如下：

原始日志
```
"source_ip" : "**.**.**.**"
```
Logtail插件处理配置

处理结果

"source_ip" : "**.**.**.**"
"source_ip_province_" : "浙江省"
"source_ip_city_" : "杭州"
"source_ip_province_code_" : "ZJ"
"source_ip_country_code_" : "CN"
"source_ip_longitude_" : "120.********"
"source_ip_latitude_" : "30.********"

JSON配置方式

参数说明

配置type为processor_geoip，detail说明如下表所示。

参数	类型	是否必选	说明
SourceKey	String	是	待进行IP地址转换的原始字段名。
DBPath	String	是	GeoIP数据库的全路径。例如/user/data/GeoLite2-City_20180102/GeoLite2-City.mmdb。
NoKeyError	Boolean	否	原始日志中无您所指定的原始字段名时，系统是否报错。 true：报错。 false（默认值）：不报错。
NoMatchError	Boolean	否	IP地址无效或在数据库中未匹配到该IP地址时，系统是否报错。 true（默认值）：报错。 false：不报错。
KeepSource	Boolean	否	解析后的日志中，是否保留原始字段。 true（默认值）：保留。 false：不保留。
Language	String	否	语言属性。默认值为zh-CN。重要请确保您的GeoIP数据库中包含对应的语言。

配置示例

将日志中的IP地址转换成对应的地理位置，示例如下：

原始日志
```
"source_ip" : "**.**.**.**"
```

Logtail插件处理配置

{
   "type": "processor_geoip",
    "detail": {
         "SourceKey": "source_ip",
         "NoKeyError": true,
         "NoMatchError": true,
         "KeepSource": true,
         "DBPath" : "/user/local/data/GeoLite2-City_20180102/GeoLite2-City.mmdb"
    }
}

处理结果

"source_ip" : "**.**.**.**"
"source_ip_city_" : "杭州"
"source_ip_province_code_" : "ZJ"
"source_ip_country_code_" : "CN"
"source_ip_longitude_" : "120.********"
"source_ip_latitude_" : "30.********"

Log转为Metric插件

使用processor_log_to_sls_metric插件将采集到的日志转成SLS Metric。此处介绍processor_log_to_sls_metric插件的参数说明和配置示例。

配置说明

重要

Logtail 1.7.1及以上版本支持processor_log_to_sls_metric插件。

表单配置方式

配置处理器类型为Log转Metric，相关参数说明如下表所示。

参数说明

参数	说明
MetricTimeKey	指定日志中的时间字段，该字段将与时序数据中的`__time_nano__` 字段映射。默认提取日志中`__time__`字段的值。确保指定的字段是合法的、符合格式的时间戳。目前支持以second（10位长度）、millisecond（13位长度）、microsecond（16位长度）、nanosecond（19位长度）为单位的Unix时间戳。
MetricLabelKeys	指定`__labels__`字段的Key列表，Key需遵循正则表达式 `^[a-zA-Z_][a-zA-Z0-9_]*$`。Value不能包含竖线（\|）和 `#$#`。更多信息，请参见时序数据（Metric）。不支持在MetricLabelKeys参数中添加`__labels__`字段。如果原始字段中存在 `__labels__` 字段，该值将被追加到新的`__labels__`字段中。
MetricValues	用于指定Metric名称和Metric值。 Metric名称对应`__name__`字段，需遵循正则表达式`^[a-zA-Z_:][a-zA-Z0-9_:]*$`。 Metric值对应`__value__`字段，需为Double类型。更多信息，请参见时序数据（Metric）。
CustomMetricLabels	自定义的`__labels__`字段， Key需遵循正则表达式 `^[a-zA-Z_][a-zA-Z0-9_]*$`，Value不能包含竖线（\|）和 `#$#`。更多信息，请参见时序数据（Metric）。
IgnoreError	当没有匹配日志时是否输出Error日志。

配置示例

原始日志

{
    "script_md5":"8c6aebe9****c27f",
    "remote_addr":"123.XX.XX.123",
    "remote_user":"-",
    "time_local":"15/Aug/2023:12:03:20",
    "method":"GET",
    "url":"/www.a.com",
    "protocol":"HTTP/1.1",
    "status":"404",
    "body_bytes_sent":"4146",
    "http_referer":"-",
    "http_user_agent":"curl/7.74.0",
    "http_x_forwarded_for":"-",
    "__labels__":"field1#$#field1|field2#$#field2|tag1#$#tag1|tag2#$#tag2",
    "body_bytes_sent_name":"body_bytes_sent",
    "status_name":"status",
    "httptime":"1692101000",
    "__time__":"1692101000"
}

Logtail插件处理配置

处理结果

第一条时序数据

{
    "__labels__":"field1#$#field1|field2#$#field2|method#$#GET|nginx#$#test|tag1#$#tag1|tag2#$#tag2|url#$#/www.a.com",
    "__name__":"body_bytes_sent",
    "__value__":"4146",
    "__time_nano__":"1692101000000000000",
    "__time__":"1692101000"
}

第二条时序数据

{
    "__labels__":"field1#$#field1|field2#$#field2|method#$#GET|nginx#$#test|tag1#$#tag1|tag2#$#tag2|url#$#/www.a.com",
    "__name__":"status",
    "__value__":"404",
    "__time_nano__":"1692101000000000000",
    "__time__":"1692101000"
}

JSON配置方式

配置type为processor_log_to_sls_metric，detail说明如下表所示。

参数说明

参数	类型	是否必选	说明
MetricTimeKey	String	否	指定日志中的时间字段，该字段将与时序数据中的`__time_nano__` 字段映射。默认提取日志中`__time__`字段的值。确保指定的字段是合法的、符合格式的时间戳。目前支持以second（10位长度）、millisecond（13位长度）、microsecond（16位长度）、nanosecond（19位长度）为单位的Unix时间戳。
MetricLabelKeys	[]String	是	指定`__labels__`字段的Key列表，Key需遵循正则表达式 `^[a-zA-Z_][a-zA-Z0-9_]*$`。Value不能包含竖线（\|）和 `#$#`。更多信息，请参见时序数据（Metric）。不支持在MetricLabelKeys参数中添加`__labels__`字段。如果原始字段中存在 `__labels__` 字段，该值将被追加到新的`__labels__`字段中。
MetricValues	Map	是	用于指定Metric名称和Metric值。 Metric名称对应`__name__`字段，需遵循正则表达式`^[a-zA-Z_:][a-zA-Z0-9_:]*$`。 Metric值对应`__value__`字段，需为Double类型。更多信息，请参见时序数据（Metric）。
CustomMetricLabels	Map	否	自定义的`__labels__`字段， Key需遵循正则表达式 `^[a-zA-Z_][a-zA-Z0-9_]*$`，Value不能包含竖线（\|）和 `#$#`。更多信息，请参见时序数据（Metric）。
IgnoreError	Boolean	否	当没有匹配日志时是否输出Error日志。默认值为false，表示不输出。

配置示例

原始日志

{
    "script_md5":"8c6aebe9****c27f",
    "remote_addr":"123.XX.XX.123",
    "remote_user":"-",
    "time_local":"15/Aug/2023:12:03:20",
    "method":"GET",
    "url":"/www.a.com",
    "protocol":"HTTP/1.1",
    "status":"404",
    "body_bytes_sent":"4146",
    "http_referer":"-",
    "http_user_agent":"curl/7.74.0",
    "http_x_forwarded_for":"-",
    "__labels__":"field1#$#field1|field2#$#field2|tag1#$#tag1|tag2#$#tag2",
    "body_bytes_sent_name":"body_bytes_sent",
    "status_name":"status",
    "httptime":"1692101000",
    "__time__":"1692101000"
}

Logtail插件处理配置

{
    "processors":[
        {
            "detail":{
                "CustomMetricLabels":{
                    "nginx":"test"
                },
                "IgnoreError":false,
                "MetricLabelKeys":[
                    "url",
                    "method"
                ],
                "MetricTimeKey":"httptime",
                "MetricValues":{
                    "body_bytes_sent_name":"body_bytes_sent",
                    "status_name":"status"
                }
            },
            "type":"processor_log_to_sls_metric"
        }
    ]
}

处理结果

第一条时序数据

{
    "__labels__":"field1#$#field1|field2#$#field2|method#$#GET|nginx#$#test|tag1#$#tag1|tag2#$#tag2|url#$#/www.a.com",
    "__name__":"body_bytes_sent",
    "__value__":"4146",
    "__time_nano__":"1692101000000000000",
    "__time__":"1692101000"
}

第二条时序数据

{
    "__labels__":"field1#$#field1|field2#$#field2|method#$#GET|nginx#$#test|tag1#$#tag1|tag2#$#tag2|url#$#/www.a.com",
    "__name__":"status",
    "__value__":"404",
    "__time_nano__":"1692101000000000000",
    "__time__":"1692101000"
}

Log转为Trace插件

使用processor_otel_trace插件将采集到的日志转成SLS Trace。此处介绍processor_otel_trace插件的参数说明和配置示例。

配置说明

重要

Logtail 1.7.1及以上版本支持processor_otel_trace插件。

表单配置方式

配置处理器类型为Log转Trace，相关参数说明如下表所示。

参数说明

参数	说明
SourceKey	原始字段名。
Format	转换后的格式，可选值： protobuf json protojson
NoKeyError	当日志中没有对应的原始字段时，是否报错。默认值为false。
TraceIDNeedDecode	是否对TraceID进行Base64解码，默认值为false。设置Format为protojson时，如果TraceID已进行过Base64编码，则需要设置TraceIDNeedDecode为true，否则将导致转换失败。
SpanIDNeedDecode	是否对SpanID进行Base64解码。默认值为false。设置Format为protojson时，如果SpanID已进行过Base64编码，则需要设置SpanIDNeedDecode为true，否则将导致转换失败。
ParentSpanIDNeedDecode	是否对ParentSpanID进行Base64解码。默认值为false。设置Format为protojson时，如果ParentSpanID已进行过Base64编码，则需要设置ParentSpanIDNeedDecode为true，否则将导致转换失败。

配置示例

原始日志

INFO OtlpJsonLoggingSpanExporter - {"resource":{"attributes":[]},"scopeSpans":[{"scope":{"name":"io.opentelemetry.spring-webmvc-3.1","version":"1.26.0-alpha","attributes":[]},"spans":[{"traceId":"a7adbcb0921fa4a5b90615d0ad38ef95","spanId":"eecaa7e1b63c9f61","parentSpanId":"fa85fcee7fe0e0e8","name":"HelloWorldController.sayHello","kind":1,"startTimeUnixNano":"1696659118615748056","endTimeUnixNano":"1696659128701715998","attributes":[{"key":"thread.id","value":{"intValue":"48"}},{"key":"thread.name","value":{"stringValue":"http-nio-18080-exec-1"}}],"events":[],"links":[],"status":{}}]},{"scope":{"name":"io.opentelemetry.tomcat-7.0","version":"1.26.0-alpha","attributes":[]},"spans":[{"traceId":"a7adbcb0921fa4a5b90615d0ad38ef95","spanId":"fa85fcee7fe0e0e8","name":"GET /hello","kind":2,"startTimeUnixNano":"1696659118479360000","endTimeUnixNano":"1696659128703706165","attributes":[{"key":"http.status_code","value":{"intValue":"200"}},{"key":"user_agent.original","value":{"stringValue":"curl/7.84.0"}},{"key":"net.host.name","value":{"stringValue":"localhost"}},{"key":"http.response_content_length","value":{"intValue":"12"}},{"key":"http.target","value":{"stringValue":"/hello"}},{"key":"net.sock.peer.addr","value":{"stringValue":"127.0.0.1"}},{"key":"net.host.port","value":{"intValue":"18080"}},{"key":"net.sock.peer.port","value":{"intValue":"53649"}},{"key":"thread.id","value":{"intValue":"48"}},{"key":"thread.name","value":{"stringValue":"http-nio-18080-exec-1"}},{"key":"http.route","value":{"stringValue":"/hello"}},{"key":"net.sock.host.addr","value":{"stringValue":"127.0.0.1"}},{"key":"net.protocol.name","value":{"stringValue":"http"}},{"key":"net.protocol.version","value":{"stringValue":"1.1"}},{"key":"http.scheme","value":{"stringValue":"http"}},{"key":"http.method","value":{"stringValue":"GET"}}],"events":[],"links":[],"status":{}}]}],"schemaUrl":"https://opentelemetry.io/schemas/1.19.0"}

Logtail插件处理配置
处理结果

JSON配置方式

配置type为processor_otel_trace，detail说明如下表所示。

参数说明

参数	类型	是否必选	说明
SourceKey	String	是	原始字段名。
Format	String	是	转换后的格式，可选值：protobuf、json、protojson。
NoKeyError	Boolean	否	当日志中没有对应的原始字段时，是否报错。默认值为false。
TraceIDNeedDecode	Boolean	否	是否对TraceID进行Base64解码，默认值为false。设置Format为protojson时，如果TraceID已进行过Base64编码，则需要设置TraceIDNeedDecode为true，否则将导致转换失败。
SpanIDNeedDecode	Boolean	否	是否对SpanID进行Base64解码。默认值为false。设置Format为protojson时，如果SpanID已进行过Base64编码，则需要设置SpanIDNeedDecode为true，否则将导致转换失败。
ParentSpanIDNeedDecode	Boolean	否	是否对ParentSpanID进行Base64解码。默认值为false。设置Format为protojson时，如果ParentSpanID已进行过Base64编码，则需要设置ParentSpanIDNeedDecode为true，否则将导致转换失败。

配置示例

原始日志

INFO OtlpJsonLoggingSpanExporter - {"resource":{"attributes":[]},"scopeSpans":[{"scope":{"name":"io.opentelemetry.spring-webmvc-3.1","version":"1.26.0-alpha","attributes":[]},"spans":[{"traceId":"a7adbcb0921fa4a5b90615d0ad38ef95","spanId":"eecaa7e1b63c9f61","parentSpanId":"fa85fcee7fe0e0e8","name":"HelloWorldController.sayHello","kind":1,"startTimeUnixNano":"1696659118615748056","endTimeUnixNano":"1696659128701715998","attributes":[{"key":"thread.id","value":{"intValue":"48"}},{"key":"thread.name","value":{"stringValue":"http-nio-18080-exec-1"}}],"events":[],"links":[],"status":{}}]},{"scope":{"name":"io.opentelemetry.tomcat-7.0","version":"1.26.0-alpha","attributes":[]},"spans":[{"traceId":"a7adbcb0921fa4a5b90615d0ad38ef95","spanId":"fa85fcee7fe0e0e8","name":"GET /hello","kind":2,"startTimeUnixNano":"1696659118479360000","endTimeUnixNano":"1696659128703706165","attributes":[{"key":"http.status_code","value":{"intValue":"200"}},{"key":"user_agent.original","value":{"stringValue":"curl/7.84.0"}},{"key":"net.host.name","value":{"stringValue":"localhost"}},{"key":"http.response_content_length","value":{"intValue":"12"}},{"key":"http.target","value":{"stringValue":"/hello"}},{"key":"net.sock.peer.addr","value":{"stringValue":"127.0.0.1"}},{"key":"net.host.port","value":{"intValue":"18080"}},{"key":"net.sock.peer.port","value":{"intValue":"53649"}},{"key":"thread.id","value":{"intValue":"48"}},{"key":"thread.name","value":{"stringValue":"http-nio-18080-exec-1"}},{"key":"http.route","value":{"stringValue":"/hello"}},{"key":"net.sock.host.addr","value":{"stringValue":"127.0.0.1"}},{"key":"net.protocol.name","value":{"stringValue":"http"}},{"key":"net.protocol.version","value":{"stringValue":"1.1"}},{"key":"http.scheme","value":{"stringValue":"http"}},{"key":"http.method","value":{"stringValue":"GET"}}],"events":[],"links":[],"status":{}}]}],"schemaUrl":"https://opentelemetry.io/schemas/1.19.0"}

Logtail插件处理配置

{
  "processors": [
    {
      "type": "processor_split_log_regex",
      "detail": {
        "PreserveOthers": true,
        "SplitKey": "content",
        "SplitRegex": "INFO\\sOtlpJsonLoggingSpanExporter\\s.+"
      }
    },
    {
      "type": "processor_regex",
      "detail": {
        "SourceKey": "content",
        "Regex": "INFO\\sOtlpJsonLoggingSpanExporter\\s-(\\s.+)",
        "Keys": [
          "trace_data"
        ]
      }
    },
    {
      "detail": {
        "SourceKey": "trace_data",
        "Format": "protojson",
        "NoKeyError": true
      },
      "type": "processor_otel_trace"
    }
  ]
}

处理结果

数据安全插件概览

功能入口

转换IP地址插件

配置说明

表单配置方式

JSON配置方式

Log转为Metric插件

配置说明

表单配置方式

JSON配置方式

Log转为Trace插件

配置说明

表单配置方式

JSON配置方式

相关文档