Structured Logging — esensya, mga format ng data at prinsipyo ng paggawa sa mga aplikasyon

Ano ang Structured Logging

Structured Logging ay isang paraan ng pag-log kung saan ang bawat mensahe ay naglalaman ng mga pinangalanang field na may naka-type na mga halaga. Sa halip na isang string tulad ng User 42 logged in from device ABC ang isang structured log ay mukhang isang set ng mga field: user_id=42, event=login, device_id=ABC, timestamp=2026-07-04T10:30:00Z.

Ang pangunahing bentahe ng mga structured log kumpara sa text log ay ang kakayahang mag-programmatic processing. Ang pag-parse ng mga text log ay nangangailangan ng mga regular na expression at mga palagay tungkol sa format ng string. Ang mga structured log ay nai-parse nang walang pagkawala: bawat field ay may kilalang uri at pangalan, na nagpapahintulot sa pagbuo ng mga query tulad ng hanapin ang lahat ng error sa awtorisasyon sa nakaraang oras para sa gumagamit 42 nang walang karagdagang pagproseso.

Ayon sa datos ng Honeycomb.io (2023), ang mga team na gumagamit ng structured logging sa production ay nakakatuklas ng mga insidente nang average na 4 na beses na mas mabilis kumpara sa mga team na umaasa sa text log at grep.

Mga format ng structured log

Structured Logging ay sumusuporta sa maraming format ng serialization. Ang pagpili ng format ay depende sa imprastraktura: JSON ay maginhawa para sa pagsasama sa Elasticsearch at mga cloud system, logfmt — para sa console viewing sa pamamagitan ng tail at grep, Protocol Buffers — para sa high-performance system na may limitasyon sa bandwidth.

JSON — unibersal na format

JSON ay ang pinakakaraniwang format para sa mga structured log. Ito ay native na sinusuportahan ng lahat ng sistema ng pagkolekta: Logstash, Fluentd, Amazon CloudWatch, Google Cloud Logging. Ang mga JSON log ay madaling basahin ng tao at i-parse ng anumang programming language nang walang karagdagang library. Ang pangunahing disbentaha — redundancy: bawat key-value pair ay nangangailangan ng mga panipi at tutuldok, na nagpapataas ng volume ng nakaimbak na data ng 30–50% kumpara sa logfmt.

Logfmt — compact na format

Logfmt ay binuo sa Heroku para sa console visibility. Ito ay mas compact kaysa JSON, nagpapanatili ng pagiging nababasa ng tao at madaling maputol sa pamamagitan ng cut at awk. Halimbawa: ts=2026-07-04T10:30:00Z level=error module=api status=500. Ang Logfmt ay hindi nangangailangan ng pag-escape ng karamihan ng mga character at angkop para sa stdout-logging sa mga container.

Bakit kailangan ang Structured Logging sa mobile development

Sa mga mobile application, Structured Logging ay lumulutas ng tatlong pangunahing gawain: paghahanap ng mga sanhi ng crash nang walang reproduksyon sa device, pagsubaybay sa mga sesyon ng gumagamit at pagsusuri ng pagganap ayon sa mga bersyon ng application.

Ang mga text log sa mga mobile device ay halos walang silbi — ang developer ay hindi maaaring mag-grep ng mga log sa device ng gumagamit. Ang mga structured log ay ipinapadala sa mga cloud system (Firebase, Sentry, Datadog) at nai-index doon. Maaaring bumuo ng query: ipakita ang lahat ng crash sa iOS 17.4, bersyon ng app 3.2, sa modyul na checkouts — at makakuha ng eksaktong seleksyon sa ilang segundo.

Ayon sa datos ng Sentry (2024), ang mga application na gumagamit ng structured breadcrumbs ay may 60% na mas maraming konteksto sa bawat ulat ng crash kumpara sa mga application na nagla-log lamang ng text ng error. Ito ay direktang nakakaapekto sa bilis ng pag-aayos ng bug.

Mga kasangkapan sa pagkolekta at pagsusuri

ELK Stack — Elasticsearch, Logstash, Kibana — nananatiling standard na imprastraktura para sa pagtatrabaho sa mga structured log. Ang Logstash ay tumatanggap ng mga log sa JSON, nagko-convert at nagpapadala sa Elasticsearch para sa pag-index, ang Kibana ay nagbibigay ng visual na interface para sa mga query at dashboard.

Para sa mga mobile application, popular ang mga cloud solution: Firebase Crashlytics na may custom na log, Sentry na may breadcrumbs, Datadog na may APM tracking. Tumatanggap sila ng mga structured log nang direkta mula sa mobile SDK at hindi nangangailangan ng pag-deploy ng sariling backend. Ang Firebase ay nag-aalok ng libreng pakete para sa pag-uulat ng crash, ang Sentry ay nagdaragdag ng distributed tracing, at ang Datadog ay nagsasama sa APM para sa sabay-sabay na pagsubaybay sa pagganap ng mga kahilingan sa client at server.

Grafana Loki — alternatibo sa Elasticsearch, na-optimize para sa mga log. Ang Loki ay hindi nag-i-index ng nilalaman ng mga mensahe bilang default, sa halip ay gumagamit ng mga label para sa pag-filter. Ito ay makabuluhang mas mura sa pag-iimbak at mas mabilis para sa mga query batay sa isang nakapirming set ng mga field.

// Structured logging sa pamamagitan ng Swift Logger papuntang JSON
struct StructuredLog {
    let event: String
    let attributes: [String: Any]
    let level: String

    func serialize() -> String {
        var base = "event=\(event) level=\(level)"
        for (key, value) in attributes {
            base += " \(key)=\(value)"
        }
        return base
    }
}

Pinakamahusay na kasanayan sa Structured Logging

Ang unang tuntunin ng structured logging: bawat mensahe ay dapat maglaman ng identifier ng kahilingan o sesyon. Nang walang konteksto, ang isang solong log ay walang silbi — hindi posible na maunawaan kung aling gumagamit o kahilingan ito nauukol. Magdagdag ng correlation ID sa simula ng sesyon at ipasa ito sa lahat ng layer ng application.

Ang pangalawang tuntunin: pag-type ng mga field. Ang mga numerical field (duration_ms, status_code, retry_count) ay dapat ipadala bilang mga numero, hindi bilang mga string. Ang Elasticsearch at mga katulad na sistema ay nag-i-index ng mga numero at string nang magkaiba: sa mga numero ay maaaring ilapat ang mga agregasyon (average, median, persentil), sa mga string — full-text na paghahanap. Ang maling pag-type ay nag-aalis ng posibilidad na bumuo ng mga analytical dashboard.

Ang ikatlong tuntunin: iwasan ang mga nested object. Ang mga JSON log na may lalim ng nesting na higit sa 2 antas ay mahirap i-filter at i-visualize. Sa halip na {"user": {"name": "Alice", "role": "admin"}} gumamit ng flat keys: user_name=Alice user_role=admin.

// Structured logging sa Android sa pamamagitan ng Timber + logfmt
class StructuredTree : Timber.Tree() {
    override fun log(priority: Int, tag: String?,
                  message: String?, t: Throwable?) {
        val level = priorityToLevel(priority)
        val logfmt = "level=$level tag=$tag message=$message"
        sendToRemote(logfmt)
    }
}

Aling mga field ang mandatory

Minimum na set ng field para sa bawat structured na mensahe: timestamp sa ISO 8601, level (debug/info/warn/error/fatal), logger (pangalan ng modyul o klase), message (paglalarawan ng kaganapan na nababasa ng tao). Karagdagan: correlation_id, user_id (kung kilala), version (bersyon ng application), platform (iOS/Android), environment (dev/staging/prod).

Kung walang correlation_id ang mga structured log ay nagiging isang koleksyon ng mga hiwa-hiwalay na tala na hindi maaaring iugnay sa isang solong senaryo ng gumagamit. Bumuo ng UUID sa bawat pagsisimula ng application at idagdag ito sa lahat ng log ng sesyon. Sa praktika, ang correlation_id ay dapat ipasa sa lahat ng layer: mula sa mga UI event hanggang sa mga network request at background task — kung hindi, ang bahagi ng mga log ay mananatiling walang konteksto at hindi makikilahok sa analitika. Sa end-to-end tracking, ang isang UUID ay nagpapahintulot sa pagkolekta ng kumpletong larawan ng landas ng gumagamit.

Mga halimbawa ng structured logging sa Swift at Kotlin

Sa iOS, ang structured logging ay maaaring ipatupad sa pamamagitan ng isang wrapper sa paligid ng os_log na nagse-serialize ng mga field sa logfmt format. Sa Android — sa pamamagitan ng Timber na may custom na Tree na nagko-convert ng mga mensahe sa JSON o logfmt bago ipadala sa server.

import OSLog

struct StructuredLogger {
    let subsystem: String
    let category: String

    func log(level: OSLogType,
              event: String,
              context: [String: Any]) {
        let oslogger = Logger(
            subsystem: subsystem,
            category: category
        )
        let fields = context.map {
            "\($0.key)=\($0.value)"
        }.joined(separator: " ")
        oslogger.log(level: level,
                     "\(event) \(fields)")
    }
}

Structured vs Unstructured: paghahambing ng mga paraan

Ang pagpili sa pagitan ng structured at text log ay depende sa yugto ng proyekto. Sa mga unang yugto ng pag-unlad, ang mga text log ay mas simple at mas mabilis — ang developer ay nagsusulat ng mensahe nang direkta nang walang karagdagang wrapper. Ngunit sa sandaling lumampas ang proyekto sa mga hangganan ng isang team o isang server, ang mga structured log ay nagiging mandatory.