Skip to content

MonotoringTA/opentelemetryOneScript

 
 

Repository files navigation

OpenTelemetry SDK для OneScript

Ask DeepWiki

Библиотека на OneScript для использования OpenTelemetry в оскриптовых проектах.

Позволяет собирать и отправлять телеметрию (трассировку, логи, метрики) в формате OTLP в любой совместимый коллектор — Grafana LGTM, OpenTelemetry Collector и другие. Поддерживает два транспорта: HTTP JSON и gRPC.

Возможности

  • Трассировка — создание спанов, вложенных спанов, установка атрибутов, событий, линков и статусов
  • Контекст — thread-safe implicit context propagation для автоматического наследования родительских спанов
  • Логирование — запись логов с уровнями серьезности и корреляцией с трассировкой
  • Интеграция с logos — аппендер для библиотеки logos, перенаправляющий логи в OpenTelemetry
  • Метрики — счетчики, реверсивные счетчики, датчики и гистограммы для измерения показателей
  • W3C Trace Context — внедрение и извлечение traceparent/tracestate HTTP-заголовков
  • Экспорт по OTLP/HTTP — отправка данных в формате JSON на стандартные эндпоинты /v1/traces, /v1/logs, /v1/metrics
  • Экспорт по OTLP/gRPC — отправка данных через gRPC с помощью библиотеки oint (OPI_GRPC)

Установка

opm install opentelemetry

Быстрый старт

Трассировка

#Использовать opentelemetry

// Создание ресурса
Ресурс = Новый ОтелРесурс();
Ресурс.Атрибуты().Установить("service.name", "my-service");

// Создание транспорта и экспортера
Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Экспортер = Новый ОтелЭкспортерСпанов(Транспорт);
Процессор = Новый ОтелПростойПроцессорСпанов(Экспортер);

// Создание провайдера и трассировщика
Провайдер = Новый ОтелПровайдерТрассировки(Ресурс, Процессор);
Трассировщик = Провайдер.ПолучитьТрассировщик("my-library", "1.0.0");

// Создание спана (SpanKind задаётся при создании — immutable)
Спан = Трассировщик.НачатьСпан("обработка-запроса", ОтелВидСпана.Сервер());
Спан.СделатьТекущим(); // спан становится текущим в контексте
Спан.УстановитьАтрибут("http.method", "GET");
Спан.УстановитьАтрибут("http.url", "/api/data");

// Дочерний спан — НачатьСпан автоматически берёт родителя из контекста
ДочернийСпан = Трассировщик.НачатьСпан("запрос-к-бд", ОтелВидСпана.Клиент());
// ... выполнение работы ...
ДочернийСпан.УстановитьСтатус(ОтелКодСтатуса.Ок());
ДочернийСпан.Завершить();

Спан.УстановитьСтатус(ОтелКодСтатуса.Ок());
Спан.Завершить(); // автоматически восстанавливает предыдущий контекст

Провайдер.Закрыть();

Логирование

#Использовать opentelemetry

Ресурс = Новый ОтелРесурс();
Ресурс.Атрибуты().Установить("service.name", "my-service");

Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Экспортер = Новый ОтелЭкспортерЛогов(Транспорт);
Процессор = Новый ОтелПростойПроцессорЛогов(Экспортер);

Провайдер = Новый ОтелПровайдерЛогирования(Ресурс, Процессор);
Запись = Логгер.СоздатьЗаписьЛога();
Запись.УстановитьТело("Пользователь авторизован")
    .УстановитьСерьезность(ОтелСтепеньСерьезности.Info())
    .УстановитьАтрибут("user.id", "12345");

Логгер.Записать(Запись);

Метрики

#Использовать opentelemetry

Ресурс = Новый ОтелРесурс();
Ресурс.Атрибуты().Установить("service.name", "my-service");

Провайдер = Новый ОтелПровайдерМетрик(Ресурс);
Метрика = Провайдер.ПолучитьМетр("my-library", "1.0.0");

// Счетчик
Счетчик = Метрика.СоздатьСчетчик("http.requests", "Количество запросов", "1");
Счетчик.Добавить(1);

// Гистограмма
Гистограмма = Метрика.СоздатьГистограмму("http.duration", "Время ответа", "ms");
Гистограмма.Записать(150);

// Реверсивный счетчик (UpDownCounter)
ОчередьСчетчик = Метрика.СоздатьРеверсивныйСчетчик("queue.size", "Размер очереди", "1");
ОчередьСчетчик.Добавить(1);  // добавлен элемент
ОчередьСчетчик.Добавить(-1); // элемент обработан

// Датчик (Gauge)
Датчик = Метрика.СоздатьДатчик("cpu.usage", "Загрузка CPU", "%");
Датчик.Записать(75.5);

W3C Trace Context

#Использовать opentelemetry

// Внедрение контекста в исходящий HTTP-запрос
Спан = Трассировщик.НачатьСпан("http-запрос", ОтелВидСпана.Клиент());
Заголовки = Новый Соответствие();
ОтелW3CПропагатор.Внедрить(Спан.Контекст(), Заголовки);
// Заголовки теперь содержат "traceparent" и опционально "tracestate"

// Извлечение контекста из входящего запроса
КонтекстСпана = ОтелW3CПропагатор.Извлечь(ВходящиеЗаголовки);
Если КонтекстСпана <> Неопределено Тогда
    Спан = Трассировщик.НачатьДочернийСпан("обработка", КонтекстСпана, ОтелВидСпана.Сервер());
КонецЕсли;

Использование gRPC-транспорта

