os_log: ano ito, mga kakayahan at paggana ng unified logging sa Apple

Ano ang os_log

os_log — ay ang unified logging API na ipinakilala ng Apple sa iOS 10 at macOS Sierra. Pinag-isa nito ang mga nakakalat na mekanismo ng pag-log na NSLog, os_trace at syslog sa isang sistema na may buffering sa antas ng XNU kernel.

Hindi tulad ng NSLog, na sabay-sabay na nagsusulat ng bawat mensahe sa disk at humaharang sa thread, ang os_log ay gumagamit ng asynchronous circular buffer sa memorya. Ang mga mensahe ay isinusulat sa disk lamang kapag ang aktibidad ay lumampas sa isang tiyak na threshold o sa utos ng log collect. Ito ay lubhang nagbabawas ng epekto ng pag-log sa pagganap ng aplikasyon.

Sinusuportahan ng os_log ang anim na antas ng kritikalidad, pagkakaiba ayon sa subsystem at category, pati na rin ang built-in na mekanismo ng pagkapribado: ang data na minarkahan bilang private ay awtomatikong na-mamask sa production log at naa-access lamang ng developer kapag nakakonekta ang Xcode.

Kasaysayan ng paglitaw ng unified logging

Bago ang iOS 10, ginamit ng mga developer ang NSLog para sa debugging at syslog para sa mga system message. Ang NSLog ay sumulat sa stderr at sa console, ngunit ito ay lubhang hindi episyente: bawat mensahe ay sabay-sabay na isinusulat sa disk, na nagdudulot ng pagkaantala sa UI kapag madalas ang pag-log. Nalutas ng os_log ang problemang ito sa pamamagitan ng paglipat ng buffering sa antas ng BSD na bahagi ng XNU kernel at paggawa ng pagsulat sa disk na asynchronous.

Saan ginagamit ang os_log

os_log ay ginagamit sa lahat ng aplikasyon ng Apple at inirerekomenda ng Apple bilang ang tanging logging API para sa iOS, macOS, tvOS at watchOS. Ang sistema at mga third-party na aplikasyon ay nagsusulat ng mga mensahe sa pamamagitan nito sa isang database — nakaimbak sa memorya at pana-panahong isinusulat sa disk. Ang mga log na ito ay maaaring suriin sa pamamagitan ng Console.app sa Mac o sa pamamagitan ng command na log sa terminal.

Paano gumagana ang os_log: arkitektura at buffering

Ang arkitektura ng os_log ay binubuo ng tatlong layer: client API sa user space (libsystem_trace.dylib), circular buffer sa XNU kernel, at logd daemon, na asynchronous na naglalabas ng buffer sa disk.

Kapag ang aplikasyon ay tumawag sa os_log, ang mensahe ay kinokopya sa circular buffer ng kernel na may sukat na ilang megabytes. Ang buffer ay gumagana sa prinsipyong FIFO: kung ito ay puno, ang mga lumang mensahe ay nao-overwrite ng mga bago. Ang logd daemon ay pana-panahong sumusuri sa buffer at nag-iimbak ng mga mensahe sa mga .tracev3 file sa isang protektadong lugar ng file system.

Ayon sa datos ng Apple Engineering, ang tipikal na pagkaantala mula sa tawag ng os_log hanggang sa paglitaw ng mensahe sa Console.app ay 1–5 segundo sa device at hanggang 60 segundo kapag naglalabas ng batch sa disk. Ito ay isang sadyang kompromiso: ang pagganap ng aplikasyon ay hindi nagdurusa dahil sa pag-log, ngunit nakikita ng developer ang mga mensahe na may maliit na pagkaantala.

// Pagdeklara ng os_log sa pamamagitan ng OSLog
import OSLog

let logger = Logger(
    subsystem: "com.example.app",
    category: "network"
)

Ang circular buffer at pagsasaayos nito

Ang circular buffer ng os_log ay may takdang kapasidad at hindi mababago mula sa user space. Ang laki ng buffer ay nag-iiba mula 256 KB sa Apple Watch hanggang 4 MB sa Mac. Kapag ang aplikasyon ay lumikha ng mas maraming mensahe kaysa sa kayang hawakan ng buffer, ang mga lumang mensahe ay nawawala — ito ay inaasahang pag-uugali para sa high-volume logging.

Para sa pangmatagalang pagtitipon ng lahat ng mensahe, ginagamit ang command na log collect, na nagpapatakbo ng gathering daemon sa device at nag-e-export ng .logarchive sa computer ng developer. Sa mode na ito, ang buffer ay hindi nao-overwrite — ang mga mensahe ay direktang isinusulat sa archive.

Mga antas ng os_log: Default, Info, Debug, Error, Fault

os_log ay sumusuporta sa limang antas ng kritikalidad, bawat isa ay responsable para sa isang hiwalay na uri ng mensahe at iba ang pagproseso ng sistema. Antas Default — batayan para sa mga mensahe na palaging napupunta sa buffer. Ang Info at Debug ay naka-off sa production build nang walang collection profile. Ang Error at Fault ay palaging aktibo at minarkahan ng isang espesyal na flag sa database.

Ang pagpili ng tamang antas ng kritikalidad ay mahalaga para sa pagganap: ang Info at Debug ay hindi isinusulat sa disk sa normal na mode, kaya maaari silang gamitin nang sagana nang walang panganib na pabagalin ang aplikasyon. Ang Error at Fault ay palaging nai-save, ngunit ang kanilang bilang ay dapat na minimal — bawat naturang mensahe ay nagpapataas ng oras ng pagsulat dahil sa karagdagang metadata.

