Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Pemetaan rekaman log OTLP ke entri log

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

Eksportir Google Cloud untuk Cloud Logging mengonversi data log berformat OTLP menjadi objekLogEntry. Kemudian, agen ini mengirimkan data ini ke project Google Cloud Anda menggunakan Cloud Logging API. Namun, aturan default yang digunakan Google Cloud Observability dan pengekspor untuk membuat entri log berbeda. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi Google Cloud Observability untuk menggunakan pemetaan pengekspor.

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 sebagai berikut:

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

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

Saat Google Cloud Observability 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 nilai kolom `event_name` pada `LogRecord` OTLP. Jika kolom tersebut tidak ada atau tidak ditetapkan, sistem akan menggunakan daftar atribut data log OpenTelemetry yang diprioritaskan berikut untuk menentukan nama log: `log.name` `gcp.log.name` `log_name` `gcp.log_name` `logging.googleapis.com/logName` `service.name` `gcp.service.name` `service_name` `gcp.service_name` `event.name` `gcp.event.name` `event_name` `gcp.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 prioritas kolom data log OpenTelemetry berikut untuk menentukan `timestamp`: `time_unix_nano` jika bukan nol. `observed_time_unix_nano` jika bukan nol. Waktu penyerapan entri log. Periode retensi untuk bucket log yang menyimpan data menentukan stempel waktu terlama yang dapat diserap. Untuk mengetahui informasi selengkapnya, lihat Kuota Cloud Logging.
`receiveTimestamp`	Ditetapkan ke waktu saat `LogEntry` diserap.
`severity`	Sistem memetakan tingkat keseriusan OpenTelemetry dalam data log ke tingkat keseriusan Cloud Logging. Untuk mengetahui detailnya, lihat Kolom tingkat keparahan.
`httpRequest`	Sistem akan memetakan atribut `gcp.http_request` dalam data log ke kolom `LogEntry` yang setara. Sistem menerima atribut ini sebagai atribut terstruktur atau sebagai string JSON. Untuk mengetahui informasi selengkapnya, lihat kolom HttpRequest.
`labels`	Sistem menetapkan kolom ini menggunakan nilai atribut data log. Untuk mengetahui informasi selengkapnya, lihat Kolom label.
`trace`	Sistem menetapkan kolom ini ke nilai dari kolom `traceId` data log. Nilai harus berupa string heksadesimal 32 karakter yang valid, atau entri akan ditolak.
`spanId`	Sistem menetapkan kolom ini ke nilai dari kolom `spanId` data log. Nilainya harus berupa string heksadesimal 16 karakter yang valid, atau entri akan ditolak.
`traceSampled`	Sistem menetapkan kolom ini berdasarkan bit yang paling tidak signifikan dari kolom `flags` data log. Jika bit paling tidak signifikan sama dengan `1`, kolom ini akan ditetapkan ke `true`; jika tidak, kolom ini akan tetap tidak ditetapkan.
`sourceLocation`	Sistem menetapkan kolom ini ke nilai dari atribut Code data log. Untuk mengetahui informasi selengkapnya, lihat Kolom SourceLocation.
`split`	Tidak ditetapkan.
`apphub` `apphubDestination` `apphubSource`	Tidak 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.
`operation`	Sistem akan memetakan atribut `gcp.operation` dalam data log ke kolom `LogEntry` yang setara. Untuk mengetahui informasi selengkapnya, lihat Kolom operasi.
Payload	Sistem menetapkan payload dengan mengonversi isi data log ke jenis payload yang sesuai. Untuk 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 data log yang berisi dua atribut, yang masing-masing berisi setidaknya satu atribut lain:

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

Format kolom gcp.http_request dapat berupa atribut bertingkat terstruktur atau string JSON dari atribut terstruktur.

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

Dalam tabel, atribut bertingkat ditampilkan menggunakan tanda kurung kurawal. Misalnya, gcp.http_request {requestMethod} berarti atribut gcp.http_request berisi atribut requestMethod. Nilai dari atribut terdalam 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 akan melakukan tindakan berikut:

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

Misalnya, ada atribut yang dilampirkan ke data 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 array atau elemen JSON, sistem akan mengonversi nilai menjadi string.

Misalnya, berikut ini ilustrasi 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 tingkatan bertingkat yang lebih dalam akan dipotong.

Kolom operasi

Google Cloud Observability memetakan atribut OTLP yang berlaku untuk operasi ke kolom operation dari LogEntry. Bagian berikut menjelaskan cara sistem memetakan atribut bertingkat.

Atribut gcp.operation harus berisi jenis nilai kunci. Nama atribut yang di-flatten tidak didukung. Contoh berikut mengilustrasikan data log yang atribut gcp.operation-nya berisi empat key-value pair:

log_record {
  attributes: {
    gcp.operation {
      "id": "abc123",
      "producer": "my_producer",
      "first": "true",
      "last": "false",
    }
  }
}

Tabel berikut menjelaskan cara Google Cloud Observability memetakan gcp.operation ke LogEntry:

OpenTelemetry `LogRecord.attribute.operation` pasangan nilai kunci.	Nilai yang disimpan di kolom operasi `LogEntry` berikut	Jenis yang Diterima
`id`	`id`	string
`producer`	`httpRequest.requestUrl`	string
`first`	`first`	bool
`last`	`last`	bool

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 menjadi 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 akan menyalin string ke kolom LogEntry.textPayload.
Array: Sistem akan membuat string elemen array sambil mempertahankan baris baru. Kemudian, string tersebut akan disalin ke kolom LogEntry.textPayload.
KeyValueList: Sistem mengonversi pasangan tersebut menjadi JSON, lalu mengisi kolom LogEntry.jsonPayload, dengan batasan berikut:
- Jika data OTLP berisi kunci atribut duplikat, sistem akan mempertahankan kunci pertama dan menghapus atribut dengan kunci duplikat.
- Jika kedalaman bertingkat untuk pasangan JSON lebih besar dari lima, sistem akan memotong 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 nomor tingkat keparahan dan teks tingkat keparahan. logs.proto menentukan nomor tingkat keparahan.

Google Cloud Observability menentukan tingkat keparahan Logging dari nomor tingkat keparahan OpenTelemetry, jika ditetapkan. Jika tidak, kolom ini akan menggunakan teks tingkat keparahan. 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" not set	`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 Code 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 `resourceLogs` OTLP. Batas.
Ukuran maksimum setiap permintaan	5 MiB	Batas.
Ukuran maksimum `LogEntry` yang dibuat dari data log OTLP	256 KiB	Cloud Logging memotong atau menghapus data dari data log OTLP jika diperlukan. Batas.
Panjang maksimum kunci atribut	512 B	Kunci label yang terlalu besar akan dipotong saat data log OTLP dikonversi menjadi `LogEntry`. Batas.
Panjang maksimum nilai atribut	64 KiB	Nilai label yang terlalu besar saat data log OTLP dikonversi menjadi `LogEntry`. Batas.
Kedalaman maksimum penyusunan bertingkat atribut	20	Permintaan dengan atribut yang melebihi batas ini akan ditolak saat data log OTLP dikonversi menjadi `LogEntry`.
Jumlah maksimum byte penyerapan log per menit	2,4 GB untuk region 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 data OTLP tidak berisi informasi tingkat keseriusan, tingkat keseriusan Cloud Logging akan ditetapkan ke DEFAULT.
Jika data OTLP berisi kunci atribut duplikat, sistem akan mempertahankan kunci pertama dan menghapus atribut dengan kunci duplikat.
Sistem mengonversi atribut yang dilampirkan ke data 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 kolom LogEntry ditetapkan.

