Внесок у розробку процесора розгортання для OpenTelemetry Collector Contrib

Ідея розгортання обʼєднаних журналів всередині OpenTelemetry Collector не почалася з процесора.

Під «розгортанням» (“unrolling,) я маю на увазі взяття одного запису журналу, що містить кілька логічних подій, наприклад, масив JSON з десятьма записами журналу, і розширення його на десять окремих записів журналу, по одному для кожної події. Це дозволяє працювати з окремими записами журналу, а не з обʼєднаними даними.

Коли в Collector SIG вперше обговорювали проблему обробки журналів, що містять кілька логічних подій в одному тілі, наприклад масив JSON, першою інтуїтивною реакцією було вирішити її за допомогою функції OTTL (OpenTelemetry Transform Language) всередині процесора перетворення.

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

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

Процесор розгортання (unroll processor) розгортає пакетні записи у чіткий, детермінований спосіб. Після кількох місяців роботи у промислових умовах я хотів допомогти, передавши проєкту процесор розгортання, щоб спільнота OpenTelemetry могла скористатися спільним рішенням.

Дозвольте пояснити, що таке процесор розгортання, як він працює, як він може вам допомогти і як ми допомогли зробити внесок у дистрибутив Contrib.

Навіщо розгортати?

Основна проблема проста: деякі джерела передають кілька подій в одному записі журналу. Ви хочете працювати з чистими, окремими записами журналу.

До розгортання у вас було два варіанти:

1. Попередньо обробляти журнали поза колектором — якщо ви могли вставити логіку.
2. Спробувати змусити OTTL/transform робити те, для чого він не був призначений.

Жоден з цих підходів не виявився оптимальним для вирішення проблеми.

Що робить процесор розгортання

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

Якщо у вашому вхідному масиві JSON було десять обʼєктів, ви отримаєте десять окремих записів журналу. Кожен запис журналу збереже свої метадані і буде готовий до перетворення, фільтрування, скорочення — до всього, що вам потрібно.

Це просто, передбачувано і безпечно для використання у промисловій експлуатації.

Чому було вирішено відмовитися від OTTL?

Ми ретельно вивчили це питання.

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

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

Процесор розгортання чітко відокремлює проблему додавання записів від логіки трансформації і працює таким чином, що є як комбінованим, так і передбачуваним.

Я допомагав створювати першу версію процесора розгортання в Bindplane Distro of OpenTelemetry Collector. Він був вперше поставлений і почав використовуватися клієнтами в січні 2025 року і з того часу працює в промисловому режимі.

Я бачив, як клієнти використовують його в:

• Журналах VPC
• Конвеєрах CloudWatch
• Журналах Windows + endpoint
• Пакетній телеметрії колектора

Ми спостерігали дуже низький обсяг проблем навіть під реальним промисловим навантаженням, особливо коли початковий приймач або джерело сигналів журналу були досить незалежними від формату. Це дало нам впевненість, щоб запропонувати компонент всьому проєкту.

Як налаштувати процесор розгортання

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

processors:
  unroll:
service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [..., unroll, ...]
      exporters: [logging]

Загальний шаблон розгортання

Процесор розгортання виконує роботу тільки в тому випадку, якщо log.body є ітераційним списком, наприклад, правильним масивом JSON. Але в реальних конвеєрах записи журналу не завжди мають таку чітку структуру. Іноді потрібна додаткова попередня обробка, щоб перетворити необроблені дані журналу в формат, з яким може працювати процесор розгортання.

Приклад: кілька обʼєктів JSON в одному записі журналу

Розглянемо випадок, коли кілька обʼєктів JSON обʼєднані в один запис журналу, як показано нижче:

{"@timestamp":"2025-09-19T02:20:17.920Z", "log.level": "INFO", "message":"initialized", "ecs.version": "1.2.0","service.name":"ES_ECS","event.dataset":"elasticsearch.server","process.thread.name":"main","log.logger":"org.elasticsearch.node.Node","elasticsearch.node.name":"es-test-3","elasticsearch.cluster.name":"elasticsearch"},{"type": "server", "timestamp": "2025-09-18T20:44:01,838-04:00", "level": "INFO", "component": "o.e.n.Node", "cluster.name": "elasticsearch", "node.name": "es-test", "message": "initialized" }

Ось як можна виконати попередню обробку за допомогою процесора transform, а потім unroll:

receivers: ...

processors:
  transform:
    error_mode: ignore
    log_statements:
      - context: log
        statements:
          - set(body, Split(body, "\"},"))
  unroll: {}
exporters: ...

services:
  pipelines:
    logs:
      receivers: [...]
      processors: [transform, unroll]
      exporters: [...]

Ця інструкція перетворення використовує Split для розділення тіла на частини за допомогою роздільника "},", створюючи тіло у вигляді списку. that the unroll processor can expand.

Висновки

Ця функція виникла з простої потреби: зробити Collector більш універсальним і здатним розширювати записи журналів.

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

Наразі ми не пропонуємо додавати розширення записів до OTTL. Розширення змінює кардинальність потоку даних і, ймовірно, вимагає інших гарантій життєвого циклу та відповідності, тому на сьогоднішній день спеціальний процесор є оптимальним рішенням. Розділення обовʼязків дозволяє OTTL зосередитися на перетворенні наявних записів журналу, тоді як процесор розгортання обробляє розширення.

Процесор розгортання тепер доступний в офіційному OpenTelemetry Collector Contrib. Не соромтеся створювати запити та тестувати його для своїх конвеєрів журналів.

• ←Попередня
• Наступна→