データ変換プラグイン - Simple Log Service - Alibaba Cloud ドキュメントセンター

データ変換プラグインを使用して、生ログのフォーマットを変更したり、IP アドレスを地理的な場所に変換したり、ログをメトリックやトレースに変換したりできます。

データセキュリティプラグインの概要

Simple Log Service (SLS) は、次のタイプのデータ変換プラグインを提供します。要件に応じてプラグインを選択できます。

プラグイン名	タイプ	説明
IP アドレスの変換	拡張機能	IP アドレスを地理的な場所 (国、省、市、経度、緯度) に変換します。
ログをメトリックに変換	拡張機能	ログを SLS メトリックデータに変換します。
ログをトレースに変換	拡張機能	ログを SLS トレースデータに変換します。

エントリポイント

Logtail プラグインを使用してログを処理する場合、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 アドレスが無効であるか、データベースに見つからない場合にシステムがエラーを報告します。
言語	言語プロパティ。デフォルト値は zh-CN です。重要 GeoIP データベースに指定された言語が含まれていることを確認してください。

例

次の例は、ログ内の IP アドレスを対応する地理的な場所に変換する方法を示しています。

生ログ
```
"source_ip" : "**.**.**.**"
```
Logtail プラグイン構成

結果

"source_ip" : "**.**.**.**"
"source_ip_province_" : "Zhejiang"
"source_ip_city_" : "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	ブール値	いいえ	指定されたソースフィールドが生ログに見つからない場合にシステムがエラーを報告するかどうかを指定します。 `true`: エラーを報告します。 `false` (デフォルト): エラーを報告しません。
NoMatchError	ブール値	いいえ	IP アドレスが無効であるか、データベースに見つからない場合にシステムがエラーを報告するかどうかを指定します。 `true` (デフォルト): エラーを報告します。 `false`: エラーを報告しません。
KeepSource	ブール値	いいえ	解析後にソースフィールドをログに保持するかどうかを指定します。 `true` (デフォルト): フィールドを保持します。 `false`: フィールドを保持しません。
Language	文字列	いいえ	言語プロパティ。デフォルト値は 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_" : "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 プラグインのパラメーターについて説明し、構成例を示します。

構成の説明

重要

processor_log_to_sls_metric プラグインは Logtail 1.7.1 以降でサポートされています。

フォーム構成

[プロセッサタイプ] で、[ログをメトリックに変換] を選択します。次の表にパラメーターを示します。

パラメーター

パラメーター	説明
MetricTimeKey	ログ内の時間フィールドを指定します。このフィールドは、時系列データの `__time_nano__` フィールドにマッピングされます。デフォルトでは、`__time__` フィールドの値がログから抽出されます。指定されたフィールドが正しいフォーマットの有効なタイムスタンプであることを確認してください。秒 (10 桁)、ミリ秒 (13 桁)、マイクロ秒 (16 桁)、またはナノ秒 (19 桁) の Unix タイムスタンプがサポートされています。
MetricLabelKeys	`__labels__` フィールドのキーのリストを指定します。キーは正規表現 `^[a-zA-Z_][a-zA-Z0-9_]*$` に一致する必要があります。値に縦棒 (\|) または `#$#` を含めることはできません。詳細については、「時系列データ (メトリック)」をご参照ください。 MetricLabelKeys パラメーターに `__labels__` フィールドを追加することはできません。ソースフィールドに `__labels__` フィールドが存在する場合、その値は新しい `__labels__` フィールドに追加されます。
MetricValues	メトリック名とメトリック値を指定します。メトリック名は `__name__` フィールドに対応し、正規表現 `^[a-zA-Z_:][a-zA-Z0-9_:]*$` に一致する必要があります。メトリック値は `__value__` フィールドに対応し、Double 型である必要があります。詳細については、「時系列データ (メトリック)」をご参照ください。
CustomMetricLabels	カスタム `__labels__` フィールドを指定します。キーは正規表現 `^[a-zA-Z_][a-zA-Z0-9_]*$` に一致する必要があります。値に縦棒 (\|) または `#$#` を含めることはできません。詳細については、「時系列データ (メトリック)」をご参照ください。
IgnoreError	一致するログがない場合にエラーログを出力するかどうかを指定します。

例

生ログ

{
    "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"
}

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__` フィールドの値がログから抽出されます。指定されたフィールドが正しいフォーマットの有効なタイムスタンプであることを確認してください。秒 (10 桁)、ミリ秒 (13 桁)、マイクロ秒 (16 桁)、またはナノ秒 (19 桁) の Unix タイムスタンプがサポートされています。
MetricLabelKeys	[]文字列	はい	`__labels__` フィールドのキーのリストを指定します。キーは正規表現 `^[a-zA-Z_][a-zA-Z0-9_]*$` に一致する必要があります。値に縦棒 (\|) または `#$#` を含めることはできません。詳細については、「時系列データ (メトリック)」をご参照ください。 MetricLabelKeys パラメーターに `__labels__` フィールドを追加することはできません。ソースフィールドに `__labels__` フィールドが存在する場合、その値は新しい `__labels__` フィールドに追加されます。
MetricValues	マップ	はい	メトリック名とメトリック値を指定します。メトリック名は `__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 プラグインのパラメーターについて説明し、構成例を示します。

構成の説明

重要

processor_otel_trace プラグインは Logtail 1.7.1 以降でサポートされています。

フォーム構成

[プロセッサタイプ] を [ログをトレースに変換] に設定します。次の表にパラメーターを示します。

パラメーター

パラメーター	説明
SourceKey	ソースフィールドの名前。
フォーマット	変換後のフォーマット。有効な値: 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	文字列	はい	ソースフィールドの名前。
フォーマット	文字列	はい	変換後のフォーマット。有効な値: 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 プラグイン構成

{
  "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 構成

ログをメトリックに変換するプラグイン

構成の説明

フォーム構成

JSON 構成

ログをトレースに変換するプラグイン

構成の説明

フォーム構成

JSON を使用した構成

関連ドキュメント