OpenTelemetry SDK для OneScript

Библиотека на OneScript для использования OpenTelemetry в оскриптовых проектах. Реализует спецификацию OpenTelemetry v1.55.0.

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

Возможности

Подсистема	Описание
Автоконфигурация	Настройка SDK из переменных окружения или файла конфигурации (через configor)
Трассировка	Спаны, вложенные спаны, атрибуты, события, линки, статусы, семплирование
Логирование	Записи логов с уровнями серьёзности и корреляцией с трассировкой
Метрики	Счётчики, реверсивные счётчики, датчики, гистограммы, экспоненциальные гистограммы, наблюдаемые инструменты
Пропагация	W3C Trace Context, W3C Baggage, B3 (отдельный пакет), композитный пропагатор
Экспорт	OTLP/HTTP (JSON и Protobuf), OTLP/gRPC, InMemory (для тестов), TLS
Интеграция с logos	Аппендер для logos, перенаправляющий логи в OpenTelemetry
Пакетная обработка	Batch-процессоры для спанов и логов с фоновым экспортом

Установка

bash

opm install opentelemetry

Все зависимости (logos, 1connector, collectionos, configor, async) устанавливаются автоматически.

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

Самый простой способ настроить OpenTelemetry — через автоконфигурацию. Достаточно задать переменные окружения и вызвать ОтелАвтоконфигурация.Инициализировать().

Переменные окруженияКод приложенияФайл конфигурации (configor)

bash

export OTEL_SERVICE_NAME=my-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

bsl

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

// Автоконфигурация из переменных окружения
Сдк = ОтелАвтоконфигурация.Инициализировать();

// Получение трассировщика и метра через SDK
Трассировщик = Сдк.ПолучитьТрассировщик("my-library");
Метр = Сдк.ПолучитьМетр("my-library");

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

// Или через глобальный доступ из любого места кода
Трассировщик = ОтелГлобальный.ПолучитьТрассировщик("другая-библиотека");

json

{
    "otel": {
        "service": { "name": "my-service" },
        "exporter": {
            "otlp": {
                "endpoint": "http://localhost:4318",
                "protocol": "http/protobuf"
            }
        }
    }
}

Требования

Зависимость	Минимальная версия
OneScript	2.0.0+
logos	1.7.1+
1connector	2.2.1+
collectionos	0.8.2+
configor	0.11.1+
async	0.3.0+
oint	1.33.0+ (только для gRPC-транспорта)

Дальнейшее изучение

Автоконфигурация — настройка через переменные окружения и файл конфигурации
Трассировка — спаны, атрибуты, события, семплирование
Логирование — записи логов, интеграция с logos
Метрики — инструменты измерения, периодический экспорт
Пропагация — W3C Trace Context, Baggage, B3
Экспорт — транспорты HTTP, gRPC, InMemory, TLS

Автоконфигурация

Модуль ОтелАвтоконфигурация — рекомендуемый способ инициализации SDK. Он следует спецификации переменных окружения OpenTelemetry и автоматически создаёт все необходимые провайдеры (трассировки, логирования, метрик), настраивает экспортеры, процессоры и пропагаторы.

Как работает автоконфигурация

Читает параметры из переменных окружения (OTEL_*) и/или файла конфигурации через configor.
Создаёт транспорт (HTTP или gRPC) согласно OTEL_EXPORTER_OTLP_PROTOCOL.
Строит провайдеры трассировки, логирования и метрик с batch-процессорами.
Регистрирует SDK глобально через ОтелГлобальный.
Возвращает готовый объект ОтелSdk.

Инициализация

bsl

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

Сдк = ОтелАвтоконфигурация.Инициализировать();

// Получение трассировщика
Трассировщик = Сдк.ПолучитьТрассировщик("my-library");

// Получение метра
Метр = Сдк.ПолучитьМетр("my-library");

// Глобальный доступ из любого места кода
Трассировщик2 = ОтелГлобальный.ПолучитьТрассировщик("other-library");

Настройка через переменные окружения

Переменные окружения читаются автоматически. Имена переменных соответствуют стандарту OpenTelemetry: OTEL_FOO_BAR → ключ configor otel.foo.bar.

Минимальная конфигурацияHTTP/JSON транспортgRPC транспортОтключение SDK

bash

export OTEL_SERVICE_NAME=my-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

bash

export OTEL_SERVICE_NAME=my-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,team=backend

bash

export OTEL_SERVICE_NAME=my-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

bash

export OTEL_SDK_DISABLED=true

Настройка через файл конфигурации (configor)

Путь к файлу задаётся переменной OTEL_CONFIG_FILE или программно. Поддерживаются форматы JSON и YAML.

JSON конфигурацияYAML конфигурацияУказание пути к файлу

json

{
    "otel": {
        "service": {
            "name": "my-service"
        },
        "exporter": {
            "otlp": {
                "endpoint": "http://otel-collector:4318",
                "protocol": "http/protobuf",
                "headers": "Authorization=Bearer token123",
                "compression": "gzip",
                "timeout": "10000"
            }
        },
        "traces": {
            "sampler": "parentbased_traceidratio",
            "sampler": {
                "arg": "0.1"
            }
        },
        "propagators": "tracecontext,baggage"
    }
}

yaml

otel:
  service:
    name: my-service
  exporter:
    otlp:
      endpoint: http://otel-collector:4318
      protocol: http/protobuf
      compression: gzip
  traces:
    sampler: parentbased_always_on
  propagators: tracecontext,baggage

bash

export OTEL_CONFIG_FILE=/etc/myapp/otel-config.json

Полная таблица переменных окружения

Общие параметры SDK

Переменная	Ключ configor	По умолчанию	Описание
`OTEL_SDK_DISABLED`	`otel.sdk.disabled`	`false`	Отключить SDK. При `true` создаётся NoOp SDK
`OTEL_SERVICE_NAME`	`otel.service.name`	—	Имя сервиса (`service.name` в ресурсе)
`OTEL_RESOURCE_ATTRIBUTES`	`otel.resource.attributes`	—	Дополнительные атрибуты ресурса, формат: `key1=value1,key2=value2`
`OTEL_SDK_SHUTDOWN_TIMEOUT`	`otel.sdk.shutdown.timeout`	`30000`	Таймаут завершения SDK в миллисекундах
`OTEL_CONFIG_FILE`	`otel.config.file`	—	Путь к файлу конфигурации configor (YAML/JSON)

Экспортеры

