資料轉換類外掛程式 - Simple Log Service

資料轉換類外掛程式用於將原始日誌進行格式轉換、IP地理化、日誌轉指標/鏈路等情境。

資料安全外掛程式概覽

Log Service提供以下多種類型的資料轉換類外掛程式，請按需要進行選擇。

外掛程式名稱	類型	功能說明
轉換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需遵循Regex `^[a-zA-Z_][a-zA-Z0-9_]*$`。Value不能包含豎線（\|）和 `#$#`。更多資訊，請參見時序資料（Metric）。不支援在MetricLabelKeys參數中添加`__labels__`欄位。如果原始欄位中存在 `__labels__` 欄位，該值將被追加到新的`__labels__`欄位中。
MetricValues	用於指定Metric名稱和Metric值。 Metric名稱對應`__name__`欄位，需遵循Regex`^[a-zA-Z_:][a-zA-Z0-9_:]*$`。 Metric值對應`__value__`欄位，需為Double類型。更多資訊，請參見時序資料（Metric）。
CustomMetricLabels	自訂的`__labels__`欄位， Key需遵循Regex `^[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需遵循Regex `^[a-zA-Z_][a-zA-Z0-9_]*$`。Value不能包含豎線（\|）和 `#$#`。更多資訊，請參見時序資料（Metric）。不支援在MetricLabelKeys參數中添加`__labels__`欄位。如果原始欄位中存在 `__labels__` 欄位，該值將被追加到新的`__labels__`欄位中。
MetricValues	Map	是	用於指定Metric名稱和Metric值。 Metric名稱對應`__name__`欄位，需遵循Regex`^[a-zA-Z_:][a-zA-Z0-9_:]*$`。 Metric值對應`__value__`欄位，需為Double類型。更多資訊，請參見時序資料（Metric）。
CustomMetricLabels	Map	否	自訂的`__labels__`欄位， Key需遵循Regex `^[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"
    }
  ]
}

處理結果

Simple Log Service：資料轉換類外掛程式

資料安全外掛程式概覽

功能入口

轉換IP地址外掛程式

配置說明

表單配置方式

JSON配置方式

Log轉為Metric外掛程式

配置說明

表單配置方式

JSON配置方式

Log轉為Trace外掛程式

配置說明

表單配置方式

JSON配置方式

相關文檔