Начинаем работу с мониторингом (Observability) iOS-приложений

Когда вы выпускаете своё приложение в магазин, и люди по всему миру начинают им пользоваться, вы вскоре обнаруживате, что у пользователей возникают странные ошибки, и составить полную картину того, что может быть не так, бывает непросто.

Исправить сбой, используя логи ошибок, может быть легко. Но что, если функция не работает, и у вас закончились идеи о том, что может происходить, и единственное, что приходит в голову, это: «Как бы мне хотелось отладить приложение на телефоне этого пользователя», что, конечно, редко достижимо?

В этом руководстве вы изучите основы мониторинга приложений (observability) и поймете, как ваше приложение ведет себя в руках ваших клиентов.

В процессе обучения вы:

• Создадите учетную запись Grafana Cloud
• Интегрируете Open-Telemetry Framework в ваше iOS-приложение
• Отправите телеметрическую информацию из вашего приложения и визуализируйте её в Grafana

Вы можете узнать больше о мониторинге приложений в мини-курсе «Мониторинг приложений» от Kodeco.

Начало работы

Для начала вам нужно создать бесплатную учетную запись на Grafana.com.

Вы можете использовать учетную запись Google, Github, Microsoft или Amazon, чтобы напрямую связать ее с Grafana.

После этого Grafana предложит вам создать Stack, который станет вашим собственным порталом.

При первом запуске может потребоваться несколько минут.

После открытия перейдите на главную страницу из бокового меню. Это приведет вас на страницу руководства по началу работы.

Из списка опций выберите OpenTelemetry.

Это переведет вас на страницу руководства по интеграции OpenTelemetry.

В разделе Choose your setup выберите Quickstart, затем в качестве примера выберите Java.

Введите название приложения, которое вы будете подключать к Grafana. Введите themet, затем нажмите Create token.

Это приведет вас к настройке, необходимой для подключения к Grafana. В разделе Add automatic instrumentation вам понадобятся две вещи:

• токен аутентификации из параметра OTEL_EXPORTER_OTLP_HEADERS (скрыт на скриншоте)
• URL-адрес вашего стека Grafana из параметра OTEL_EXPORTER_OTLP_ENDPOINT

"Authentication=Basic [YOUR_TOKEN]"

Сохраните эти значения, так как вы будете использовать их во всем модуле. Затем нажмите кнопку «Продолжить», чтобы завершить. Вы должны увидеть сообщение с подтверждением: You’re all set!

Интеграция OpenTelemetry Framework

Для начала откройте пример проекта в стартовой папке. Это мобильное приложение, которое позволяет искать в Метрополитен-музее по любому ключевому слову и отображает результаты на экране.

Начните с добавления пакета SPM OpenTelemetry из https://github.com/open-telemetry/opentelemetry-swift.

Xcode предложит вам выбрать цели для интеграции в ваш проект. Выберите следующие:

• OpenTelemetryApi
• OpenTelemetryProtocolExporter
• OpenTelemetryProtocolExporterHTTP
• OpenTelemetrySdk

Настройка трассировки OpenTelemetry

В навигаторе проекта создайте новую папку в файле проекта и назовите её Observability, затем создайте в этой папке новый файл Swift с именем OTelSpans.swift. Замените код в новом файле следующим:

import Foundation
import OpenTelemetryApi // 1
import OpenTelemetrySdk
import OpenTelemetryProtocolExporterCommon
import OpenTelemetryProtocolExporterHttp
import ResourceExtension

public class OTelSpans {
  private static var shared = OTelSpans() // 2

  var grafanaHttpExporter: OtlpHttpTraceExporter! // 3
  // 4
  let grafanaToken = "" // Set your Grafana token here
  let grafanaEndpoint = "" // Set your URL here
  
  private init() { // 5
  } 
}

1. Сначала импортируем добавленные в проект через SPM целевые объекты.
2. Создаем экземпляр класса OTelSpans в виде синглтона и используем этот общий экземпляр во всем проекте.
3. Объект OtlpHttpTraceExporter — это объект интеграции, который устанавливает связь между фреймворком OpenTelemetry в вашем приложении и Grafana.
4. Установите эти свойства на токен и URL, скопированные из Grafana в предыдущем разделе. Без них интеграция работать не будет.
5. Наконец, делаем пустой приватный метод инициализации. Сейчас вы его заполните.

Добавьте это в приватный инициализатор:

