Plugin transformasi data - Simple Log Service

Anda dapat menggunakan plugin transformasi data untuk mengubah format log mentah, mengonversi alamat IP menjadi lokasi geografis, atau mengonversi log menjadi metrik atau jejak.

Ikhtisar plugin keamanan data

Simple Log Service (SLS) menyediakan jenis plugin transformasi data berikut. Anda dapat memilih plugin sesuai kebutuhan Anda.

Nama Plugin	Tipe	Deskripsi
Konversi alamat IP	Ekstensi	Mengonversi alamat IP menjadi lokasi geografis (negara, provinsi, kota, bujur, dan lintang).
Konversi log ke metrik	Ekstensi	Mengonversi log menjadi data metrik SLS.
Konversi log ke jejak	Ekstensi	Mengonversi log menjadi data jejak SLS.

Titik masuk

Jika ingin menggunakan plugin Logtail untuk memproses log, tambahkan konfigurasi plugin Logtail saat membuat atau mengubah konfigurasi Logtail. Untuk informasi selengkapnya, lihat Ikhtisar.

Plugin Konversi alamat IP

Anda dapat menggunakan plugin processor_geoip untuk mengonversi alamat IP dalam log menjadi lokasi geografis, seperti negara, provinsi, kota, bujur, dan lintang. Bagian ini menjelaskan parameter dan memberikan contoh konfigurasi untuk plugin processor_geoip.

Deskripsi konfigurasi

Catatan

Paket instalasi Logtail tidak menyertakan database GeoIP. Anda harus mengunduh secara manual database GeoIP ke server tempat Logtail diinstal dan menentukan jalurnya dalam konfigurasi. Kami menyarankan Anda mengunduh database dengan granularitas tingkat Kota. Untuk informasi selengkapnya, lihat MaxMind GeoLite2.
Pastikan database dalam format MMDB.
Konfigurasi berbasis formulir: Metode ini tersedia saat Anda mengumpulkan log teks dan keluaran standar kontainer.
Konfigurasi JSON: Metode ini tidak tersedia saat Anda mengumpulkan log teks.

Konfigurasi berbasis formulir

Parameter

Atur Processor Type ke Convert IP Addresses. Tabel berikut menjelaskan parameter tersebut.

Parameter	Deskripsi
Source Field	Nama bidang sumber yang nilainya ingin Anda konversi dari alamat IP.
GeoIP Database Path	Jalur lengkap database GeoIP. Contoh: `/user/data/GeoLite2-City_20180102/GeoLite2-City.mmdb`.
Keep Source Field	Jika Anda memilih opsi ini, bidang sumber tetap ada dalam log setelah penguraian.
Report Error On Missing Source Field	Jika Anda memilih opsi ini, sistem akan melaporkan kesalahan jika bidang sumber yang ditentukan tidak ditemukan dalam log mentah.
Report Error On Parsing Failure	Jika Anda memilih opsi ini, sistem akan melaporkan kesalahan jika alamat IP tidak valid atau tidak ditemukan dalam database.
Language	Properti bahasa. Nilai default adalah zh-CN. Penting Pastikan database GeoIP Anda berisi bahasa yang ditentukan.

Contoh

Contoh berikut menunjukkan cara mengonversi alamat IP dalam log menjadi lokasi geografis yang sesuai:

Log mentah
```
"source_ip" : "**.**.**.**"
```
Konfigurasi plugin Logtail

Hasil

"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.********"

Konfigurasi JSON

Parameter

Atur type ke processor_geoip. Tabel berikut menjelaskan parameter dalam detail.

Parameter	Tipe	Wajib	Deskripsi
SourceKey	String	Ya	Nama bidang sumber yang nilainya ingin Anda konversi dari alamat IP.
DBPath	String	Ya	Jalur lengkap database GeoIP. Contoh: /user/data/GeoLite2-City_20180102/GeoLite2-City.mmdb.
NoKeyError	Boolean	Tidak	Menentukan apakah sistem melaporkan kesalahan jika bidang sumber yang ditentukan tidak ditemukan dalam log mentah. `true`: Melaporkan kesalahan. `false` (default): Tidak melaporkan kesalahan.
NoMatchError	Boolean	Tidak	Menentukan apakah sistem melaporkan kesalahan jika alamat IP tidak valid atau tidak ditemukan dalam database. `true` (default): Melaporkan kesalahan. `false`: Tidak melaporkan kesalahan.
KeepSource	Boolean	Tidak	Menentukan apakah bidang sumber dipertahankan dalam log setelah penguraian. `true` (default): Mempertahankan bidang. `false`: Tidak mempertahankan bidang.
Language	String	Tidak	Properti bahasa. Nilai default adalah zh-CN. Penting Pastikan database GeoIP Anda berisi bahasa yang ditentukan.

