数据转换类插件用于将原始日志进行格式转换、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插件处理配置,配置处理器:处理器类型选择转换IP地址,原始字段填写
source_ip,GeoIP数据库路径填写/user/data/GeoLite2-City_20180102/GeoLite2-City.mmdb。高级参数中勾选保留原始字段、原始字段缺失报错和解析失败报错,语言填写zh-CN,然后单击确认。 -
处理结果
"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插件处理配置
在处理插件配置弹窗中,将处理插件类型选择为Log转Metric。将MetricTimeKey设置为
httptime。在MetricLabelKeys中添加url和method两个 Key。在MetricValues中添加两行映射:body_bytes_sent_name对应body_bytes_sent、status_name对应status。在CustomMetricLabels中添加一行:Label Key 为nginx,Label Value 为test。单击确认。 -
处理结果
-
第一条时序数据
{ "__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插件处理配置
处理插件类型选择 Log转Trace,SourceKey 设置为
content,Format 选择protojson,勾选 NoKeyError,TraceIDNeedDecode、SpanIDNeedDecode、ParentSpanIDNeedDecode 保持未勾选,单击 确认。 -
处理结果
处理结果示例如下。
1 10-07 14:12:08 attribute: {"http.method":"GET","http.response_content_length":"","http.route":"/hello","http.scheme":"http","http.status_code":"","http.target":"/hello","net.host.name":"localhost","net.host.port":"","net.protocol.name":"http","net.protocol.version":"1.1","net.sock.host.addr":"127.0.0.1","net.sock.peer.addr":"127.0.0.1","net.sock.peer.port":"","thread.id":"","thread.name":"http-nio-18080-exec-1","user_agent.original":"curl/7.84.0"} duration: 10224346 end: 1696659128703706 host: B-7xxx xxx.local kind: server links: [] logs: [] name: GET /hello otlp.name: io.opentelemetry.tomcat-7.0 otlp.version: 1.26.0-alpha parentSpanID: resource: {"host.arch":"x86_64","os.description":"Mac OS X 13.0.1","os.type":"darwin","process.command_args":"","process.executable.path":"/Library/Java/JavaVirtualMachines/jdk-20.jdk/Contents/Home/bin/java","process.pid":"","process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 20.0.1+9-29","process.runtime.name":"Java(TM) SE Runtime Environment","process.runtime.version":"20.0.1+9-29","telemetry.auto.version":"1.26.0","telemetry.sdk.language":"java","telemetry.sdk.name":"opentelemetry","telemetry.sdk.version":"1.26.0"} service: unknown_service:java spanID: 7dexxx xxxb47bc start: 1696659118479360 statusCode: UNSET statusMessage: traceID: 6bb690xxx xxxff79 traceState:
-
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" } ] } -
处理结果
处理结果示例如下。
1 10-07 14:12:08 attribute: {"http.method":"GET","http.response_content_length":"","http.route":"/hello","http.scheme":"http","http.status_code":"","http.target":"/hello","net.host.name":"localhost","net.host.port":"","net.protocol.name":"http","net.protocol.version":"1.1","net.sock.host.addr":"127.0.0.1","net.sock.peer.addr":"127.0.0.1","net.sock.peer.port":"","thread.id":"","thread.name":"http-nio-18080-exec-1","user_agent.original":"curl/7.84.0"} duration: 10224346 end: 1696659128703706 host: B-7xxx xxx.local kind: server links: [] logs: [] name: GET /hello otlp.name: io.opentelemetry.tomcat-7.0 otlp.version: 1.26.0-alpha parentSpanID: resource: {"host.arch":"x86_64","os.description":"Mac OS X 13.0.1","os.type":"darwin","process.command_args":"","process.executable.path":"/Library/Java/JavaVirtualMachines/jdk-20.jdk/Contents/Home/bin/java","process.pid":"","process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 20.0.1+9-29","process.runtime.name":"Java(TM) SE Runtime Environment","process.runtime.version":"20.0.1+9-29","telemetry.auto.version":"1.26.0","telemetry.sdk.language":"java","telemetry.sdk.name":"opentelemetry","telemetry.sdk.version":"1.26.0"} service: unknown_service:java spanID: 7dexxx xxxb47bc start: 1696659118479360 statusCode: UNSET statusMessage: traceID: 6bb690xxx xxxff79 traceState:
-
相关文档
-
通过API接口配置Logtail流水线:
-
通过控制台配置处理插件: