# API та SDK для логів OpenTelemetry Go досягли статусу реліз-кандидата

LLMS index: [llms.txt](/llms.txt)

---

OpenTelemetry Go `v1.47.0-rc.1` вже доступний. Цей реліз переводить API та SDK для логів у статус реліз-кандидата (Release Candidate, RC) — останній етап перед наданням стабільних гарантій сумісності v1. Ми вважаємо, що дизайн готовий, і тепер нам потрібен відгук спільноти щодо тестування його в реальних застосунках та інтеграціях перед набуттям цими гарантіями чинності.

## Що включено в реліз-кандидат? {#what-is-included-in-the-release-candidate}

RC охоплює два модулі:

- `go.opentelemetry.io/otel/log`
- `go.opentelemetry.io/otel/sdk/log`

Ці модулі переходять з `v0.22.0` (стабільність beta) до `v1.47.0-rc.1`. Версія узгоджена з іншими стабільними модулями OpenTelemetry Go, які мають спільний номер версії. Експортери логів та модуль `logtest` залишаються експериментальними і не охоплюються стабільністю цього RC.

Реліз також додає `Logger`, `GetLoggerProvider` та `SetLoggerProvider` до кореневого пакунка `go.opentelemetry.io/otel`. Відповідні API в `go.opentelemetry.io/otel/log/global` тепер позначені як застарілі. Це узгоджує глобальний доступ до логерів із патернами, які вже використовуються для трасувань та метрик.

Повні нотатки про реліз дивіться у [випуску реліз-кандидата][rc-release].

## Шлях до реліз-кандидата {#the-journey-to-release-candidate}

Робота над поточним дизайном розпочалася наприкінці 2023 року з [API Logs та прототипу мосту][api-prototype]. Прототип містив тести продуктивності та ранні версії мостів, що дозволило нам перевірити як структуру, так і витрати на API, перш ніж остаточно затвердити його.

[Перша альфа-версія Logs API][api-alpha] з'явилася у лютому 2024 року, а [перша альфа-версія Logs SDK][sdk-alpha] — у квітні. У травні 2024 року ми опублікували [першу спільну бета-версію API та SDK][beta-release]. Відтоді ми продовжували слідувати еволюції специфікації OpenTelemetry Logs, розширили API від його початкового випадку використання, орієнтованого на мости, до прямого використання, а також удосконалили представлення записів, обробку, обмеження, поведінку життєвого циклу та продуктивність. Останні зміни включали впровадження спільних типів [`attribute.Value` та `attribute.KeyValue`][shared-attributes] для всіх сигналів та [переробку `BatchProcessor`][batch-redesign] для безпечнішої поведінки експортера під тиском.

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

## Що лягло в основу дизайну? {#what-guided-the-design}

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

- **Відповідність специфікації:** Публічні абстракції та поведінка спроєктовані для реалізації специфікацій OpenTelemetry Logs API та SDK, включаючи конкурентність, кореляцію контексту, обмеження записів та вимоги до життєвого циклу процесорів й експортерів.
- **Надійність:** `BatchProcessor` використовує обмежену чергу та не змушує логування чекати на ввід-вивід експортера. SDK також визначає чітку семантику скидання (flush) та завершення роботи (shutdown).
- **Продуктивність:** Записи та операції на гарячих шляхах спроєктовані для зменшення виділень памʼяті у купі та тиску на збирач сміття. SDK оптимізовано для типової конфігурації експортера OTLP із пакетним процесором.
- **Знайомість:** Провайдери, області інструментування, опції, процесори, експортери та глобальний доступ слідують патернам, закладеним API трасувань та метрик, тому Logs API має відчуватися як частина того самого Go SDK, а не окремий фреймворк логування.

Рішення та компроміси задокументовані в [документі з дизайну Logs API][api-design] та [документі з дизайну Logs SDK][sdk-design]. Ці документи також фіксують розглянуті альтернативи та пояснюють такий вибір, як представлення записів, обробка атрибутів, розширюваність та модель пакетування.

## Спробуйте RC {#try-the-rc}

Оновіть такі модулі до реліз-кандидата:

```sh
go get go.opentelemetry.io/otel@v1.47.0-rc.1
go get go.opentelemetry.io/otel/log@v1.47.0-rc.1
go get go.opentelemetry.io/otel/sdk/log@v1.47.0-rc.1
```

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

## Повідомляйте про проблеми вже зараз {#please-report-problems-now}

Якщо ви зіткнетеся з будь-якими проблемами, будь ласка, [створіть нову проблему][new-issue] у репозиторії OpenTelemetry Go. Вкажіть версію RC, вашу версію Go, за можливості мінімальний відтворюваний приклад та те, що ви очікували.

**Період відгуку:** Ми чекатимемо щонайменше 14 днів після публікації цього допису, перш ніж стабілізувати Logs API та SDK. Якщо значні знахідки вимагатимуть ще одного RC, ми перезапустимо 14-денний період відгуку після публікації цього RC. Це дає спільноті час перевірити будь-які суттєві зміни до стабілізації.

Це вікно відгуку важливе. Після стабілізації Logs API та SDK наша [політика версіонування][versioning] зобовʼязує нас до сумісності протягом усієї лінії v1. Поза задокументованими винятками ми більше не зможемо виправляти проблеми шляхом розривних змін API в межах v1; несумісне виправлення довелося б чекати на нову основну версію. Якщо форма API, поведінка, точка розширення чи характеристика продуктивності не працюють для вашого випадку, настав час повідомити нам.

Після оцінки відгуку ми внесемо необхідні оновлення RC, а потім переведемо Logs API та SDK у стабільний стан. Дякуємо всім, хто долучився дизайнами, впровадженнями, рецензіями, бенчмарками, інтеграціями та відгуком на цьому шляху.

[api-design]: https://github.com/open-telemetry/opentelemetry-go/blob/73b17d449376ccd8420f84fc8d5d4435ad44e0d6/log/DESIGN.md
[api-alpha]: https://github.com/open-telemetry/opentelemetry-go/releases/tag/v1.24.0
[api-prototype]: https://github.com/open-telemetry/opentelemetry-go/pull/4725
[batch-redesign]: https://github.com/open-telemetry/opentelemetry-go/pull/8620
[beta-release]: https://github.com/open-telemetry/opentelemetry-go/releases/tag/v1.27.0
[new-issue]: https://github.com/open-telemetry/opentelemetry-go/issues/new/choose
[rc-release]: https://github.com/open-telemetry/opentelemetry-go/releases/tag/v1.47.0-rc.1
[sdk-design]: https://github.com/open-telemetry/opentelemetry-go/blob/73b17d449376ccd8420f84fc8d5d4435ad44e0d6/sdk/log/DESIGN.md
[sdk-alpha]: https://github.com/open-telemetry/opentelemetry-go/pull/5260
[shared-attributes]: https://github.com/open-telemetry/opentelemetry-go/pull/8490
[versioning]: https://github.com/open-telemetry/opentelemetry-go/blob/73b17d449376ccd8420f84fc8d5d4435ad44e0d6/VERSIONING.md