Переменная	Ключ configor	По умолчанию	Описание
`OTEL_TRACES_EXPORTER`	`otel.traces.exporter`	`otlp`	Экспортер трассировки: `otlp`, `none`
`OTEL_LOGS_EXPORTER`	`otel.logs.exporter`	`otlp`	Экспортер логов: `otlp`, `none`
`OTEL_METRICS_EXPORTER`	`otel.metrics.exporter`	`otlp`	Экспортер метрик: `otlp`, `none`

OTLP — общие параметры

Применяются ко всем сигналам, если не заданы per-signal переопределения.

Переменная	Ключ configor	По умолчанию	Описание
`OTEL_EXPORTER_OTLP_ENDPOINT`	`otel.exporter.otlp.endpoint`	`http://localhost:4318` (HTTP) / `http://localhost:4317` (gRPC)	Адрес OTLP-коллектора
`OTEL_EXPORTER_OTLP_PROTOCOL`	`otel.exporter.otlp.protocol`	`http/protobuf`	Протокол: `http/json`, `http/protobuf`, `grpc`
`OTEL_EXPORTER_OTLP_HEADERS`	`otel.exporter.otlp.headers`	—	Заголовки HTTP/gRPC, формат: `key1=value1,key2=value2`
`OTEL_EXPORTER_OTLP_COMPRESSION`	`otel.exporter.otlp.compression`	`none`	Сжатие: `gzip`, `none`
`OTEL_EXPORTER_OTLP_TIMEOUT`	`otel.exporter.otlp.timeout`	`10000`	Таймаут запроса в миллисекундах
`OTEL_EXPORTER_OTLP_CERTIFICATE`	`otel.exporter.otlp.certificate`	—	Путь к CA-сертификату (PEM)
`OTEL_EXPORTER_OTLP_CLIENT_KEY`	`otel.exporter.otlp.client.key`	—	Путь к клиентскому приватному ключу (PEM)
`OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`	`otel.exporter.otlp.client.certificate`	—	Путь к клиентскому сертификату (PEM)
`OTEL_EXPORTER_OTLP_INSECURE`	`otel.exporter.otlp.insecure`	`false`	Отключить проверку TLS-сертификата

OTLP — трассировка (per-signal)

Переопределяют общие OTEL_EXPORTER_OTLP_* для сигнала трассировки.

