Structured Logging — mahiyyəti, data formatları və tətbiqlərdə iş prinsipi

Structured Logging nədir

Structured Logging — hər bir mesajın tipli dəyərlərlə adlandırılmış sahələr ehtiva etdiyi log yazma üsuludur. User 42 logged in from device ABC kimi sətir əvəzinə strukturlaşdırılmış log sahələr dəsti kimi görünür: user_id=42, event=login, device_id=ABC, timestamp=2026-07-04T10:30:00Z.

Strukturlaşdırılmış logların mətn loglarından əsas üstünlüyü proqram emalı imkanıdır. Mətn loglarının pars edilməsi müntəzəm ifadələr və sətir formatı haqqında fərziyyələr tələb edir. Strukturlaşdırılmış loglar itkisiz pars edilir: hər sahənin məlum tipi və adı var ki, bu da əlavə emal olmadan son bir saat ərzində istifadəçi 42 üçün bütün avtorizasiya xətalarını tap səviyyəsində sorğular qurmağa imkan verir.

Honeycomb.io (2023) məlumatlarına görə, istehsalda structured logging istifadə edən komandalar hadisələri mətn loglarına və grep-ə güvənən komandalarla müqayisədə orta hesabla 4 dəfə daha sürətli aşkarlayır.

Strukturlaşdırılmış log formatları

Structured Logging bir neçə seriyalaşdırma formatını dəstəkləyir. Format seçimi infrastrukturdan asılıdır: JSON Elasticsearch və bulud sistemləri ilə inteqrasiya üçün əlverişlidir, logfmt — tail və grep ilə konsol baxışı üçün, Protocol Buffers — yüksək məhsuldar, ötürmə qabiliyyəti məhdud sistemlər üçün.

JSON — universal format

JSON strukturlaşdırılmış loglar üçün ən geniş yayılmış formatdır. Bütün toplama sistemləri tərəfindən yerli olaraq dəstəklənir: Logstash, Fluentd, Amazon CloudWatch, Google Cloud Logging. JSON logları insan tərəfindən asan oxunur və əlavə kitabxanalar olmadan istənilən proqramlaşdırma dili ilə pars edilir. Əsas çatışmazlıq — artıqlıq: hər bir açar-dəyər cütü dırnaq işarələri və iki nöqtə tələb edir ki, bu da saxlanılan məlumatların həcmini logfmt-la müqayisədə 30–50% artırır.

Logfmt — kompakt format

Logfmt Heroku-da konsol görünməsi üçün hazırlanmışdır. JSON-dan daha kompaktdır, insan oxumasını qoruyur və cut və awk ilə asanlıqla kəsilir. Nümunə: ts=2026-07-04T10:30:00Z level=error module=api status=500. Logfmt əksər simvolların ekranlaşdırılmasını tələb etmir və konteynerlərdə stdout-loglama üçün yaxşı uyğundur.

Structured Logging mobil inkişafda nə üçün lazımdır

Mobil tətbiqlərdə Structured Logging üç əsas vəzifəni həll edir: cihazda təkrar istehsal etmədən çökmə səbəblərini tapmaq, istifadəçi sessiyalarını izləmək və tətbiq versiyaları üzrə performansı analiz etmək.

Mobil cihazlarda mətn logları demək olar ki, faydasızdır — tərtibatçı istifadəçinin cihazında logları grep edə bilməz. Strukturlaşdırılmış loglar bulud sistemlərinə (Firebase, Sentry, Datadog) göndərilir və orada indekslənir. Sorğu qurmaq olar: iOS 17.4-də bütün crash-ləri göstər, tətbiq versiyası 3.2, checkouts modulunda — və bir neçə saniyə ərzində dəqiq seçim əldə etmək.

Sentry (2024) məlumatlarına görə, structured breadcrumbs istifadə edən tətbiqlər yalnız xəta mətnini loglayan tətbiqlərlə müqayisədə hər crash hesabatında 60% daha çox kontekstə malikdir. Bu, birbaşa səhvin düzəliş sürətinə təsir edir.

Toplama və analiz alətləri

ELK Stack — Elasticsearch, Logstash, Kibana — strukturlaşdırılmış loglarla iş üçün standart infrastruktur olaraq qalır. Logstash logları JSON-da qəbul edir, çevirir və indeksasiya üçün Elasticsearch-ə göndərir, Kibana sorğular və dashboardlar üçün vizual interfeys təmin edir.

Mobil tətbiqlər üçün bulud həlləri populyardır: Firebase Crashlytics xüsusi loglarla, Sentry breadcrumbs ilə, Datadog APM izləmə ilə. Onlar strukturlaşdırılmış logları birbaşa mobil SDK-dan qəbul edir və öz backend-in yerləşdirilməsini tələb etmir. Firebase crash hesabatları üçün pulsuz paket təqdim edir, Sentry distributed tracing əlavə edir, Datadog isə eyni anda müştəri və serverdə sorğu performansını izləmək üçün APM ilə inteqrasiya olunur.

Grafana Loki — loglar üçün optimallaşdırılmış Elasticsearch alternatividir. Loki standart olaraq mesaj məzmununu indeksləmir, filtrləmə üçün etiketlərdən (labels) istifadə edir. Bu, saxlamada əhəmiyyətli dərəcədə ucuzdur və sabit sahələr dəsti üzrə sorğularda daha sürətlidir.

// Structured logging Swift Logger vasitəsilə JSON-da
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
    }
}

Structured Logging ən yaxşı təcrübələri

Strukturlaşdırılmış loglamanın birinci qaydası: hər bir mesaj sorğu və ya sessiya identifikatoru ehtiva etməlidir. Kontekst olmadan tək bir log faydasızdır — hansı istifadəçiyə və ya sorğuya aid olduğunu anlamaq mümkün deyil. Sessiyanın başlanğıcında correlation ID əlavə edin və onu tətbiqin bütün təbəqələrindən ötürün.

İkinci qayda: sahələrin tipləşdirilməsi. Rəqəm sahələri (duration_ms, status_code, retry_count) sətir kimi deyil, rəqəm kimi ötürülməlidir. Elasticsearch və oxşar sistemlər rəqəmləri və sətirləri fərqli indeksləşdirir: rəqəmlərə aqreqasiyalar (orta, median, persentil) tətbiq oluna bilər, sətirlərə — tam mətn axtarışı. Yanlış tipləşdirmə analitik dashboardlar qurmaq imkanını əlindən alır.

Üçüncü qayda: iç-içə obyektlərdən qaçın. 2 səviyyədən dərin iç-içə JSON loglarını filtrləmək və vizuallaşdırmaq çətindir. {"user": {"name": "Alice", "role": "admin"}} əvəzinə düz açarlardan istifadə edin: user_name=Alice user_role=admin.

// Structured logging Android-də Timber + logfmt vasitəsilə
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)
    }
}

Hansı sahələr məcburidir

Hər bir strukturlaşdırılmış mesaj üçün minimal sahə dəsti: timestamp ISO 8601 formatında, level (debug/info/warn/error/fatal), logger (modul və ya sinif adı), message (hadisənin insan oxuna bilən təsviri). Əlavə olaraq: correlation_id, user_id (məlumdursa), version (tətbiq versiyası), platform (iOS/Android), environment (dev/staging/prod).

Correlation ID olmadan strukturlaşdırılmış loglar bir istifadəçi ssenarisində birləşdirilə bilməyən dağınıq qeydlər dəstinə çevrilir. Hər tətbiq işə salındıqda UUID yaradın və onu bütün sessiya loglarına əlavə edin. Praktikada correlation ID bütün təbəqələrdən ötürülməlidir: UI hadisələrindən şəbəkə sorğularına və fon tapşırıqlarına qədər — əks halda logların bir hissəsi kontekstsiz qalacaq və analitikada iştirak etməyəcək. Uçdan-uca izləmədə bir UUID istifadəçi yolunun tam şəklini toplamağa imkan verir.

Swift və Kotlin-də strukturlaşdırılmış loglama nümunələri

iOS-da strukturlaşdırılmış loglama os_log üzərində sahələri logfmt formatına seriyalaşdıran sarğı vasitəsilə həyata keçirilə bilər. Android-də — serverə göndərməzdən əvvəl mesajları JSON və ya logfmt-ə çevirən xüsusi Tree ilə Timber vasitəsilə.

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: yanaşmaların müqayisəsi

Strukturlaşdırılmış və mətn logları arasında seçim layihənin mərhələsindən asılıdır. İnkişafın ilkin mərhələlərində mətn logları daha sadə və sürətlidir — tərtibatçı mesajı birbaşa əlavə sarğılar olmadan yazır. Lakin layihə bir komanda və ya bir server hüdudlarından kənara çıxan kimi, strukturlaşdırılmış loglar məcburi olur.