let grafanaEndpoint = URL(string: "\(grafanaEndpoint)/v1/traces")! // 1
let grafanaHeaders = OtlpConfiguration(headers: [("Authorization", "Basic \(grafanaToken)")],
                                       exportAsJson: true) // 2
    
grafanaHttpExporter = OtlpHttpTraceExporter(endpoint: grafanaEndpoint,
                                            config: grafanaHeaders) // 3
    
let spanProcessor = SimpleSpanProcessor(spanExporter: grafanaHttpExporter) // 4
    
OpenTelemetry.registerTracerProvider(tracerProvider:
                                     TracerProviderBuilder()
  .with(resource: DefaultResources().get())
  .add(spanProcessor: spanProcessor)
  .build()
) // 5

1. Создаем экземпляр URL-адреса с сервером Grafana.
2. Создаем конфигурацию, необходимую Grafana для аутентификации соединения с вашим стеком Grafana. Это кортеж строк, указывающий данные для отправки в формате JSON.
3. Создаем экземпляр OtlpHttpTraceExporter, используя URL-адрес и конфигурацию.
4. Создаем обработчик, который будет отвечать за отправку трассировочных данных через ваш экспортер. Пока вы будете использовать простой обработчик.
5. Наконец, вы регистрируете trace-провайдер через его билдер. Билдер может принимать ресурсы, которые будут добавляться к каждому span — это набор пар ключ-значение, включаемых во все span’ы. После этого передайте в builder процессор, который вы только что создали.

Добавьте этот метод в OTelSpans сразу после инициализатора:

internal func tracer(  // 1
  scopeName: String
) -> any Tracer {
  let instrumentationScopeVersion = "semver:0.1.0"  // 2
  
  let tracer = OpenTelemetry.instance.tracerProvider.get(  // 3
    instrumentationName: scopeName,
    instrumentationVersion: instrumentationScopeVersion)
  return tracer
}

1. Новый метод принимает строку в качестве параметра и возвращает объект, соответствующий протоколу Tracer. Чтобы получить экземпляр трассировщика, необходимо указать имя инструментария, которое передается в качестве параметра методу, и версию, которую вы устанавливаете в качестве константы. «semver» — это сокращение от Semantic Version (семантическая версия).
2. В конце концов, вы получаете объект трассировщика из OpenTelemetry и возвращаете его.

Теперь, чтобы добавить метод для создания span, добавьте следующее после последнего метода в конце класса:

public func createSpan(  // 1
  scopeName: String,
  name: String
) -> (any Span) {
  var spanBuilder = tracer(scopeName: scopeName)  // 2
    .spanBuilder(spanName: name)
  
  let span = spanBuilder.startSpan()  // 3
  
  return span
}

1. Метод принимает два строковых параметра: первый — имя scope, которое вы будете использовать для получения tracer, второй — имя span.
2. Используя метод tracer(scopeName: String), который вы создали ранее, вы получаете tracer, а через него — span builder, задавая имя для любого span, созданного этим builder.
3. Через builder получите span, который уже запущен. Запуск span эквивалентен установке времени начала в Date.now.

Поскольку OTelSpans хранит общее свойство и инициализатор как private, использование этой функциональности можно упростить, добавив метод класса, который будет проксировать вызов к внутреннему экземпляру. Добавьте следующий метод:

public class func createSpan(
  scopeName: String,
  name: String
) -> (any Span) {
  shared.createSpan(
    scopeName: scopeName,
    name: name)
}

Отправка span-объектов из вашего приложения

К настоящему моменту вы добавили весь вспомогательный код для создания span-объектов с помощью Open-Telemetry. Создавая span-объекты в разных частях вашего приложения, вы можете измерить время выполнения вашего кода. Хороший пример — измерение времени ожидания пользователями результатов поиска.

Перейдите в файл TheMetStore.swift и добавьте эту строку в самом начале функции fetchObjects(for:):

let span = OTelSpans.createSpan(scopeName: "TheMet-Tracing", name: "fetchObjects")

И добавьте это прямо перед концом метода:

span.end()

Запустите приложение и выполните поиск по нескольким ключевым словам, затем откройте портал Grafana.

Просмотр ваших span в Grafana

В меню выберите Traces в разделе Detaildown. Выберите Traces на вкладках в середине страницы.

Выбрав вкладку, вы увидите все отправленные вами отдельные трассировочные фрагменты: время начала, название и продолжительность.

Вы можете выбрать любой span по названию трассировки для получения более подробной информации.

Источник