Mengonfigurasi Google Cloud Observability untuk menggunakan pemetaan pengekspor

Google Cloud Observability dan pengekspor Google Cloud untuk Cloud Logging menggunakan aturan yang berbeda untuk membuat objek LogEntry dari data log berformat OTLP. Misalnya, Google Cloud Observability mengisi kolom otel, tetapi pengekspor tidak.

Jika Anda ingin Google Cloud Observability menggunakan aturan pemetaan yang sama dengan pengekspor, lakukan perubahan berikut pada aplikasi Anda yang mengirim data log OTLP ke Telemetry API:

Tambahkan atribut gcp.use_legacy_mapping ke resource yang disertakan dalam permintaan. Untuk mengetahui informasi selengkapnya, lihat Menambahkan atau menghapus atribut.

Jika atribut ini ditetapkan, hal berikut akan terjadi:
1. Kolom otel tidak diisi.
2. Atribut yang diawali dengan gcp akan dihapus dengan pengecualian berikut:
  - gcp.log.name
  - gcp.insert_id
  Dua atribut sebelumnya dipetakan ke kolom LogEntry.
Aturan pemetaan lama menyebabkan Google Cloud Observability menghapus beberapa konten. Namun, ukuran objek LogEntry lebih kecil.
Tambahkan pemroses ke kolektor HTTP OTLP Anda yang menetapkan label log berikut:
- Tetapkan instrumentation_scope ke instrumentation_scope.name.
- instrumentation_version: Tetapkan ke instrumentation_scope.version.
- service.name: Tetapkan ke resource.attributes["service.name"].
- Tetapkan service.namespace ke resource.attributes["service.namespace"].
- service.instance.id: Tetapkan ke resource.attributes["service.instance.id"].
Sebagai contoh, lihat Bermigrasi ke pengekspor OTLP: Pemroses.