データ変換プラグインは、生ログをさまざまなフォーマットに変換したり、IP アドレスを地理的位置情報に解決したり、ログをメトリックやトレースに変換したりします。
データ変換プラグイン
Log Service は、以下のデータ変換プラグインを提供します。
|
パラメーター |
タイプ |
説明 |
|
IP アドレスの変換 |
拡張 |
IP アドレスを地理的位置 (国、リージョン、都市、緯度、経度) に変換します。 |
|
ログからメトリックへ |
拡張 |
ログを Log Service のメトリックに変換します。 |
|
ログからトレースへ |
拡張 |
ログを Log Service のトレースデータに変換します。 |
エントリーポイント
Logtail プラグインをログ処理に使用するには、Logtail 構成を作成または変更するときに追加します。 詳細については、「概要」をご参照ください。
IP アドレス変換プラグイン
processor_geoip プラグインは、ログ内の IP アドレスを国、省、都市、経度、緯度などの地理位置情報データに変換します。
構成
-
Logtail インストールパッケージには GeoIP データベースが含まれていないため、Logtail がインストールされているサーバーに手動でダウンロードして設定する必要があります。 都市レベルの精度のデータベースをダウンロードすることを推奨します。 詳細については、「MaxMind GeoLite2」をご参照ください。
-
データベースが MMDB フォーマットであることを確認してください。
-
フォーム構成は、テキストログとコンテナ標準出力で利用できます。
-
JSON 構成は、テキストログでは利用できません。
フォーム構成
-
パラメーター
[プロセッサータイプ] を IP アドレスの変換 に設定します。
パラメーター
説明
元のフィールド
変換する IP アドレスを含むソースフィールド。
GeoIP データベースパス
GeoIP データベースの絶対パス。 例:
/user/data/GeoLite2-City_20180102/GeoLite2-City.mmdb。元のフィールドの保持
処理後のログにソースフィールドを保持します。
元のフィールド欠落のエラー報告
生ログにソースフィールドがない場合にエラーを報告します。
解析失敗のエラー報告
IP アドレスが無効であるか、データベースで見つからない場合にエラーを報告します。
言語
地名の言語。 デフォルト: zh-CN。
重要ご利用の GeoIP データベースが指定された言語をサポートしていることを確認してください。
-
例
-
生ログ
"source_ip" : "**.**.**.**" -
Logtail プラグイン構成: processor を次の設定で構成します。 [プロセッサタイプ] を [IP アドレスの変換] に設定し、[ソースフィールド] に
source_ipを、[GeoIP データベースパス] に /user/data/GeoLite2-City_20180102/GeoLite2-City.mmdb を指定します。 詳細設定で、[元のフィールドを保持]、[元のフィールドが見つからない場合にエラーを報告]、[解析失敗時にエラーを報告] を選択します。 [言語] をzh-CNに設定し、[確認] をクリックします。 -
処理結果
"source_ip" : "**.**.**.**" "source_ip_province_" : "Zhejiang" "source_ip_city_" : "China (Hangzhou)" "source_ip_province_code_" : "ZJ" "source_ip_country_code_" : "CN" "source_ip_longitude_" : "120.********" "source_ip_latitude_" : "30.********"
-
JSON 構成
-
パラメーター
type を processor_geoip に設定します。 detail パラメーターについては、次の表で説明します。
パラメーター
タイプ
必須
説明
SourceKey
文字列
はい
変換する IP アドレスを含むソースフィールド。
DBPath
文字列
はい
GeoIP データベースの完全なパス。 例: /user/data/GeoLite2-City_20180102/GeoLite2-City.mmdb。
NoKeyError
ブール値
いいえ
SourceKeyで指定されたフィールドが生ログにない場合にエラーを報告します。-
true: エラーを報告します。 -
false(デフォルト): エラーを報告しません。
NoMatchError
ブール値
いいえ
IP アドレスが無効であるか、データベースで見つからない場合にエラーを報告します。
-
true(デフォルト): エラーを報告します。 -
false: エラーを報告しません。
KeepSource
ブール値
いいえ
処理後のログにソースフィールドを保持します。
-
true(デフォルト): ソースフィールドを保持します。 -
false: ソースフィールドを保持しません。
Language
文字列
いいえ
地名の言語。 デフォルト: zh-CN。
重要ご利用の GeoIP データベースが指定された言語をサポートしていることを確認してください。
-
-
例
-
生ログ
"source_ip" : "**.**.**.**" -
Logtail プラグイン構成
{ "type": "processor_geoip", "detail": { "SourceKey": "source_ip", "NoKeyError": true, "NoMatchError": true, "KeepSource": true, "DBPath" : "/user/data/GeoLite2-City_20180102/GeoLite2-City.mmdb" } } -
処理結果
"source_ip" : "**.**.**.**" "source_ip_city_" : "China (Hangzhou)" "source_ip_province_code_" : "ZJ" "source_ip_country_code_" : "CN" "source_ip_longitude_" : "120.********" "source_ip_latitude_" : "30.********"
-
ログからメトリックへのプロセッサ
processor_log_to_sls_metric プラグインを使用して、ログを SLS メトリックに変換します。
構成
processor_log_to_sls_metric プラグインは、Logtail 1.7.1 以降のバージョンでサポートされています。
コンソール
[プロセッサタイプ] を ログからメトリックへ に設定します。 次の表にパラメーターを説明します。
-
パラメーター
パラメーター
説明
MetricTimeKey
ログ内の時間フィールドを時系列データの
__time_nano__フィールドにマッピングします。 デフォルトでは、__time__フィールドの値が使用されます。指定されたフィールドに有効な UNIX タイムスタンプが含まれていることを確認してください。 サポートされている単位は、秒 (10 桁)、ミリ秒 (13 桁)、マイクロ秒 (16 桁)、ナノ秒 (19 桁) です。
MetricLabelKeys
__labels__フィールドのキーのリストです。キーは正規表現^[a-zA-Z_][a-zA-Z0-9_]*$に従う必要があります。値には、縦棒 (|) または#$#を含めることはできません。詳細については、「時系列データ (メトリック)」をご参照ください。__labels__フィールドを MetricLabelKeys パラメーターに追加することはできません。__labels__フィールドがソースフィールドに存在する場合、その値は新しい__labels__フィールドに追加されます。MetricValues
メトリック名と値を生成するためのログフィールドのマップを指定します。 各キーと値のペアでは、キーはメトリック名 (
__name__) のログフィールドを指定し、値はメトリック値 (__value__) のログフィールドを指定します。-
メトリック名は
__name__フィールドに対応し、正規表現^[a-zA-Z_:][a-zA-Z0-9_:]*$に従う必要があります。 -
メトリック値は
__value__フィールドに対応し、Double 型である必要があります。
詳細については、「時系列データ (メトリック)」をご参照ください。
CustomMetricLabels
カスタム
__labels__フィールドでは、Key は正規表現^[a-zA-Z_][a-zA-Z0-9_]*$に従う必要があり、Value には縦棒 (|) または#$#を含めることはできません。詳細については、「時系列データ (メトリック)」をご参照ください。IgnoreError
変換に一致するログがない場合にエラーを記録するかどうか。 デフォルト:
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 プラグイン構成
プロセッサ構成のポップアップウィンドウで、[プロセッサタイプ] を [ログからメトリックへ] に設定します。 [MetricTimeKey] を
httptimeに設定します。 [MetricLabelKeys] にurlとmethodを追加します。 [MetricValues] で、body_bytes_sent_nameからbody_bytes_sentへ、およびstatus_nameからstatusへの 2 つのマッピングを追加します。 [CustomMetricLabels] で、キーがnginx、値が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" } -
2番目の時系列データレコード
{ "__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
文字列
いいえ
ログ内の時間フィールドを時系列データの
__time_nano__フィールドにマッピングします。 デフォルトでは、__time__フィールドの値が使用されます。指定されたフィールドに有効な UNIX タイムスタンプが含まれていることを確認してください。 サポートされている単位は、秒 (10 桁)、ミリ秒 (13 桁)、マイクロ秒 (16 桁)、ナノ秒 (19 桁) です。
MetricLabelKeys
文字列の配列
はい
__labels__フィールドのキーは、正規表現^[a-zA-Z_][a-zA-Z0-9_]*$に準拠する必要があります。値には、縦棒 (|) または#$#を含めることはできません。詳細については、「時系列データ (メトリック)」をご参照ください。__labels__フィールドを MetricLabelKeys パラメーターに追加することはできません。__labels__フィールドがソースフィールドに存在する場合、その値は新しい__labels__フィールドに追加されます。MetricValues
マップ
はい
メトリック名と値を生成するためのログフィールドのマップ。 各キーと値のペアでは、キーはメトリック名 (
__name__) のログフィールドを指定し、値はメトリック値 (__value__) のログフィールドを指定します。-
メトリック名は
__name__フィールドに対応し、正規表現^[a-zA-Z_:][a-zA-Z0-9_:]*$に従う必要があります。 -
メトリック値は
__value__フィールドに対応し、Double 型である必要があります。
詳細については、「時系列データ (メトリック)」をご参照ください。
CustomMetricLabels
マップ
いいえ
カスタム
__labels__フィールドでは、キーは正規表現^[a-zA-Z_][a-zA-Z0-9_]*$に従う必要があり、値には縦棒 (|) または#$#を含めることはできません。 詳細については、「時系列データ (メトリック)」をご参照ください。IgnoreError
ブール値
いいえ
一致するログがない場合にエラーを記録するかどうか。 デフォルト:
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" } -
2番目の時系列データレコード
{ "__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" }
-
-
ログからトレースへのプロセッサ
processor_otel_trace プラグインを使用して、収集したログを SLS トレースに変換します。
構成
processor_otel_trace プロセッサは、Logtail 1.7.1 以降でサポートされています。
フォーム構成
[プロセッサタイプ] を Log から Trace への転換 に設定します。以下の表でパラメーターについて説明します。
-
パラメーター
パラメーター
説明
SourceKey
ソースフィールドの名前。
Format
出力フォーマット。 有効な値:
-
protobuf
-
json
-
protojson
NoKeyError
trueの場合、ログにソースフィールドがない場合にエラーを報告します。 デフォルトはfalseです。TraceIDNeedDecode
trueの場合、TraceIDを Base64 からデコードします。 デフォルトはfalseです。Formatをprotojsonに設定し、TraceIDが Base64 エンコードされている場合、変換の失敗を防ぐためにこのパラメーターをtrueに設定します。SpanIDNeedDecode
trueの場合、SpanIDを Base64 からデコードします。 デフォルトはfalseです。Formatをprotojsonに設定し、SpanIDが Base64 エンコードされている場合、変換の失敗を防ぐためにこのパラメーターをtrueに設定します。ParentSpanIDNeedDecode
trueの場合、ParentSpanIDを Base64 からデコードします。 デフォルトはfalseです。Formatをprotojsonに設定し、ParentSpanIDが Base64 エンコードされている場合、変換の失敗を防ぐためにこのパラメーターを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 プロセッサ構成
[プロセッサタイプ] を [ログからトレースへ] に設定し、[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
文字列
はい
ソースフィールドの名前。
Format
文字列
はい
出力フォーマット。 有効な値は
protobuf、json、protojsonです。NoKeyError
ブール値
いいえ
trueの場合、ログにソースフィールドがない場合にエラーを報告します。 デフォルトはfalseです。TraceIDNeedDecode
ブール値
いいえ
trueの場合、TraceIDを Base64 からデコードします。 デフォルトはfalseです。Formatをprotojsonに設定し、TraceIDが Base64 エンコードされている場合、変換の失敗を防ぐためにこのパラメーターをtrueに設定します。SpanIDNeedDecode
ブール値
いいえ
trueの場合、SpanIDを Base64 からデコードします。 デフォルトはfalseです。Formatをprotojsonに設定し、SpanIDが Base64 エンコードされている場合、変換の失敗を防ぐためにこのパラメーターをtrueに設定します。ParentSpanIDNeedDecode
ブール値
いいえ
trueの場合、ParentSpanIDを Base64 からデコードします。 デフォルトはfalseです。Formatをprotojsonに設定し、ParentSpanIDが Base64 エンコードされている場合、変換の失敗を防ぐためにこのパラメーターを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 パイプラインの構成:
-
コンソールを使用した処理プラグインの構成: