Логи

Лог — це текстовий запис з часовою міткою, структурований (рекомендовано) або неструктурований, з додатковими метаданими. З усіх сигналів телеметрії, логи мають найбільшу спадщину. Більшість мов програмування мають вбудовані можливості логування або добре відомі, широко використовувані бібліотеки логування.

Логи OpenTelemetry

OpenTelemetry надає API та SDK для створення записів логів, а також SDK для мов та мости для логів для інтеграції з наявними фреймворками логів. Логи — це все, що ви надсилаєте через провайдера логів, а події — це особливий тип логів. Не всі логи є подіями, але всі події є логами. API логів є публічним і може використовуватися безпосередньо кодом програми або опосередковано через наявні бібліотеки та мости логів.

OpenTelemetry призначений для роботи з логами, які ви вже створюєте, і пропонує інструменти для кореляції логів з іншими сигналами, додавання контекстних атрибутів та нормалізації різних джерел у загальну форму для обробки та експорту.

Логи OpenTelemetry в OpenTelemetry Collector

OpenTelemetry Collector надає кілька інструментів для роботи з логами:

• Кілька приймачів, які аналізують логи з конкретних, відомих джерел даних логів.
• filelogreceiver, який читає логи з будь-якого файлу та надає можливості аналізувати їх з різних форматів або використовувати регулярний вираз.
• Процесори, такі як transformprocessor, які дозволяють аналізувати вкладені дані, спрощувати вкладені структури, додавати/видаляти/оновлювати значення та інше.
• Експортери, які дозволяють виводити дані логів у не-OpenTelemetry форматі.

Перший крок у впровадженні OpenTelemetry часто включає розгортання Collector як універсального агента логування.

Логи OpenTelemetry для застосунків

У застосунках логи OpenTelemetry створюються за допомогою будь-якої бібліотеки логування або вбудованих можливостей логування. Коли ви додаєте автоінструментування або активуєте SDK, OpenTelemetry автоматично корелює ваші наявні логи з будь-яким активним трейсом та відрізком, обгортаючи тіло логу їхніми ідентифікаторами. Іншими словами, OpenTelemetry автоматично корелює ваші логи та трейси.

Підтримка мов

Логи є стабільним сигналом у специфікації OpenTelemetry. Для індивідуальних мовних специфічних реалізацій API та SDK логів, статус наступний:

Структуровані, неструктуровані та напівструктуровані логи

OpenTelemetry приймає будь-який формат логів, але не всі формати однаково корисні для аналізу. У наступному розділі пояснюються відмінності між структурованими, напівструктурованими та неструктурованими логами. Важливо: лог, закодований у форматі JSON, не є автоматично «структурованим» у сенсі наявності стабільної схеми — він може бути напівструктурованим. Структуровані логи передбачають наявність послідовної схеми або чітко визначених типів полів, на які можна надійно покладатися під час подальшої обробки.

Структуровані логи

Структурований лог — це лог із визначеною, послідовною схемою або типізованими полями, які системи нижчого рівня можуть надійно аналізувати та інтерпретувати. Текстове кодування може бути JSON, protobuf або іншим форматом, але те, що робить лог структурованим, — це наявність стабільної схеми (імен полів, типів і семантики), а не лише те, що він є дійсним JSON. Наприклад, структурований JSON-лог може виглядати так:

{
  "timestamp": "2024-08-04T12:34:56.789Z",
  "level": "INFO",
  "service": "user-authentication",
  "environment": "production",
  "message": "User login successful",
  "context": {
    "userId": "12345",
    "username": "johndoe",
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36"
  },
  "transactionId": "abcd-efgh-ijkl-mnop",
  "duration": 200,
  "request": {
    "method": "POST",
    "url": "/api/v1/login",
    "headers": {
      "Content-Type": "application/json",
      "Accept": "application/json"
    },
    "body": {
      "username": "johndoe",
      "password": "******"
    }
  },
  "response": {
    "statusCode": 200,
    "body": {
      "success": true,
      "token": "jwt-token-here"
    }
  }
}

а для інфраструктурних компонентів, часто використовується Common Log Format (CLF) :

127.0.0.1 - johndoe [04/Aug/2024:12:34:56 -0400] "POST /api/v1/login HTTP/1.1" 200 1234

Також часто зустрічаються гібридні або розширені формати (наприклад, поля CLF у поєднанні з кінцевим блоком JSON).

192.168.1.1 - johndoe [04/Aug/2024:12:34:56 -0400] "POST /api/v1/login HTTP/1.1" 200 1234 "http://example.com" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36" {"transactionId": "abcd-efgh-ijkl-mnop", "responseTime": 150, "requestBody": {"username": "johndoe"}, "responseHeaders": {"Content-Type": "application/json"}}

У таких випадках обробіть або витягніть необхідні частини в нормалізований запис, щоб інструменти нижчого рівня могли їх послідовно аналізувати. filelogreceiver в [OpenTelemetry Collector] (/docs/collector) надає допоміжні засоби для обробки змішаних форматів.

Структуровані логи є кращими для використання у промисловій експлуатації, оскільки їх стабільна схема робить їх простими для перевірки, обробки, кореляції з трейсами та метриками, а також аналізу в масштабі.

Неструктуровані логи

Неструктуровані логи — це логи, які не дотримуються послідовної структури. Вони можуть бути більш зручними для читання людиною і часто використовуються у розробці. Однак, не рекомендується використовувати неструктуровані логи для промислової спостережуваності, оскільки їх набагато важче аналізувати та аналізувати в масштабі.

Приклади неструктурованих логів:

[ERROR] 2024-08-04 12:45:23 - Не вдалося підключитися до бази даних. Помилка: java.sql.SQLException: Час очікування закінчився. Спроба повторного підключення 3 рази. Сервер: db.example.com, Порт: 5432

Перезавантаження системи ініційовано 2024-08-04 03:00:00 користувачем: admin. Причина: Заплановане обслуговування. Зупинені сервіси: веб-сервер, база даних, кеш. Оцінений час простою: 15 хвилин.

DEBUG - 2024-08-04 09:30:15 - Користувач johndoe виконав дію: завантаження файлу. Імʼя файлу: report_Q3_2024.pdf, Розмір: 2.3 MB, Тривалість: 5.2 секунди. Результат: Успіх

Можливо зберігати та аналізувати неструктуровані логи у промисловій експлуатації, хоча вам може знадобитися значна робота для їх аналізу або попередньої обробки, щоб вони були машиночитними. Наприклад, вищезазначені три логи потребуватимуть регулярного виразу для аналізу їх часових міток та спеціальних парсерів для послідовного отримання тіл повідомлень логів. Це зазвичай необхідно для того, щоб бекенд логування знав, як сортувати та організовувати логи за часовою міткою. Хоча можливо аналізувати неструктуровані логи для цілей аналізу, це може бути більше роботи, ніж перехід на структуроване логування, наприклад, через стандартний фреймворк логування у ваших застосунках.

Напівструктуровані логи

Напівструктуровані логи містять машиночитні пари ключ/значення або розділені поля, але не гарантують стабільної схеми для всіх джерел. Прикладами є логи ключ=значення (показані нижче) або JSON-блоки, де імена та типи полів різняться між повідомленнями. Напівструктуровані логи часто легше аналізувати, ніж неструктуровані, але все одно можуть потребувати обробки та нормалізації перед аналізом.

Приклад напівструктурованого логу:

2024-08-04T12:45:23Z level=ERROR service=user-authentication userId=12345 action=login message="Failed login attempt" error="Invalid password" ipAddress=192.168.1.1 userAgent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36"

Напівструктуровані логи можуть вимагати зіставлення та примусового перетворення типів під час імпорту, щоб бути повністю корисними для подальшого аналізу.

Компоненти логування OpenTelemetry

Наступні списки концепцій та компонентів забезпечують підтримку логування OpenTelemetry.

Доповнювач журналу/Міст

Як розробник застосунків, API моста логів не повинен викликатися вами безпосередньо, оскільки він надається для авторів бібліотек логування для створення доповнювачів логів/мостів. Натомість, ви просто використовуєте свою улюблену бібліотеку логування та налаштовуєте її для використання доповнювача логів (або моста для логів), який здатний виводити логи у OpenTelemetry LogRecordExporter.

SDK OpenTelemetry пропонують цю функціональність.

Постачальник логерів

Частина API моста логів і повинен використовуватися лише, якщо ви є автором бібліотеки логування.

Постачальник логерів (іноді називається LoggerProvider) є фабрикою для Loggerʼів. У більшості випадків постачальник логерів ініціалізується один раз і його життєвий цикл відповідає життєвому циклу застосунку. Ініціалізація постачальника логерів також включає ініціалізацію ресурсів та експортерів.

Логер

Частина API моста логів і повинен використовуватися лише, якщо ви є автором бібліотеки логування.

Логер створює записи логів. Логери створюються з постачальників логерів.

Експортер записів логів

Експортери записів логів відправляють записи логів споживачу. Цей споживач може бути стандартним виводом для налагодження та розробки, OpenTelemetry Collector, або будь-яким відкритим або бекендом постачальника на ваш вибір.

Запис логу

Запис логу представляє запис події. У OpenTelemetry запис логу містить два види полів:

• Іменовані поля верхнього рівня певного типу та значення
• Поля ресурсів та атрибутів довільного значення та типу

Поля верхнього рівня:

Для отримання додаткової інформації про записи логів та поля логів, дивіться Модель даних логів.

Специфікація

Щоб дізнатися більше про логи в OpenTelemetry, дивіться специфікацію логів.