Contoh

Contoh berikut menunjukkan cara mengonversi alamat IP dalam log menjadi lokasi geografis yang sesuai:

Log mentah
```
"source_ip" : "**.**.**.**"
```

Konfigurasi plugin Logtail

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

Hasil

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

Plugin Konversi log ke metrik

Anda dapat menggunakan plugin processor_log_to_sls_metric untuk mengonversi log yang dikumpulkan menjadi metrik SLS. Bagian ini menjelaskan parameter dan memberikan contoh konfigurasi untuk plugin processor_log_to_sls_metric.

Deskripsi konfigurasi

Penting

Plugin processor_log_to_sls_metric didukung pada Logtail 1.7.1 dan versi yang lebih baru.

Konfigurasi formulir

Pada Processor Type, pilih Convert Log To Metric. Tabel berikut menjelaskan parameter-parameter tersebut.

Parameter

Parameter	Deskripsi
MetricTimeKey	Menentukan bidang waktu dalam log. Bidang ini dipetakan ke bidang `__time_nano__` dalam data deret waktu. Secara default, nilai bidang `__time__` diekstraksi dari log. Pastikan bidang yang ditentukan merupakan timestamp yang valid dalam format yang benar. Timestamp Unix dalam satuan detik (10 digit), milidetik (13 digit), mikrodetik (16 digit), atau nanodetik (19 digit) didukung.
MetricLabelKeys	Menentukan daftar kunci untuk bidang `__labels__`. Kunci harus cocok dengan ekspresi reguler `^[a-zA-Z_][a-zA-Z0-9_]*$`. Nilai tidak boleh mengandung tanda pipa vertikal (\|) atau `#$#`. Untuk informasi selengkapnya, lihat Data deret waktu (Metrik). Anda tidak dapat menambahkan bidang `__labels__` ke parameter MetricLabelKeys. Jika bidang `__labels__` sudah ada dalam bidang sumber, nilainya akan ditambahkan ke bidang `__labels__` yang baru.
MetricValues	Menentukan nama metrik dan nilai metrik. Nama metrik berkorespondensi dengan bidang `__name__` dan harus cocok dengan ekspresi reguler `^[a-zA-Z_:][a-zA-Z0-9_:]*$`. Nilai metrik berkorespondensi dengan bidang `__value__` dan harus bertipe Double. Untuk informasi selengkapnya, lihat Data deret waktu (Metrik) .
CustomMetricLabels	Menentukan bidang `__labels__` kustom. Kunci harus cocok dengan ekspresi reguler `^[a-zA-Z_][a-zA-Z0-9_]*$`. Nilai tidak boleh mengandung tanda pipa vertikal (\|) atau `#$#`. Untuk informasi selengkapnya, lihat Data deret waktu (Metrik) .
IgnoreError	Menentukan apakah akan mengeluarkan log kesalahan jika tidak ada log yang cocok.

Contoh

Log mentah

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

Konfigurasi plugin Logtail

Hasil

Data deret waktu pertama

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

Data deret waktu kedua

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

Konfigurasi JSON

Atur type ke processor_log_to_sls_metric. Tabel berikut menjelaskan parameter dalam detail.

Parameter

Parameter	Tipe	Wajib	Deskripsi
MetricTimeKey	String	Tidak	Menentukan bidang waktu dalam log. Bidang ini dipetakan ke bidang `__time_nano__` dalam data deret waktu. Secara default, nilai bidang `__time__` diekstraksi dari log. Pastikan bidang yang ditentukan merupakan timestamp yang valid dalam format yang benar. Timestamp Unix dalam satuan detik (10 digit), milidetik (13 digit), mikrodetik (16 digit), atau nanodetik (19 digit) didukung.
MetricLabelKeys	[]String	Ya	Menentukan daftar kunci untuk bidang `__labels__`. Kunci harus cocok dengan ekspresi reguler `^[a-zA-Z_][a-zA-Z0-9_]*$`. Nilai tidak boleh mengandung tanda pipa vertikal (\|) atau `#$#`. Untuk informasi selengkapnya, lihat Data deret waktu (Metrik). Anda tidak dapat menambahkan bidang `__labels__` ke parameter MetricLabelKeys. Jika bidang `__labels__` sudah ada dalam bidang sumber, nilainya akan ditambahkan ke bidang `__labels__` yang baru.
MetricValues	Map	Ya	Menentukan nama metrik dan nilai metrik. Nama metrik berkorespondensi dengan bidang `__name__` dan harus cocok dengan ekspresi reguler `^[a-zA-Z_:][a-zA-Z0-9_:]*$`. Nilai metrik berkorespondensi dengan bidang `__value__` dan harus bertipe Double. Untuk informasi selengkapnya, lihat Data deret waktu (Metrik) .
CustomMetricLabels	Map	Tidak	Menentukan bidang `__labels__` kustom. Kunci harus cocok dengan ekspresi reguler `^[a-zA-Z_][a-zA-Z0-9_]*$`. Nilai tidak boleh mengandung tanda pipa vertikal (\|) atau `#$#`. Untuk informasi selengkapnya, lihat Data deret waktu (Metrik) .
IgnoreError	Boolean	Tidak	Menentukan apakah akan mengeluarkan log kesalahan jika tidak ada log yang cocok. Nilai default adalah false, yang berarti tidak ada log kesalahan yang dikeluarkan.

