Бібліотеки інструментів

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

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

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

Використання вбудованих бібліотек

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

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

Використання бібліотек інструментів

OpenTelemetry-Swift надає кілька бібліотек інструментів, які генерують інструменти для вас, коли вони встановлені та ініціалізовані.

Наприклад, інструментування NSURLSession автоматично створює відрізки для всіх мережевих запитів, зроблених за допомогою NSURLSessions.

Налаштування

Усі бібліотеки інструментів доступні в OpenTelemetry Swift. Щоб увімкнути інструментування, дотримуйтесь інструкцій з використання.

SDKResourceExtension

SDKResourceExtension надає деталі про пристрій як ресурс.

Використання

Використовуйте DefaultResource.get(), щоб створити обʼєкт ресурсу “все в одному”. Цей ресурс можна додати до TracerProvider або MetricProvider.

OpenTelemetry.registerTracerProvider(tracerProvider: TracerProviderBuilder()
            .with(resource: DefaultResource.get())
            .build())

Деталі

SDKResourceExtension надає атрибути в обʼєкті ресурсу з деталями про пристрій iOS, деталі ОС та деталі застосунку. Він застосовує ці значення до відповідних семантичних атрибутів.

Інформація про застосунок

Інформація про пристрій

Інформація про операційну систему

Інструментування NSURLSession

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

Примітка: Інструментування NSURLSession покладається на глобального постачальника трасувань у обʼєкті OpenTelemetry. Власні постачальники трасувань повинні бути налаштовані та встановлені як глобальні постачальники перед цим інструментуванням.

Використання

Ініціалізуйте клас за допомогою URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration()), щоб автоматично захоплювати всі мережеві виклики.

Цю поведінку можна змінити або доповнити, використовуючи необовʼязкові зворотні виклики, визначені в URLSessionInstrumentationConfiguration:

• shouldInstrument: ((URLRequest) -> (Bool)?)?

  Фільтруйте, які запити ви хочете інструментувати, стандартно всі.

• shouldRecordPayload: ((URLSession) -> (Bool)?)?

  Реалізуйте, якщо хочете, щоб сесія записувала дані корисного навантаження, стандартно false.

• shouldInjectTracingHeaders: ((URLRequest) -> (Bool)?)?

  Дозволяє фільтрувати, до яких запитів ви хочете вставляти заголовки для відстеження, стандартно true. Ви також повинні повернути true, якщо хочете вставити власні заголовки.

• injectCustomHeaders: ((inout URLRequest, Span?) -> Void)?

  Реалізуйте цей зворотний виклик, щоб вставити власні заголовки або змінити запит іншим чином.

• nameSpan: ((URLRequest) -> (String)?)?

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

• createdRequest: ((URLRequest, Span) -> Void)?

  Викликається після створення запиту, дозволяє додати додаткову інформацію до відрізка.

• receivedResponse: ((URLResponse, DataOrFile?, Span) -> Void)?

  Викликається після отримання відповіді, дозволяє додати додаткову інформацію до відрізка.

• receivedError: ((Error, DataOrFile?, HTTPStatus, Span) -> Void)?

  Викликається після отримання помилки, дозволяє додати додаткову інформацію до відрізка.

Нижче наведено приклад ініціалізації. Конструкція URLSessionInstrumentationConfiguration може бути передана параметрами, визначеними вище, щоб відповідати потребам застосунку.

let sessionInstrumentation = URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration())

Деталі

Інструментування NSURLSession також надає додаткові атрибути, що надають деталі про стан мережі пристрою на момент мережевих запитів.

SignpostIntegration

Цей пакет створює виклики os_signpost begin та end, коли відрізки починаються або закінчуються. Це дозволяє автоматичну інтеграцію додатків, інструментованих за допомогою OpenTelemetry, щоб показувати їх відрізки в профілюючому застосунку, як Instruments. Він також експортує OSLog, який використовується для публікації, щоб користувач міг додати додаткові події signpost. Ця функціональність показана в прикладі Simple Exporter.

Повідомлення про версію

• iOS 15+, macOS 12+, tvOS 15+, watchOS 8+: використовуйте OSSignposterIntegration, який використовує сучасний API OSSignposter для підвищення ефективності та сумісності.
• Старі системи: використовуйте SignPostIntegration, який базується на традиційному API os_signpost.

Використання

Add the appropriate span processor based on your deployment target (see the manual instrumentation) docs for details on configuring your providers:

Для iOS 15+, macOS 12+, tvOS 15+, watchOS 8+:

OpenTelemetry.instance.tracerProvider.addSpanProcessor(OSSignposterIntegration())

Для старих систем

OpenTelemetry.instance.tracerProvider.addSpanProcessor(SignPostIntegration())

Або вибрати автоматично під час виконання:

if #available(iOS 15, macOS 12, tvOS 15, watchOS 8, *) {
    OpenTelemetry.instance.tracerProvider.addSpanProcessor(OSSignposterIntegration())
} else {
    OpenTelemetry.instance.tracerProvider.addSpanProcessor(SignPostIntegration())
}

Доступні бібліотеки інструментів

Повний список бібліотек інструментів, створених OpenTelemetry, доступний у репозиторії opentelemetry-swift.

Ви також можете знайти більше інструментів в реєстрі.

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

Після налаштування бібліотек інструментів, ви можете додати свої власні інструменти до вашого коду, щоб збирати власні дані телеметрії.