Pemetaan rekaman log OTLP ke entri log

Dokumen ini menjelaskan cara Google Cloud Observability menentukan kolom LogEntry dari rekaman log OTLP, saat rekaman tersebut dikirim ke Google Cloud menggunakan Telemetry API.

Struktur umum data log berformat OTLP

Saat data log dikirim ke Google Cloud menggunakan Telemetry API, data ini harus dalam format yang konsisten dengan OTLP. Struktur umum untuk data ini adalah seperti yang ditunjukkan:

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "logRecords": [...]
        }
      ]
    }
]

Perhatikan bahwa OpenTelemetry mengelompokkan log individual, yang masing-masing direpresentasikan oleh struktur logRecord, dengan informasi tentang sumber log tersebut, yang direpresentasikan oleh struktur resource.

Saat menerima objek resourceLogs, Google Cloud Observability akan membuat satu LogEntry untuk setiap logRecord. Tidak seperti OTLP yang mengelompokkan informasi sumber dengan kumpulan log individual, setiap struktur LogEntry berisi informasi tentang sumber log dan log itu sendiri.

Untuk mempelajari lebih lanjut struktur data log berformat OTLP, lihat logs.proto OpenTelemetry.

Cara kolom LogEntry ditetapkan

Google Cloud Observability menggunakan aturan berikut untuk menentukan nilai kolom LogEntry:

Kolom `LogEntry` (Nama dari referensi HTTP)	Cara sistem menentukan nilai kolom
`logName`	Sistem menggunakan daftar atribut rekaman log OpenTelemetry yang diprioritaskan berikut untuk menentukan nama log: `gcp.log_name` `log_name` `event_name` Nama log harus aman untuk URL atau dienkode URL selama penyerapan.
`resource`	Sistem menggunakan informasi yang ditetapkan di kolom `resource` atau menyimpulkan resource. Untuk mengetahui detailnya, lihat Pemetaan atribut OTLP ke jenis resource.
`timestamp`	Sistem menggunakan daftar kolom rekaman log OpenTelemetry yang diprioritaskan berikut untuk menentukan `timestamp`: `time_unix_nano` jika bukan nol. `observed_time_unix_nano` jika bukan nol. Waktu entri log dimasukkan. Periode retensi untuk bucket log yang menyimpan data menentukan stempel waktu terlama yang dapat diserap. Untuk mengetahui informasi selengkapnya, lihat Kuota Cloud Logging.
`receiveTimestamp`	Disetel ke waktu saat `LogEntry` di-ingest.
`severity`	Sistem memetakan tingkat keparahan OpenTelemetry dalam catatan log ke tingkat keparahan Cloud Logging. Untuk mengetahui detailnya, lihat Kolom tingkat keparahan.
`httpRequest`	Sistem memetakan atribut `gcp.http_request` dalam catatan log ke kolom `LogEntry` yang setara. Untuk mengetahui informasi selengkapnya, lihat Kolom HttpRequest. FIXME. Ada kolom lain yang dipetakan ke kolom ini.
`labels`	Sistem menetapkan kolom ini menggunakan nilai atribut rekaman log. Untuk mengetahui informasi selengkapnya, lihat Kolom label.
`trace`	Sistem menetapkan kolom ini ke nilai dari kolom `traceId` dalam catatan log. Nilai harus berupa string hex 32 karakter yang valid, atau entri ditolak.
`spanId`	Sistem menetapkan kolom ini ke nilai dari kolom `spanId` dalam catatan log. Nilai harus berupa string hex 16 karakter yang valid, atau entri ditolak.
`traceSampled`	Belum ditetapkan.
`sourceLocation`	Sistem menetapkan kolom ini ke nilai dari atribut Kode catatan log. Untuk mengetahui informasi selengkapnya, lihat kolom SourceLocation.
`split`	Belum ditetapkan.
`apphub` `apphubDestination` `apphubSource`	Belum ditetapkan.
`otel`	Untuk kolom dalam data log OTLP yang tidak memiliki kolom yang setara dalam `LogEntry`, sistem akan mengonversi jenis data, lalu menambahkan data yang dikonversi ke kolom `otel`. Untuk mengetahui informasi selengkapnya, lihat Kolom Otel.
Payload	Sistem menetapkan payload dengan mengonversi isi rekaman log ke jenis payload yang sesuai. Untuk mengetahui informasi selengkapnya, lihat Kolom payload.

Kolom HttpRequest