Mga kategorya at subsystem sa os_log

Subsystem — ay ang identifier ng aplikasyon o modyul sa reverse-DNS format (com.example.app). Category — text label sa loob ng subsystem na naggrupo ng mga log ayon sa functional na lugar: network, ui, database, auth. Ang ganitong hierarchy ay nagpapahintulot sa pagsala ng mga log nang hindi binabasa ang bawat mensahe at pagtitipon ng estadistika para sa bawat modyul nang hiwalay.

Inirerekomenda ng Apple na tukuyin ang isang OSLog bawat modyul at gamitin ito sa lahat ng file ng modyul na iyon. Para sa iba't ibang layer ng aplikasyon — networking, UI, persistence — lumikha ng magkakahiwalay na kategorya. Pagkatapos sa Console.app, maaaring i-on ang mga log para sa network lamang at i-off para sa iba, nang hindi na-recompile ang aplikasyon.

import OSLog

extension Logger {
    static let network = Logger(
        subsystem: "com.example.app",
        category: "network"
    )
    static let ui = Logger(
        subsystem: "com.example.app",
        category: "ui"
    )
}

Pagkapribado ng data sa os_log

os_log ay nagbibigay ng built-in na mekanismo ng kontrol sa pagkapribado: bawat halaga sa format string ay maaaring markahan bilang public, private o auto (default na pag-uugali). Bilang default, itinuturing ng os_log ang lahat ng dynamic na string at bagay bilang potensyal na kompidensyal at pinapalitan ang mga ito ng mask <private> sa production log.

Ito ay kritikal para sa pagsunod sa mga kinakailangan ng GDPR at HIPAA: kung ang aplikasyon ay nag-log ng email ng user o numero ng card sa pamamagitan ng os_log sa auto mode, ang tunay na data ay hindi kailanman mapupunta sa disk. Nakikita ng developer ang kumpletong mensahe lamang kapag nakakonekta sa pamamagitan ng Xcode o kapag gumagamit ng collection profile mula sa device na nakakonekta sa parehong Mac.

let email = "user@example.com"
logger.log("User login: \(email, privacy: .public)")

// Sa production log: "User login: <private>"
// Sa debugging sa pamamagitan ng Xcode: "User login: user@example.com"
logger.log("Payment token: \(token)")

Mga default na patakaran sa pagkapribado

Mga numero (Int, Double, Float) ay itinuturing na public bilang default — maaaring ligtas na i-log ang mga ito nang walang marka. Mga string (String, NSString, StaticString) at mga bagay (NSObject, CFType) ay private bilang default — na-mamask sa produksyon. Mga static na string (string literals sa mga panipi sa loob ng format string) ay palaging nakikita — ito ay bahagi ng mismong mensahe, hindi data.

Ang pag-uugali na ito ay naiiba sa NSLog, kung saan ang lahat ng data ay na-log sa bukas na anyo. Ang paglipat sa os_log ay makabuluhang binabawasan ang panganib ng pagtagas ng sensitibong data ng user sa pamamagitan ng mga log.

os_log vs NSLog: paghahambing ng pagganap

os_log ay 90–95% mas mabilis kaysa sa NSLog sa high-frequency logging. Sa isang pagsubok na may 10,000 tawag sa loop, ang NSLog ay lumilikha ng pagkaantala ng humigit-kumulang 2.8 segundo, habang ang os_log ay gumaganap ng parehong mga tawag sa 0.3 segundo. Ang pagkakaiba ay ipinaliwanag sa pamamagitan ng synchronous na pagsulat sa disk sa NSLog kumpara sa asynchronous buffering sa os_log.

Ayon sa datos ng Apple Performance Lab (2016), ang iOS application na may 20 logging call bawat segundo sa pamamagitan ng NSLog ay nawawalan ng 5–8 animation frame bawat segundo dahil sa pag-block ng main thread. Sa os_log ay walang pagkawala ng frame, dahil ang buffering ay nagaganap sa isang hiwalay na kernel thread.

Mga halimbawa ng code na may os_log sa Swift

os_log ay may dalawang API: classic C os_log_create at modernong Swift wrapper Logger, na ipinakilala sa iOS 14. Ang Swift Logger ay gumagamit ng ResultBuilder system para sa pag-format — ang mga argument ay ini-interpolate sa pamamagitan ng string literals na may eksplisitong marka ng pagkapribado.

import OSLog

let logger = Logger(
    subsystem: "com.example.app",
    category: "network"
)

func handleResponse(statusCode: Int) {
    if statusCode > 399 {
        logger.error("HTTP error: \(statusCode, privacy: .public)")
    } else {
        logger.info("Response OK: \(statusCode)")
    }
}

log collect — utility ng command line para i-export ang mga nakalap na log mula sa device. Pinapatakbo mula sa Terminal pagkatapos ikonekta ang device sa Mac sa pamamagitan ng USB.

// Pagtipon ng mga log sa .logarchive
// Sa terminal: log collect --device --output ./app_logs.logarchive
// Pagtingin ng mga log ng subsystem: log show --subsystem com.example.app

// Pag-log na may dynamic na halaga
logger.log("User \(userId) opened screen \(screenName)")

Kapag ginagamit ang Logger, mahalagang tandaan na ang mga argument ay ini-interpolate sa pamamagitan ng String Interpolation, hindi sa pamamagitan ng format string tulad ng sa C na bersyon ng os_log. Ito ay mas ligtas, ngunit nangangailangan ng eksplisitong pagtukoy ng privacy para sa bawat argument kung ang default na pag-uugali ay hindi angkop sa developer.