Переменная	Описание
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	Адрес коллектора
`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`	Протокол
`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	Заголовки
`OTEL_EXPORTER_OTLP_TRACES_COMPRESSION`	Сжатие
`OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`	Таймаут (мс)
`OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE`	CA-сертификат (PEM)
`OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY`	Клиентский ключ (PEM)
`OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE`	Клиентский сертификат (PEM)

OTLP — логирование (per-signal)

Переменная	Описание
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	Адрес коллектора
`OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`	Протокол
`OTEL_EXPORTER_OTLP_LOGS_HEADERS`	Заголовки
`OTEL_EXPORTER_OTLP_LOGS_COMPRESSION`	Сжатие
`OTEL_EXPORTER_OTLP_LOGS_TIMEOUT`	Таймаут (мс)
`OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE`	CA-сертификат (PEM)
`OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY`	Клиентский ключ (PEM)
`OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE`	Клиентский сертификат (PEM)

OTLP — метрики (per-signal)

Переменная	По умолчанию	Описание
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	—	Адрес коллектора
`OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`	—	Протокол
`OTEL_EXPORTER_OTLP_METRICS_HEADERS`	—	Заголовки
`OTEL_EXPORTER_OTLP_METRICS_COMPRESSION`	—	Сжатие
`OTEL_EXPORTER_OTLP_METRICS_TIMEOUT`	—	Таймаут (мс)
`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`	`cumulative`	Временная агрегация: `cumulative`, `delta`, `lowmemory`
`OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION`	`explicit_bucket_histogram`	Агрегация гистограммы: `explicit_bucket_histogram`, `base2_exponential_bucket_histogram`
`OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE`	—	CA-сертификат (PEM)
`OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY`	—	Клиентский ключ (PEM)
`OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE`	—	Клиентский сертификат (PEM)

Семплирование трассировки

Переменная	Ключ configor	По умолчанию	Описание
`OTEL_TRACES_SAMPLER`	`otel.traces.sampler`	`parentbased_always_on`	Стратегия сэмплирования
`OTEL_TRACES_SAMPLER_ARG`	`otel.traces.sampler.arg`	`1.0`	Аргумент сэмплера (доля для `traceidratio`)

Поддерживаемые значения OTEL_TRACES_SAMPLER:

Значение	Описание
`always_on`	Сэмплировать все спаны
`always_off`	Не сэмплировать ничего
`traceidratio`	Случайная доля (задаётся через `OTEL_TRACES_SAMPLER_ARG`)
`parentbased_always_on`	ParentBased(root=AlwaysOn)
`parentbased_always_off`	ParentBased(root=AlwaysOff)
`parentbased_traceidratio`	ParentBased(root=TraceIdRatio)

Пакетный процессор спанов (BatchSpanProcessor)

Переменная	Ключ configor	По умолчанию	Описание
`OTEL_BSP_MAX_QUEUE_SIZE`	`otel.bsp.max.queue.size`	`2048`	Максимальный размер очереди
`OTEL_BSP_SCHEDULE_DELAY`	`otel.bsp.schedule.delay`	`5000`	Интервал запуска экспорта (мс)
`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`	`otel.bsp.max.export.batch.size`	`512`	Максимальный размер пакета
`OTEL_BSP_EXPORT_TIMEOUT`	`otel.bsp.export.timeout`	`30000`	Таймаут экспорта (мс)

Пакетный процессор логов использует те же параметры, но со значением по умолчанию OTEL_BSP_SCHEDULE_DELAY = 1000 мс.

Периодический экспорт метрик

Переменная	Ключ configor	По умолчанию	Описание
`OTEL_METRIC_EXPORT_INTERVAL`	`otel.metric.export.interval`	`60000`	Интервал экспорта метрик (мс)
`OTEL_METRICS_EXEMPLAR_FILTER`	`otel.metrics.exemplar.filter`	`trace_based`	Фильтр exemplars: `always_on`, `always_off`, `trace_based`

Пропагаторы контекста

Переменная	Ключ configor	По умолчанию	Описание
`OTEL_PROPAGATORS`	`otel.propagators`	`tracecontext,baggage`	Пропагаторы через запятую

Поддерживаемые значения:

Значение	Описание
`tracecontext`	W3C Trace Context
`baggage`	W3C Baggage
`b3`	B3 Single Header (требуется пакет `opentelemetry-propagator-b3`)
`b3multi`	B3 Multi Header (требуется тот же пакет)
`none`	Отключить все пропагаторы

Ограничения атрибутов

Переменная	По умолчанию	Описание
`OTEL_ATTRIBUTE_COUNT_LIMIT`	`128`	Максимальное число атрибутов (все сигналы)
`OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`	без ограничения	Максимальная длина строкового атрибута
`OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT`	наследует `OTEL_ATTRIBUTE_COUNT_LIMIT`	Переопределение для спанов
`OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`	наследует `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`	Переопределение для спанов
`OTEL_SPAN_EVENT_COUNT_LIMIT`	`128`	Максимальное число событий в спане
`OTEL_SPAN_LINK_COUNT_LIMIT`	`128`	Максимальное число ссылок в спане
`OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT`	`128`	Максимальное число атрибутов события
`OTEL_LINK_ATTRIBUTE_COUNT_LIMIT`	`128`	Максимальное число атрибутов ссылки
`OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT`	наследует `OTEL_ATTRIBUTE_COUNT_LIMIT`	Переопределение для записей лога
`OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT`	наследует `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`	Переопределение для записей лога

Смотрите также

Трассировка — ручная настройка провайдера трассировки
Логирование — ручная настройка провайдера логирования
Метрики — ручная настройка провайдера метрик
Экспорт — транспорты и TLS
Пропагация — пропагаторы контекста

Трассировка

Трассировка позволяет отслеживать цепочку вызовов внутри и между сервисами. Каждая единица работы называется спаном (span). Спаны образуют дерево, корнем которого является корневой спан (root span), а все остальные — дочерние.

Архитектура

ОтелПровайдерТрассировки
    └── ОтелТрассировщик
            └── ОтелСпан

ОтелПровайдерТрассировки — точка входа, создаёт трассировщики.
ОтелТрассировщик — создаёт спаны.
ОтелСпан — единица работы: хранит атрибуты, события, статус, временны́е метки.

Создание провайдера через построитель

ОтелПостроительПровайдераТрассировки предоставляет Fluent API для настройки провайдера.

bsl

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

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

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

Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .УстановитьРесурс(Ресурс)
    .ДобавитьПроцессор(Новый ОтелПакетныйПроцессорСпанов(Экспортер))
    .Построить();

Трассировщик = Провайдер.ПолучитьТрассировщик("my-library", "1.0.0");

Создание спанов

Простой спан

bsl

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

// ... работа ...

Область.Закрыть();
Спан.Завершить();

Дочерний спан

НачатьСпан автоматически подхватывает родителя из текущего контекста:

bsl

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

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

Область.Закрыть();
Спан.Завершить();

Корневой спан (явный родительский контекст)

bsl

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

Виды спанов (SpanKind)

ОтелВидСпана описывает роль спана в распределённой системе:

Метод	Описание
`ОтелВидСпана.Внутренний()`	Внутренняя операция (по умолчанию)
`ОтелВидСпана.Сервер()`	Входящий RPC/HTTP-запрос
`ОтелВидСпана.Клиент()`	Исходящий RPC/HTTP-запрос
`ОтелВидСпана.Производитель()`	Отправка сообщения в очередь
`ОтелВидСпана.Потребитель()`	Получение сообщения из очереди

Атрибуты

Атрибуты — пары ключ/значение, описывающие контекст операции:

bsl

Спан.УстановитьАтрибут("http.method", "GET");
Спан.УстановитьАтрибут("http.url", "/api/data");
Спан.УстановитьАтрибут("http.status_code", 200);
Спан.УстановитьАтрибут("db.rows_affected", 42);

События спана

События — именованные точки во времени с атрибутами:

bsl

// Простое событие
Спан.ДобавитьСобытие("cache-miss");

// Событие с атрибутами
Атрибуты = Новый ОтелАтрибуты();
Атрибуты.Установить("exception.type", "ФайлНеНайден");
Атрибуты.Установить("exception.message", "Файл config.json не найден");
Спан.ДобавитьСобытиеСАтрибутами("exception", Атрибуты);

Линки (Links)

Линки связывают спан с другим контекстом (например, асинхронные операции):

bsl

КонтекстСпана = ДругойСпан.ПолучитьКонтекст();
Линк = Новый ОтелЛинк(КонтекстСпана);
Спан = Трассировщик.НачатьСпан("async-операция", ОтелВидСпана.Внутренний(), , Массив(Линк));

Статус спана

ОтелКодСтатуса описывает результат операции:

Метод	Описание
`ОтелКодСтатуса.НеУстановлен()`	Статус не задан (по умолчанию)
`ОтелКодСтатуса.Ок()`	Операция завершилась успешно
`ОтелКодСтатуса.Ошибка()`	Операция завершилась с ошибкой

bsl

// Успешное завершение
Спан.УстановитьСтатус(ОтелКодСтатуса.Ок());

// Ошибка с описанием
Спан.УстановитьСтатус(ОтелКодСтатуса.Ошибка(), "Таймаут подключения к БД");

Семплирование

ОтелСэмплер контролирует, какие спаны записываются и экспортируются. Стратегия задаётся при создании провайдера или через OTEL_TRACES_SAMPLER.

Все спаны (разработка)10% трафика (продакшн)Через переменные окружения

bsl

Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .УстановитьСэмплер(ОтелСэмплер.ВсегдаВключен())
    .Построить();

bsl

Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .УстановитьСэмплер(ОтелСэмплер.НаОсновеРодителя(ОтелСэмплер.ПоДолеТрассировок(0.1)))
    .Построить();

bash

# 10% трафика
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

# Ничего не записывать
export OTEL_TRACES_SAMPLER=always_off

Доступные стратегии:

Метод	Описание
`ОтелСэмплер.ВсегдаВключен()`	Сэмплировать все спаны
`ОтелСэмплер.ВсегдаВыключен()`	Не сэмплировать ничего
`ОтелСэмплер.ПоДолеТрассировок(Доля)`	Случайная доля трассировок (0.0 – 1.0)
`ОтелСэмплер.НаОсновеРодителя(КорневойСэмплер)`	ParentBased: наследует решение родителя

Процессоры спанов

Простой процессор (для разработки)

Синхронно экспортирует каждый спан сразу после завершения. Подходит для отладки.

bsl

Процессор = Новый ОтелПростойПроцессорСпанов(Экспортер);

Пакетный процессор (для продакшена)

Накапливает спаны в очереди и отправляет пакетами в фоновом потоке.

bsl

Процессор = Новый ОтелПакетныйПроцессорСпанов(Экспортер);

Настройка через переменные окружения:

Переменная	По умолчанию	Описание
`OTEL_BSP_MAX_QUEUE_SIZE`	`2048`	Максимальный размер очереди
`OTEL_BSP_SCHEDULE_DELAY`	`5000`	Интервал экспорта (мс)
`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`	`512`	Максимальный размер пакета
`OTEL_BSP_EXPORT_TIMEOUT`	`30000`	Таймаут экспорта (мс)

Композитный процессор

Объединяет несколько процессоров для одновременной отправки в разные системы:

bsl

Процессор = Новый ОтелКомпозитныйПроцессорСпанов();
Процессор.ДобавитьПроцессор(Новый ОтелПакетныйПроцессорСпанов(ЭкспортерGrafana));
Процессор.ДобавитьПроцессор(Новый ОтелПакетныйПроцессорСпанов(ЭкспортерJaeger));

Лимиты спана

ОтелЛимитыСпана ограничивают количество атрибутов, событий и ссылок:

bsl

Лимиты = Новый ОтелЛимитыСпана();
// Настройки через конструктор или через ОтелКонфигурацияЛимитовСпана

Конфигурируются через переменные окружения:

Переменная	По умолчанию	Описание
`OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT`	`128`	Максимальное число атрибутов спана
`OTEL_SPAN_EVENT_COUNT_LIMIT`	`128`	Максимальное число событий
`OTEL_SPAN_LINK_COUNT_LIMIT`	`128`	Максимальное число ссылок
`OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT`	`128`	Максимальное число атрибутов события
`OTEL_LINK_ATTRIBUTE_COUNT_LIMIT`	`128`	Максимальное число атрибутов ссылки

Завершение работы

bsl

// Обязательно закрывайте провайдер для сброса незавершённых спанов
Провайдер.Закрыть();

Смотрите также

Автоконфигурация — настройка через env vars
Экспорт — транспорты и экспортеры
Пропагация — передача контекста между сервисами
API: ОтелСпан
API: ОтелТрассировщик
API: ОтелПровайдерТрассировки

Логирование

OpenTelemetry Logs API позволяет собирать структурированные записи логов и экспортировать их в формате OTLP. Логи автоматически коррелируют с трассировкой через контекст — в каждую запись автоматически добавляются TraceId и SpanId текущего активного спана.

Архитектура

ОтелПровайдерЛогирования
    └── ОтелЛоггер
            └── ОтелЗаписьЛога

ОтелПровайдерЛогирования — точка входа, создаёт логгеры.
ОтелЛоггер — создаёт и отправляет записи логов.
ОтелЗаписьЛога — запись с телом, уровнем серьёзности и атрибутами.

Создание провайдера через построитель

bsl

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

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

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

Провайдер = Новый ОтелПостроительПровайдераЛогирования()
    .УстановитьРесурс(Ресурс)
    .ДобавитьПроцессор(Новый ОтелПакетныйПроцессорЛогов(Экспортер))
    .Построить();

Логгер = Провайдер.ПолучитьЛоггер("my-library", "1.0.0");

Создание записей лога

ОтелЗаписьЛога строится через Fluent API:

Простая записьЗапись с атрибутамиЗапись об ошибке

bsl

Запись = Логгер.СоздатьЗаписьЛога();
Запись.УстановитьТело("Пользователь авторизован")
    .УстановитьСерьезность(ОтелСтепеньСерьезности.Info());

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

bsl

Запись = Логгер.СоздатьЗаписьЛога();
Запись.УстановитьТело("Запрос выполнен")
    .УстановитьСерьезность(ОтелСтепеньСерьезности.Info())
    .УстановитьАтрибут("user.id", "12345")
    .УстановитьАтрибут("http.method", "POST")
    .УстановитьАтрибут("http.status_code", 201);

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

bsl

Попытка
    // ... работа ...
Исключение
    Запись = Логгер.СоздатьЗаписьЛога();
    Запись.УстановитьТело(ОписаниеОшибки())
        .УстановитьСерьезность(ОтелСтепеньСерьезности.Error())
        .УстановитьАтрибут("exception.type", "ОшибкаВыполнения");
    Логгер.Записать(Запись);
КонецПопытки

Уровни серьёзности

ОтелСтепеньСерьезности соответствует спецификации OpenTelemetry (числовые значения 1–24):

Метод	Числовое значение	Описание
`ОтелСтепеньСерьезности.Trace()`	1	Детальная трассировка
`ОтелСтепеньСерьезности.Trace2()` – `Trace4()`	2–4	Варианты Trace
`ОтелСтепеньСерьезности.Debug()`	5	Отладочная информация
`ОтелСтепеньСерьезности.Debug2()` – `Debug4()`	6–8	Варианты Debug
`ОтелСтепеньСерьезности.Info()`	9	Информационное сообщение
`ОтелСтепеньСерьезности.Info2()` – `Info4()`	10–12	Варианты Info
`ОтелСтепеньСерьезности.Warn()`	13	Предупреждение
`ОтелСтепеньСерьезности.Warn2()` – `Warn4()`	14–16	Варианты Warn
`ОтелСтепеньСерьезности.Error()`	17	Ошибка
`ОтелСтепеньСерьезности.Error2()` – `Error4()`	18–20	Варианты Error
`ОтелСтепеньСерьезности.Fatal()`	21	Критическая ошибка
`ОтелСтепеньСерьезности.Fatal2()` – `Fatal4()`	22–24	Варианты Fatal

Корреляция с трассировкой

Корреляция происходит автоматически. Если в момент записи лога активен спан, его TraceId и SpanId добавляются в запись:

bsl

// Трассировка уже инициализирована
Спан = Трассировщик.НачатьСпан("обработка", ОтелВидСпана.Внутренний());
Область = Спан.СделатьТекущим();

// Запись лога автоматически получит TraceId и SpanId из контекста
Запись = Логгер.СоздатьЗаписьЛога();
Запись.УстановитьТело("Начало обработки")
    .УстановитьСерьезность(ОтелСтепеньСерьезности.Info());
Логгер.Записать(Запись);

Область.Закрыть();
Спан.Завершить();

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

ОтелАппендерLogos перенаправляет все сообщения библиотеки logos в OpenTelemetry. Это позволяет использовать привычный API logos, не меняя код.

bsl

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

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

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

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

// Создаём аппендер и добавляем его к logos-логу
Аппендер = Новый ОтелАппендерLogos(ОтелЛоггер);

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

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

Маппинг уровней logos → ОтелСтепеньСерьезности:

logos	OTel Severity
`Отладка`	`Debug`
`Информация`	`Info`
`Предупреждение`	`Warn`
`Ошибка`	`Error`

Мост логов → события спана

ОтелПроцессорСобытийВSpanEvents преобразует записи логов в события активного спана. Это удобно для отображения логов непосредственно в трассировке:

bsl

// Добавляем процессор, который пишет логи как span events
Провайдер = Новый ОтелПостроительПровайдераЛогирования()
    .УстановитьРесурс(Ресурс)
    .ДобавитьПроцессор(Новый ОтелПростойПроцессорЛогов(Экспортер))
    .ДобавитьПроцессор(Новый ОтелПроцессорСобытийВSpanEvents())
    .Построить();

Процессоры логов

Простой процессор (для разработки)

bsl

Процессор = Новый ОтелПростойПроцессорЛогов(Экспортер);

Пакетный процессор (для продакшена)

bsl

Процессор = Новый ОтелПакетныйПроцессорЛогов(Экспортер);

Пакетный процессор логов использует те же настройки OTEL_BSP_*, что и для спанов, но значение по умолчанию OTEL_BSP_SCHEDULE_DELAY = 1000 мс (вместо 5000 у спанов).

Композитный процессор

bsl

Процессор = Новый ОтелКомпозитныйПроцессорЛогов();
Процессор.ДобавитьПроцессор(Новый ОтелПакетныйПроцессорЛогов(Экспортер));
Процессор.ДобавитьПроцессор(Новый ОтелПроцессорСобытийВSpanEvents());

Смотрите также

Автоконфигурация — настройка через OTEL_LOGS_EXPORTER
Трассировка — корреляция логов со спанами
Экспорт — эндпоинт /v1/logs
API: ОтелЛоггер
API: ОтелЗаписьЛога

Метрики

OpenTelemetry Metrics API позволяет измерять числовые характеристики системы: счётчики запросов, время ответа, использование ресурсов и другие показатели. Метрики периодически собираются и экспортируются в формате OTLP.

Архитектура

ОтелПровайдерМетрик
    └── ОтелМетр
            ├── ОтелСчетчик
            ├── ОтелРеверсивныйСчетчик
            ├── ОтелДатчик
            ├── ОтелГистограмма
            ├── ОтелЭкспоненциальнаяГистограмма
            ├── ОтелНаблюдаемыйСчетчик
            ├── ОтелНаблюдаемыйРеверсивныйСчетчик
            └── ОтелНаблюдаемыйДатчик

Создание провайдера

bsl

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

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

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

// Периодический читатель — экспортирует каждые 60 секунд
Читатель = Новый ОтелПериодическийЧитательМетрик(Экспортер, 60000);
Читатель.Запустить();

Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .УстановитьРесурс(Ресурс)
    .ДобавитьЧитатель(Читатель)
    .Построить();

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

Синхронные инструменты

Counter (Счётчик)

Монотонно возрастающий счётчик. Используется для подсчёта событий, запросов, байт и т.п.

bsl

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

// Использование
Счетчик.Добавить(1);

// С атрибутами
Атрибуты = Новый ОтелАтрибуты();
Атрибуты.Установить("http.method", "GET");
Атрибуты.Установить("http.status_code", 200);
Счетчик.Добавить(1, Атрибуты);

UpDownCounter (Реверсивный счётчик)

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

bsl

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

ОчередьСчетчик.Добавить(1);   // задача добавлена
ОчередьСчетчик.Добавить(-1);  // задача обработана

Gauge (Датчик)

Фиксирует последнее измеренное значение. Используется для CPU, памяти, температуры.

bsl

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

// С атрибутами
Атрибуты = Новый ОтелАтрибуты();
Атрибуты.Установить("cpu.core", "0");
Датчик.Записать(62.3, Атрибуты);

Histogram (Гистограмма)

Распределяет значения по корзинам. Идеально для времени ответа, размеров запросов.

bsl

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

// Запись измерения
Гистограмма.Записать(150);

// С атрибутами
Атрибуты = Новый ОтелАтрибуты();
Атрибуты.Установить("http.route", "/api/orders");
Гистограмма.Записать(230, Атрибуты);

ExponentialHistogram (Экспоненциальная гистограмма)

Гистограмма с автоматическими экспоненциальными корзинами. Более точная при широком диапазоне значений.

bsl

ЭксГистограмма = Метр.СоздатьЭкспоненциальнуюГистограмму("db.query.duration", "Время запроса к БД", "ms");
ЭксГистограмма.Записать(45);

Наблюдаемые (асинхронные) инструменты

Наблюдаемые инструменты вызывают callback-функцию при каждом сборе метрик. Это удобно для измерений, которые дорого получать по запросу.

ObservableCounter

bsl

// Регистрация callback
Функция ПолучитьОшибки(Наблюдение) Экспорт
    // вызывается при каждом сборе метрик
    Наблюдение.Записать(ПолучитьКоличествоОшибокИзСистемы());
КонецФункции

НаблСчетчик = Метр.СоздатьНаблюдаемыйСчетчик("process.errors", "Количество ошибок", "1");
НаблСчетчик.ДобавитьCallback(ЭтотОбъект, "ПолучитьОшибки");

ObservableUpDownCounter

bsl

Функция ПолучитьРазмерПула(Наблюдение) Экспорт
    Наблюдение.Записать(ПулСоединений.Размер());
КонецФункции

НаблРеверсивный = Метр.СоздатьНаблюдаемыйРеверсивныйСчетчик("db.pool.size", "Размер пула", "1");
НаблРеверсивный.ДобавитьCallback(ЭтотОбъект, "ПолучитьРазмерПула");

ObservableGauge

bsl

Функция ПолучитьПамять(Наблюдение) Экспорт
    Наблюдение.Записать(ПолучитьИспользуемуюПамятьМб());
КонецФункции

НаблДатчик = Метр.СоздатьНаблюдаемыйДатчик("process.memory", "Использование памяти", "MB");
НаблДатчик.ДобавитьCallback(ЭтотОбъект, "ПолучитьПамять");

Периодический читатель метрик

ОтелПериодическийЧитательМетрик запускает фоновый поток, который собирает и экспортирует метрики с заданным интервалом.

bsl

// Интервал задаётся в миллисекундах (60000 = 60 секунд)
Читатель = Новый ОтелПериодическийЧитательМетрик(Экспортер, 60000);
Читатель.Запустить();

// ... работа приложения ...

// При завершении — сброс накопленных метрик
Провайдер.Закрыть();

Настройка через переменную окружения:

bash

export OTEL_METRIC_EXPORT_INTERVAL=30000  # каждые 30 секунд

Читатель Prometheus

ОтелПрометеусЧитательМетрик предоставляет метрики в формате Prometheus для scraping:

bsl

Читатель = Новый ОтелПрометеусЧитательМетрик();

Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .УстановитьРесурс(Ресурс)
    .ДобавитьЧитатель(Читатель)
    .Построить();

Представления (Views)

ОтелПредставление позволяет переименовывать инструменты, фильтровать атрибуты и менять агрегацию.

Фильтрация атрибутовСмена агрегации

bsl

// Оставить только нужные атрибуты, убрать чувствительные данные
Селектор = Новый ОтелСелекторИнструментов();
Селектор.УстановитьИмяИнструмента("http.requests");

Представление = Новый ОтелПредставление();
Представление.УстановитьСелектор(Селектор);
Представление.УстановитьФильтрАтрибутов(Новый ОтелФильтрМетрик("http.method", "http.status_code"));

Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .ДобавитьПредставление(Представление)
    .Построить();

bsl

// Использовать экспоненциальную гистограмму вместо явных корзин
Селектор = Новый ОтелСелекторИнструментов();
Селектор.УстановитьИмяИнструмента("http.duration");

Представление = Новый ОтелПредставление();
Представление.УстановитьСелектор(Селектор);
Представление.УстановитьАгрегацию(ОтелАгрегация.ExponentialHistogram());

Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .ДобавитьПредставление(Представление)
    .Построить();

Агрегации

ОтелАгрегация определяет, как измерения объединяются в точку данных:

Метод	Описание
`ОтелАгрегация.Sum()`	Сумма всех измерений (Counter, UpDownCounter)
`ОтелАгрегация.LastValue()`	Последнее значение (Gauge)
`ОтелАгрегация.ExplicitBucketHistogram()`	Гистограмма с явными корзинами
`ОтелАгрегация.ExponentialHistogram()`	Экспоненциальная гистограмма
`ОтелАгрегация.Drop()`	Отбросить измерения (отключить инструмент)

Временна́я агрегация

ОтелВременнаяАгрегация определяет, как агрегируются данные во времени:

Значение	Описание
`Cumulative`	Накопительные значения с начала работы (по умолчанию)
`Delta`	Разница за интервал экспорта

bash

# Настройка через переменную окружения
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta

Смотрите также

Автоконфигурация — настройка через OTEL_METRICS_EXPORTER, OTEL_METRIC_EXPORT_INTERVAL
Экспорт — эндпоинт /v1/metrics
API: ОтелМетр
API: ОтелПровайдерМетрик

Пропагация контекста

Пропагация контекста — механизм передачи телеметрических данных (trace ID, baggage) через границы сервисов. SDK поддерживает W3C Trace Context, W3C Baggage и B3 (через отдельный пакет).

Что такое пропагация

При каждом вызове между сервисами необходимо передать информацию о текущей трассировке — иначе спаны разных сервисов не будут связаны в единую трассу. Пропагаторы сериализуют контекст в HTTP-заголовки (Inject) и десериализуют обратно (Extract).

Сервис A (Inject) → HTTP-заголовки → Сервис B (Extract)
   traceparent: 00-4bf92f3577b34da6...
   baggage: userId=alice,env=prod

W3C Trace Context

ОтелW3CПропагатор работает с заголовками traceparent и tracestate по стандарту W3C Trace Context.

Внедрение в исходящий запросИзвлечение из входящего запроса

bsl

// Спан уже активен в текущем контексте
Заголовки = Новый Соответствие();
Пропагатор = Новый ОтелW3CПропагатор();
Сеттер = Новый ОтелСеттерТекстовойКарты();

Пропагатор.Внедрить(ОтелКонтекст.Текущий(), Заголовки, Сеттер);
// Заголовки["traceparent"] = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
// Заголовки["tracestate"] = ""

bsl

Пропагатор = Новый ОтелW3CПропагатор();
Геттер = Новый ОтелГеттерТекстовойКарты();

НовыйКонтекст = Пропагатор.Извлечь(ОтелКонтекст.Текущий(), ВходящиеЗаголовки, Геттер);

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

W3C Baggage

ОтелW3CBaggageПропагатор передаёт произвольные данные в заголовке baggage по стандарту W3C Baggage.

bsl

// Создание baggage
Baggage = Новый ОтелBaggage();
Baggage.УстановитьЭлемент("userId", "alice");
Baggage.УстановитьЭлемент("env", "production");

// Помещение baggage в контекст
КонтекстСBaggage = ОтелКонтекст.Текущий().УстановитьBaggage(Baggage);

// Внедрение в заголовки
Заголовки = Новый Соответствие();
Пропагатор = Новый ОтелW3CBaggageПропагатор();
Сеттер = Новый ОтелСеттерТекстовойКарты();
Пропагатор.Внедрить(КонтекстСBaggage, Заголовки, Сеттер);
// Заголовки["baggage"] = "userId=alice,env=production"

// Извлечение на стороне получателя
Геттер = Новый ОтелГеттерТекстовойКарты();
НовыйКонтекст = Пропагатор.Извлечь(ОтелКонтекст.Текущий(), ВходящиеЗаголовки, Геттер);
ПолученныйBaggage = НовыйКонтекст.ПолучитьBaggage();

Композитный пропагатор

ОтелКомпозитныйПропагатор объединяет несколько пропагаторов. Inject и Extract вызываются для каждого из них последовательно.

bsl

Пропагатор = Новый ОтелКомпозитныйПропагатор();
Пропагатор.ДобавитьПропагатор(Новый ОтелW3CПропагатор());
Пропагатор.ДобавитьПропагатор(Новый ОтелW3CBaggageПропагатор());

// Использование через глобальный SDK
ОтелГлобальный.УстановитьПропагаторы(Пропагатор);

// Внедрение всех форматов сразу
Заголовки = Новый Соответствие();
Пропагаторы = ОтелГлобальный.ПолучитьПропагаторы();
Пропагаторы.Внедрить(ОтелКонтекст.Текущий(), Заголовки);
// traceparent + tracestate + baggage — все в одних заголовках

Геттер и сеттер текстовой карты

ОтелГеттерТекстовойКарты и ОтелСеттерТекстовойКарты — адаптеры для работы с Соответствие:

bsl

// Сеттер — записывает заголовок в соответствие
Сеттер = Новый ОтелСеттерТекстовойКарты();

// Геттер — читает заголовок из соответствия (регистронезависимо)
Геттер = Новый ОтелГеттерТекстовойКарты();

// Можно реализовать собственный геттер/сеттер для
// нестандартных структур данных (например, заголовки HTTP-запроса)

Пропагаторы по умолчанию

При автоконфигурации ОтелАвтоконфигурация.Инициализировать() автоматически регистрирует пропагаторы, заданные в OTEL_PROPAGATORS (по умолчанию: tracecontext,baggage).

bsl

// После автоконфигурации — глобальные пропагаторы уже настроены
Сдк = ОтелАвтоконфигурация.Инициализировать();

// Inject/Extract через глобальный доступ
Пропагаторы = ОтелГлобальный.ПолучитьПропагаторы();
Пропагаторы.Внедрить(ОтелКонтекст.Текущий(), Заголовки);

B3 пропагатор (отдельный пакет)

Согласно спецификации Propagators Distribution, B3 и Jaeger пропагаторы поставляются отдельными пакетами.

Для поддержки B3 установите пакет opentelemetry-propagator-b3:

bash

opm install opentelemetry-propagator-b3

После установки включите B3 через переменную окружения:

bash

# B3 Single Header
export OTEL_PROPAGATORS=tracecontext,baggage,b3

# B3 Multi Header
export OTEL_PROPAGATORS=tracecontext,baggage,b3multi

B3 Single Header использует заголовок b3, B3 Multi Header — отдельные заголовки X-B3-TraceId, X-B3-SpanId, X-B3-Sampled.

Настройка через переменные окружения

Переменная	По умолчанию	Описание
`OTEL_PROPAGATORS`	`tracecontext,baggage`	Список пропагаторов через запятую

Поддерживаемые значения:

Значение	Пропагатор	Заголовки
`tracecontext`	`ОтелW3CПропагатор`	`traceparent`, `tracestate`
`baggage`	`ОтелW3CBaggageПропагатор`	`baggage`
`b3`	B3 Single (пакет `opentelemetry-propagator-b3`)	`b3`
`b3multi`	B3 Multi (пакет `opentelemetry-propagator-b3`)	`X-B3-TraceId`, `X-B3-SpanId`, …
`none`	—	Отключить все пропагаторы

Смотрите также

Автоконфигурация — настройка OTEL_PROPAGATORS
Трассировка — создание спанов и контекст
API: ОтелW3CПропагатор
API: ОтелКомпозитныйПропагатор

Экспорт данных

SDK поддерживает три транспорта для отправки телеметрии: HTTP (JSON и Protobuf), gRPC и InMemory (для тестов). Все экспортеры работают с любым транспортом — достаточно передать нужный объект транспорта.

Архитектура

Транспорт → Экспортер → Процессор → Провайдер

Транспорт (ОтелHttpТранспорт, ОтелGrpcТранспорт, ОтелВПамятьТранспорт) — отвечает за физическую отправку данных.
Экспортер (ОтелЭкспортерСпанов, ОтелЭкспортерЛогов, ОтелЭкспортерМетрик) — сериализует данные и передаёт транспорту.
Процессор — буферизирует и вызывает экспортер.

HTTP-транспорт

ОтелHttpТранспорт отправляет данные по OTLP/HTTP (порт 4318). Поддерживает два формата: http/protobuf (по умолчанию) и http/json.

HTTP/protobuf (по умолчанию)HTTP/JSONС заголовками и таймаутомС gzip сжатием

bsl

// Protobuf — бинарный формат, более компактный
Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
// Транспорт.УстановитьПротокол("http/protobuf"); // явно, необязательно

bsl

Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Транспорт.УстановитьПротокол("http/json");

bsl

Транспорт = Новый ОтелHttpТранспорт("http://otel-collector:4318");
Транспорт.УстановитьПротокол("http/protobuf");
Транспорт.УстановитьЗаголовок("Authorization", "Bearer my-token");
Транспорт.УстановитьЗаголовок("X-Team", "backend");
Транспорт.УстановитьТаймаут(15000); // 15 секунд

bsl

Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Транспорт.УстановитьСжатие("gzip");

Эндпоинты HTTP

Экспортеры автоматически добавляют суффикс пути к базовому URL транспорта:

Экспортер	Путь
`ОтелЭкспортерСпанов`	`/v1/traces`
`ОтелЭкспортерЛогов`	`/v1/logs`
`ОтелЭкспортерМетрик`	`/v1/metrics`

gRPC-транспорт

ОтелGrpcТранспорт отправляет данные по OTLP/gRPC (порт 4317) через библиотеку oint (OPI_GRPC).

Для использования gRPC необходимо установить oint 1.33.0+: opm install oint

bsl

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

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

// Все три экспортера работают с gRPC так же, как с HTTP
ЭкспортерСпанов = Новый ОтелЭкспортерСпанов(Транспорт);
ЭкспортерЛогов = Новый ОтелЭкспортерЛогов(Транспорт);
ЭкспортерМетрик = Новый ОтелЭкспортерМетрик(Транспорт);

InMemory-транспорт (для тестов)

ОтелВПамятьТранспорт сохраняет сериализованные данные в памяти. Используется в тестах для проверки экспортируемых данных без реальной сети.

bsl

Транспорт = Новый ОтелВПамятьТранспорт();

Экспортер = Новый ОтелЭкспортерСпанов(Транспорт);
Процессор = Новый ОтелПростойПроцессорСпанов(Экспортер);

Провайдер = Новый ОтелПровайдерТрассировки(Ресурс, Процессор);
Трассировщик = Провайдер.ПолучитьТрассировщик("test");

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

// Проверка экспортированных данных
Записи = Транспорт.ПолучитьЗаписи();
// Записи — массив сериализованных OTLP-пакетов

TLS

ОтелНастройкиTls позволяет настроить взаимную TLS-аутентификацию (mTLS):

bsl

НастройкиTls = Новый ОтелНастройкиTls();
НастройкиTls.УстановитьПутьКСертификатуCA("/etc/ssl/certs/ca.pem");
НастройкиTls.УстановитьПутьККлиентскомуКлючу("/etc/ssl/private/client.key");
НастройкиTls.УстановитьПутьККлиентскомуСертификату("/etc/ssl/certs/client.pem");

Транспорт = Новый ОтелHttpТранспорт("https://otel-collector:4318");
Транспорт.УстановитьНастройкиTls(НастройкиTls);

TLS через переменные окружения:

Переменная	Описание
`OTEL_EXPORTER_OTLP_CERTIFICATE`	Путь к CA-сертификату (PEM)
`OTEL_EXPORTER_OTLP_CLIENT_KEY`	Путь к клиентскому ключу (PEM)
`OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`	Путь к клиентскому сертификату (PEM)
`OTEL_EXPORTER_OTLP_INSECURE`	`true` — отключить проверку TLS (небезопасно)

Полные примеры

Трассировка + Логирование + Метрики

bsl

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

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

// Один транспорт для всех сигналов
Транспорт = Новый ОтелHttpТранспорт("http://otel-collector:4318");

// Трассировка
ЭкспортерСпанов = Новый ОтелЭкспортерСпанов(Транспорт);
ПроцессорСпанов = Новый ОтелПакетныйПроцессорСпанов(ЭкспортерСпанов);
ПровайдерТрассировки = Новый ОтелПровайдерТрассировки(Ресурс, ПроцессорСпанов);

// Логирование
ЭкспортерЛогов = Новый ОтелЭкспортерЛогов(Транспорт);
ПроцессорЛогов = Новый ОтелПакетныйПроцессорЛогов(ЭкспортерЛогов);
ПровайдерЛогирования = Новый ОтелПровайдерЛогирования(Ресурс, ПроцессорЛогов);

// Метрики
ЭкспортерМетрик = Новый ОтелЭкспортерМетрик(Транспорт);
Читатель = Новый ОтелПериодическийЧитательМетрик(ЭкспортерМетрик, 60000);
Читатель.Запустить();
ПровайдерМетрик = Новый ОтелПровайдерМетрик(Ресурс, Читатель);

// Завершение — сбрасывает все буферы
ПровайдерТрассировки.Закрыть();
ПровайдерЛогирования.Закрыть();
ПровайдерМетрик.Закрыть();

gRPC для всех сигналов

bsl

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

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

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

// Трассировка
ЭкспортерСпанов = Новый ОтелЭкспортерСпанов(Транспорт);
ПроцессорСпанов = Новый ОтелПакетныйПроцессорСпанов(ЭкспортерСпанов);
Провайдер = Новый ОтелПровайдерТрассировки(Ресурс, ПроцессорСпанов);

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

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

Смотрите также

Автоконфигурация — настройка через OTEL_EXPORTER_OTLP_*
Трассировка — экспортер спанов
Логирование — экспортер логов
Метрики — экспортер метрик
API: ОтелHttpТранспорт
API: ОтелGrpcТранспорт

OpenTelemetry SDK для OneScript ​

Возможности ​

Установка ​

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

Требования ​

Дальнейшее изучение ​

Автоконфигурация ​

Как работает автоконфигурация ​

Инициализация ​

Настройка через переменные окружения ​

Настройка через файл конфигурации (configor) ​

Полная таблица переменных окружения ​

Общие параметры SDK ​

Экспортеры ​

OTLP — общие параметры ​

OTLP — трассировка (per-signal) ​

OTLP — логирование (per-signal) ​

OTLP — метрики (per-signal) ​

Семплирование трассировки ​

Пакетный процессор спанов (BatchSpanProcessor) ​

Периодический экспорт метрик ​

Пропагаторы контекста ​

Ограничения атрибутов ​

Смотрите также ​

Трассировка ​

Архитектура ​

Создание провайдера через построитель ​

Создание спанов ​

Простой спан ​

Дочерний спан ​

Корневой спан (явный родительский контекст) ​

Виды спанов (SpanKind) ​

Атрибуты ​

События спана ​

Линки (Links) ​

Статус спана ​

Семплирование ​

Процессоры спанов ​

Простой процессор (для разработки) ​

Пакетный процессор (для продакшена) ​

Композитный процессор ​

Лимиты спана ​

Завершение работы ​

Смотрите также ​

Логирование ​

Архитектура ​

Создание провайдера через построитель ​

Создание записей лога ​

Уровни серьёзности ​

Корреляция с трассировкой ​

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

Мост логов → события спана ​

Процессоры логов ​

Простой процессор (для разработки) ​

Пакетный процессор (для продакшена) ​

Композитный процессор ​

Смотрите также ​

Метрики ​

Архитектура ​

Создание провайдера ​

Синхронные инструменты ​

Counter (Счётчик) ​

UpDownCounter (Реверсивный счётчик) ​

Gauge (Датчик) ​

Histogram (Гистограмма) ​

ExponentialHistogram (Экспоненциальная гистограмма) ​

Наблюдаемые (асинхронные) инструменты ​

ObservableCounter ​

ObservableUpDownCounter ​

ObservableGauge ​

Периодический читатель метрик ​

Читатель Prometheus ​

Представления (Views) ​

Агрегации ​

Временна́я агрегация ​

Смотрите также ​

Пропагация контекста ​

Что такое пропагация ​

W3C Trace Context ​

W3C Baggage ​

OpenTelemetry SDK для OneScript

Возможности

Установка

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

Требования

Дальнейшее изучение

Автоконфигурация

Как работает автоконфигурация

Инициализация

Настройка через переменные окружения

Настройка через файл конфигурации (configor)

Полная таблица переменных окружения

Общие параметры SDK

Экспортеры

OTLP — общие параметры

OTLP — трассировка (per-signal)

OTLP — логирование (per-signal)

OTLP — метрики (per-signal)

Семплирование трассировки

Пакетный процессор спанов (BatchSpanProcessor)

Периодический экспорт метрик

Пропагаторы контекста

Ограничения атрибутов

Смотрите также

Трассировка

Архитектура

Создание провайдера через построитель

Создание спанов

Простой спан

Дочерний спан

Корневой спан (явный родительский контекст)

Виды спанов (SpanKind)

Атрибуты

События спана

Линки (Links)

Статус спана

Семплирование

Процессоры спанов

Простой процессор (для разработки)

Пакетный процессор (для продакшена)

Композитный процессор

Лимиты спана

Завершение работы

Смотрите также

Логирование

Архитектура

Создание провайдера через построитель

Создание записей лога

Уровни серьёзности

Корреляция с трассировкой

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

Мост логов → события спана

Процессоры логов

Простой процессор (для разработки)

Пакетный процессор (для продакшена)

Композитный процессор

Смотрите также

Метрики

Архитектура

Создание провайдера

Синхронные инструменты

Counter (Счётчик)

UpDownCounter (Реверсивный счётчик)

Gauge (Датчик)

Histogram (Гистограмма)

ExponentialHistogram (Экспоненциальная гистограмма)

Наблюдаемые (асинхронные) инструменты

ObservableCounter

ObservableUpDownCounter

ObservableGauge

Периодический читатель метрик

Читатель Prometheus

Представления (Views)

Агрегации

Временна́я агрегация

Смотрите также

Пропагация контекста

Что такое пропагация

W3C Trace Context

W3C Baggage