Google Cloud Observability memetakan atribut OTLP yang berlaku untuk permintaan HTTP ke kolom LogEntry. Bagian berikut menjelaskan cara sistem memetakan atribut datar dan bertingkat.

Atribut datar

Tabel berikut menjelaskan cara Google Cloud Observability memetakan atribut datar yang berlaku untuk permintaan HTTP ke kolom LogEntry. Misalnya, nilai dari atribut http.request.method: "GET", ditetapkan sebagai nilai kolom httpRequest.requestMethod dalam entri log:

OpenTelemetry `LogRecord.attribute` pasangan nilai kunci.	Nilai yang disimpan di kolom `LogEntry` berikut (Nama dari referensi HTTP)	Jenis yang Diterima
`http.request.method`	`httpRequest.requestMethod`	string
`url.full` `http.url`	`httpRequest.requestUrl`	string
`http.request.body.size`	`httpRequest.requestSize`	string, int
`http.response.status_code`	`httpRequest.status`	string, int
`http.response.body.size`	`httpRequest.responseSize`	string, int
`user_agent.original` `http.user_agent`	`httpRequest.userAgent`	string
`client.address`	`remoteIp`	string
`server.address`	`serverIp`	string
`referrer`	`httpRequest.referer`	string
`latency`	`httpRequest.latency`	string, int
`cacheLookup`	`httpRequest.cacheLookup`	bool
`cacheHit`	`httpRequest.cacheHit`	bool
`cacheValidatedWithOriginServer`	`httpRequest.cacheValidatedWithOriginServer`	bool
`cacheFillBytes`	`httpRequest.cacheFillBytes`	string, int
`network.protocol.version` `protocol`	`httpRequest.protocol`	string

Atribut bertingkat

Bagian ini menjelaskan cara Google Cloud Observability memetakan atribut OTLP bertingkat yang berlaku untuk permintaan HTTP ke kolom dalam LogEntry. Contoh berikut mengilustrasikan catatan log yang berisi dua atribut, yang masing-masing berisi setidaknya satu atribut lainnya:

log_record {
  attributes: {
    gcp.http_request {
      "requestMethod": "GET",
      "requestUrl": "some-URL",
    }
    http_request {
      "requestMethod": "GET",
    }
  }
}

Dalam tabel, atribut bertingkat ditampilkan menggunakan tanda kurung. Misalnya, gcp.http_request {requestMethod} berarti atribut gcp.http_request berisi atribut requestMethod. Nilai dari atribut paling dalam ditetapkan ke nilai kolom entri log:

OpenTelemetry `LogRecord.attribute` pasangan nilai kunci.	Nilai yang disimpan di kolom `LogEntry` berikut (Nama dari referensi HTTP)	Jenis yang Diterima
`gcp.http_request {requestMethod}` `http_request {requestMethod}`	`httpRequest.requestMethod`	string
`gcp.http_request {requestUrl}` `http_request {requestUrl}`	`httpRequest.requestUrl`	string
`gcp.http_request {requestSize}` `http_request {requestSize}`	`httpRequest.requestSize`	string, int
`gcp.http_request {status}` `http_request {status}`	`httpRequest.status`	string, int
`gcp.http_request {responseSize}` `http_request {responseSize}`	`httpRequest.responseSize`	string, int
`gcp.http_request {userAgent}` `http_request {userAgent}`	`httpRequest.userAgent`	string
`gcp.http_request {remoteIp}` `http_request {remoteIp}`	`httpRequest.remoteIp`	string
`gcp.http_request {serverIp}` `http_request {serverIp}`	`httpRequest.serverIp`	string
`gcp.http_request {referer}` `http_request {referrer}`	`httpRequest.referer`	string
`gcp.http_request {latency}` `http_request {latency}`	`httpRequest.latency`	string, int
`gcp.http_request {cacheLookup}` `http_request {cacheLookup}`	`httpRequest.cacheLookup`	bool
`gcp.http_request {cacheHit}` `http_request {cacheHit}`	`httpRequest.cacheHit`	bool
`gcp.http_request { cacheValidatedWithOriginServer}` `http_request { cacheValidatedWithOriginServer}`	`httpRequest.cacheValidatedWithOriginServer`	bool
`gcp.http_request {cacheFillBytes}` `http_request {cacheFillBytes}`	`httpRequest.cacheFillBytes`	string, int
`gcp.http_request {protocol}` `http_request {protocol}`	`httpRequest.protocol`	string

Kolom label

Untuk menentukan label yang akan dilampirkan ke entri log, sistem melakukan tindakan berikut:

Proses ini menghapus atribut apa pun dari catatan log OTLP yang telah dipetakan ke kolom LogEntry tertentu.

Misalnya, ada atribut yang dilampirkan ke catatan log:

attributes: {
    "log_array_attr: ["value1", "value2"],
    "log_json_attr": {"json_key": "json_value"}
    "log-string-attr": "string",
    "code.file.path": "my-file.cc",
    "code.function.name: "my-func",
    "code.line.number": 123,
    "gcp.http_request": {
        "requestMethod": "GET",
        "requestUrl": "my-URL",
  },
}

Setelah menghapus kolom yang dipetakan ke kolom LogEntry tertentu, kolom berikut akan tetap ada:

attributes: {
    "log_array_attr: ["value1", "value2"],
    "log_json_attr": {"json_key": "json_value"}
    "log-string-attr": "string",
}

Jika atribut berisi elemen array atau JSON, sistem akan mengonversi nilai menjadi string.

Misalnya, berikut ini menggambarkan cara LogEntry merepresentasikan atribut sebelumnya:
```
labels: {
    "log_array_attr": "[\"value1\",\"value2\"]",
    "log_json_attr": "{\"json_key\":\"json_value\"}",
    "log-string-attr": "string",
}
```
Kedalaman bertingkat maksimum untuk atribut adalah lima. Konten apa pun yang memiliki penyusunan bertingkat lebih dalam akan dipangkas.

Kolom Otel

Untuk kolom dalam data log OTLP yang tidak memiliki kolom yang setara dalam LogEntry, sistem akan mengonversi jenis data, lalu menambahkan data yang dikonversi ke kolom otel. Misalnya, kolom otel menyimpan atribut dari kolom resource, scope, dan entity.

Sistem menggunakan aturan berikut untuk mengonversi jenis data OpenTelemetry ke jenis protobuf Value:

Jenis OpenTelemetry	jenis protobuf
`string`	`string`
`boolean`	`bool`
`integer`	`double`
`float`	`double`
`Array`	`ListValues`
`KeyValueList`	`Struct`

Untuk menghindari error presisi ganda, teruskan bilangan bulat sebagai string.

Kolom payload

Jenis data kolom logRecord.body OTLP menentukan struktur payload LogEntry:

string: Sistem menyalin string ke kolom LogEntry.textPayload.
Array: Sistem membuat string elemen array sambil mempertahankan baris baru. Kemudian, string tersebut disalin ke kolom LogEntry.textPayload.
KeyValueList: Sistem mengonversi pasangan tersebut menjadi JSON, lalu mengisi kolom LogEntry.jsonPayload, dengan batasan berikut:
- Jika rekaman OTLP berisi kunci atribut duplikat, sistem akan mempertahankan kunci pertama dan membuang atribut dengan kunci duplikat.
- Jika kedalaman bertingkat untuk pasangan JSON lebih besar dari lima, sistem akan memangkas konten hingga kedalaman lima.

Kolom tingkat keparahan

Bagian ini menjelaskan cara Google Cloud Observability memetakan kolom tingkat keparahan OpenTelemetry ke tingkat tingkat keparahan Cloud Logging. OpenTelemetry menentukan angka tingkat keparahan dan teks tingkat keparahan. logs.proto menentukan angka tingkat keparahan.

Google Cloud Observability menentukan tingkat keparahan Logging dari nomor tingkat keparahan OpenTelemetry, jika ditetapkan. Jika tidak, teks tingkat keparahan akan digunakan. Jika keduanya tidak ditetapkan, tingkat keparahan Logging akan ditetapkan ke DEFAULT.