Все существующие экспортеры (спаны, логи, метрики) работают с обоими транспортами. Достаточно заменить ОтелHttpТранспорт на ОтелGrpcТранспорт:

#Использовать opentelemetry

// gRPC-транспорт — порт 4317 (стандартный OTLP gRPC)
Транспорт = Новый ОтелGrpcТранспорт("http://localhost:4317");

// Все экспортеры принимают любой транспорт
Экспортер = Новый ОтелЭкспортерСпанов(Транспорт);
Процессор = Новый ОтелПростойПроцессорСпанов(Экспортер);

Ресурс = Новый ОтелРесурс();
Ресурс.Атрибуты().Установить("service.name", "my-service");
Провайдер = Новый ОтелПровайдерТрассировки(Ресурс, Процессор);
Трассировщик = Провайдер.ПолучитьТрассировщик("my-library", "1.0.0");

Спан = Трассировщик.НачатьСпан("операция", ОтелВидСпана.Сервер());
// ... работа ...
Спан.Завершить();

// Важно: закрывает gRPC-соединение
Транспорт.Закрыть();

Интеграция с logos

#Использовать opentelemetry
#Использовать logos

Ресурс = Новый ОтелРесурс();
Ресурс.Атрибуты().Установить("service.name", "my-service");

Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Экспортер = Новый ОтелЭкспортерЛогов(Транспорт);
Процессор = Новый ОтелПростойПроцессорЛогов(Экспортер);

Провайдер = Новый ОтелПровайдерЛогирования(Ресурс, Процессор);
ОтелЛоггер = Провайдер.ПолучитьЛоггер("my-library", "1.0.0");

// Создание аппендера и подключение к logos
Аппендер = Новый ОтелАппендерLogos(ОтелЛоггер);

Лог = Логирование.ПолучитьЛог("oscript.app.myapp");
Лог.ДобавитьСпособВывода(Аппендер);

// Теперь все сообщения logos автоматически отправляются в OpenTelemetry
Лог.Информация("Приложение запущено");
Лог.Ошибка("Произошла ошибка: файл не найден");

Архитектура

SDK следует архитектуре OpenTelemetry SDK Specification и моделируется по образцу Java SDK.

Основные компоненты

Компонент Класс Описание
Ресурс ОтелРесурс Описание сущности, производящей телеметрию
Атрибуты ОтелАтрибуты Пары ключ-значение для описания телеметрии
Контекст спана ОтелКонтекстСпана Идентификаторы трассировки и спана

Трассировка

Компонент Класс Описание
Провайдер ОтелПровайдерТрассировки Точка входа, создает трассировщики
Трассировщик ОтелТрассировщик Создает спаны
Спан ОтелСпан Единица работы с атрибутами и событиями
Процессор ОтелПростойПроцессорСпанов Обрабатывает завершенные спаны

Логирование

Компонент Класс Описание
Провайдер ОтелПровайдерЛогирования Точка входа, создает логгеры
Логгер ОтелЛоггер Создает и отправляет записи логов
Запись лога ОтелЗаписьЛога Запись лога с серьезностью и атрибутами
Процессор ОтелПростойПроцессорЛогов Синхронно передает записи экспортеру

Метрики

Компонент Класс Описание
Провайдер ОтелПровайдерМетрик Точка входа, создает метрики
Метрика ОтелМетр Создает инструменты измерения
Счетчик ОтелСчетчик Монотонно возрастающий счетчик
Реверсивный счетчик ОтелРеверсивныйСчетчик Счетчик, допускающий отрицательные значения
Датчик ОтелДатчик Хранит последнее значение (Gauge)
Гистограмма ОтелГистограмма Агрегация значений для статистики

Экспортеры

Компонент Класс Описание
HTTP-транспорт ОтелHttpТранспорт OTLP HTTP JSON (порт 4318)
gRPC-транспорт ОтелGrpcТранспорт OTLP gRPC через oint/OPI_GRPC (порт 4317)
InMemory-транспорт ОтелВПамятьТранспорт Сохраняет данные в память (для тестирования)
Конвертер ОтелКонвертерOtlpВProto Конвертация camelCase→snake_case для protobuf
Спаны ОтелЭкспортерСпанов Экспорт спанов на /v1/traces
Логи ОтелЭкспортерЛогов Экспорт логов на /v1/logs
Метрики ОтелЭкспортерМетрик Экспорт метрик на /v1/metrics

Интеграция

Компонент Класс Описание
Аппендер logos ОтелАппендерLogos Аппендер для библиотеки logos, отправляет логи через OTel

Модули констант

Модуль Описание
ОтелВидСпана Виды спанов: Внутренний, Сервер, Клиент, Производитель, Потребитель
ОтелКодСтатуса Коды статуса: НеУстановлен, Ок, Ошибка
ОтелСтепеньСерьезности Уровни серьезности: Trace, Debug, Info, Warn, Error, Fatal
ОтелУтилиты Генерация ID, работа с временными метками, форматирование
ОтелКонтекст Thread-safe хранение текущего спана (per-thread stack)
ОтелW3CПропагатор Внедрение и извлечение W3C TraceContext заголовков

Требования

  • OneScript 2.0.0+
  • logos 1.7.1+ (устанавливается автоматически через зависимости)
  • 1connector 2.2.1+ (устанавливается автоматически через зависимости)
  • collectionos 0.8.2+ (устанавливается автоматически через зависимости)
  • oint (устанавливается автоматически, требуется для gRPC-транспорта)

Разработка

Установка зависимостей

opm install -l --dev

Запуск тестов

oneunit execute

Лицензия

MIT

About

OpenTelemetry SDK для OneScript

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • 1C Enterprise 100.0%