Contoh

Log mentah

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

Konfigurasi plugin 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"
        }
    ]
}

Hasil

Data deret waktu pertama

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

Data deret waktu kedua

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

Plugin Konversi log ke jejak

Anda dapat menggunakan plugin processor_otel_trace untuk mengonversi log yang dikumpulkan menjadi jejak SLS. Bagian ini menjelaskan parameter dan memberikan contoh konfigurasi untuk plugin processor_otel_trace.

Deskripsi konfigurasi

Penting

Plugin processor_otel_trace didukung pada Logtail 1.7.1 dan versi yang lebih baru.

Konfigurasi formulir

Atur Processor Type ke Convert Log To Trace. Tabel berikut menjelaskan parameter tersebut.

Parameter

Parameter	Deskripsi
SourceKey	Nama bidang sumber.
Format	Format setelah konversi. Nilai yang valid: protobuf json protojson
NoKeyError	Menentukan apakah akan melaporkan kesalahan jika bidang sumber tidak ada dalam log. Nilai default adalah false.
TraceIDNeedDecode	Menentukan apakah akan melakukan decoding Base64 pada TraceID. Nilai default adalah false. Jika Anda mengatur Format ke protojson dan TraceID dienkripsi Base64, Anda harus mengatur TraceIDNeedDecode ke true. Jika tidak, konversi akan gagal.
SpanIDNeedDecode	Menentukan apakah akan melakukan decoding Base64 pada SpanID. Nilai default adalah false. Jika Anda mengatur Format ke protojson dan SpanID dienkripsi Base64, Anda harus mengatur SpanIDNeedDecode ke true. Jika tidak, konversi akan gagal.
ParentSpanIDNeedDecode	Menentukan apakah akan melakukan decoding Base64 pada ParentSpanID. Nilai default adalah false. Jika Anda mengatur Format ke protojson dan ParentSpanID dienkripsi Base64, Anda harus mengatur ParentSpanIDNeedDecode ke true. Jika tidak, konversi akan gagal.

Contoh

Log mentah

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

Konfigurasi plugin Logtail
Hasil

Konfigurasi menggunakan JSON

Atur type ke processor_otel_trace. Tabel berikut menjelaskan parameter dalam detail.

Parameter

Parameter	Tipe	Wajib	Deskripsi
SourceKey	String	Ya	Nama bidang sumber.
Format	String	Ya	Format setelah konversi. Nilai yang valid: protobuf, json, protojson.
NoKeyError	Boolean	Tidak	Menentukan apakah akan melaporkan kesalahan jika bidang sumber tidak ada dalam log. Nilai default adalah false.
TraceIDNeedDecode	Boolean	Tidak	Menentukan apakah akan melakukan decoding Base64 pada TraceID. Nilai default adalah false. Jika Anda mengatur Format ke protojson dan TraceID dienkripsi Base64, Anda harus mengatur TraceIDNeedDecode ke true. Jika tidak, konversi akan gagal.
SpanIDNeedDecode	Boolean	Tidak	Menentukan apakah akan melakukan decoding Base64 pada SpanID. Nilai default adalah false. Jika Anda mengatur Format ke protojson dan SpanID dienkripsi Base64, Anda harus mengatur SpanIDNeedDecode ke true. Jika tidak, konversi akan gagal.
ParentSpanIDNeedDecode	Boolean	Tidak	Menentukan apakah akan melakukan decoding Base64 pada ParentSpanID. Nilai default adalah false. Jika Anda mengatur Format ke protojson dan ParentSpanID dienkripsi Base64, Anda harus mengatur ParentSpanIDNeedDecode ke true. Jika tidak, konversi akan gagal.

Contoh

Log mentah

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

Konfigurasi plugin 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"
    }
  ]
}

Hasil

Referensi

Konfigurasikan pipeline Logtail menggunakan operasi API:
Konfigurasikan plugin pemrosesan di Konsol:
- Mengumpulkan log teks dari host
- Mengumpulkan log kontainer dari kluster di konsol (keluaran standar/file)
Mengumpulkan log kontainer dari kluster menggunakan CRD Kubernetes (keluaran standar/file)