Nomor tingkat keparahan OpenTelemetry Enum (nilai)	Teks tingkat keparahan OpenTelemetry (pengujian tidak peka huruf besar/kecil)	Tingkat keparahan Cloud Logging Enum (nilai)
`SEVERITY_NUMBER_UNSPECIFIED` (0)	"default" tidak ditetapkan	`DEFAULT` (0)
`SEVERITY_NUMBER_TRACE` (1) `SEVERITY_NUMBER_TRACE2` (2) `SEVERITY_NUMBER_TRACE3` (3) `SEVERITY_NUMBER_TRACE4` (4)	"trace" "trace2" "trace3" "trace4"	`DEBUG` (100)
`SEVERITY_NUMBER_DEBUG` (5) `SEVERITY_NUMBER_DEBUG2` (6) `SEVERITY_NUMBER_DEBUG3` (7) `SEVERITY_NUMBER_DEBUG4` (8)	"debug" "debug2" "debug3" "debug4"	`DEBUG` (100)
`SEVERITY_NUMBER_INFO` (9) `SEVERITY_NUMBER_INFO2` (10)	"info" "info2"	`INFO` (200)
`SEVERITY_NUMBER_INFO3` (11) `SEVERITY_NUMBER_INFO4` (12)	"notice" "info3" "info4"	`NOTICE` (300)
`SEVERITY_NUMBER_WARN` (13) `SEVERITY_NUMBER_WARN2` (14) `SEVERITY_NUMBER_WARN3` (15) `SEVERITY_NUMBER_WARN4` (16)	"warning" "warn" "warn2" "warn3" "warn4"	`WARNING` (400)
`SEVERITY_NUMBER_ERROR` (17) `SEVERITY_NUMBER_ERROR2` (18) `SEVERITY_NUMBER_ERROR3` (19) `SEVERITY_NUMBER_ERROR4` (20)	"error" "error2" "error3" "error4"	`ERROR` (500)
`SEVERITY_NUMBER_FATAL` (21) `SEVERITY_NUMBER_FATAL2` (22)	"critical" "fatal" "fatal2"	`CRITICAL` (600)
`SEVERITY_NUMBER_FATAL3` (23)	"alert" "fatal3"	`ALERT` (700)
`SEVERITY_NUMBER_FATAL4` (24)	"emergency" "fatal4"	`EMERGENCY` (800)

Kolom SourceLocation

Google Cloud Observability memetakan Kode OTLP berikut langsung ke kolom LogEntry. Pemetaan ini dapat dilakukan karena atribut OpenTelemetry ini secara semantik identik dengan konsep Cloud Logging.

OpenTelemetry `LogRecord.attribute` pasangan nilai kunci.	Nilai yang disimpan di kolom `LogEntry` berikut (Nama dari referensi HTTP)	Jenis yang Diterima
`code.file.path: Value`	`sourceLocation.file`	string
`code.function.name: Value`	`sourceLocation.function`	string
`code.function.number: Value`	`sourceLocation.line`	string, int

Batasan

Bagian ini menjelaskan batas. Bagian ini juga menjelaskan cara Google Cloud Observability menangani jenis data tertentu.

Batas

Deskripsi	Nilai	Catatan
Jumlah maksimum log per permintaan OTLP	8192	Mengacu pada jumlah maksimum `logRecords` dalam struktur OTLP `resourceLogs`. Batas.
Ukuran maksimum setiap permintaan	5 MiB	Batas.
Ukuran maksimum `LogEntry` yang dibuat dari rekaman log OTLP	256 KiB	Cloud Logging memangkas atau menghapus data dari rekaman log OTLP jika diperlukan. Batas.
Panjang maksimum kunci atribut	512 B	Kunci label yang terlalu besar akan dipangkas saat rekaman log OTLP dikonversi menjadi `LogEntry`. Batas.
Panjang maksimum nilai atribut	64 KiB	Nilai label yang terlalu besar saat rekaman log OTLP dikonversi menjadi `LogEntry`. Batas.
Kedalaman maksimum nesting atribut	5	Atribut yang melebihi batas ini akan dipangkas saat rekaman log OTLP dikonversi menjadi `LogEntry`.
Jumlah maksimum byte penyerapan log per menit	2,4 GB untuk wilayah berikut: `asia-east1, asia-northeast1, asia-southeast1, asia-south1, europe-west1, europe-west2, europe-west3, europe-west4, us-central1, us-east4, us-west1`. 300 MB untuk semua region lainnya.	Kuota.

Perilaku

Jika nomor tingkat keparahan dan teks tingkat keparahan OpenTelemetry ditetapkan, sistem akan menggunakan nomor tingkat keparahan untuk menentukan tingkat keparahan Cloud Logging. Jika rekaman OTLP tidak berisi informasi tingkat keparahan, maka tingkat keparahan Cloud Logging akan ditetapkan ke DEFAULT.
Jika rekaman OTLP berisi kunci atribut duplikat, sistem akan mempertahankan kunci pertama dan menghapus atribut dengan kunci duplikat.
Sistem mengonversi atribut yang dilampirkan ke catatan log menjadi string. Sebagai contoh, lihat Kolom label.
Nama log harus aman untuk URL atau dienkode URL selama penyerapan. Untuk mengetahui informasi tentang cara menetapkan nama log, lihat Cara menetapkan kolom LogEntry.