Просмотр кода страницы JavaScript (Node.js) OpenTelemetry

В этом пошаговом руководстве показано, как добавить наблюдаемость в ваше '''JavaScript'''-'''приложение''' с помощью библиотек и инструментов '''OpenTelemetry''' '''JavaScript'''.
{| class="wikitable"
!Особенность
!Поддержка
|-
|Автоматические инструменты
|Да
|-
|Трассировки
|Да
|-
|Метрики
|Да
|-
|Логи
|Нет
|}

== Предустановка ==

* Ключ-АСТРОМ версии '''1.222+'''
* Для трассировки включен контекст трассировки '''W3C'''.
*# Перейдите в '''Настройки > Предпочтения > Функции ЕдиногоАгента.'''
*# Включите опцию '''Отправлять HTTP-заголовки контекста трассировки W3C'''.

== Получение данных для доступа к Ключ-АСТРОМ ==

=== Определение базового URL API ===
Подробную информацию о сборке базового '''URL-адреса''' конечной точки '''OTLP''' см. в разделе [[Экспорт с помощью OTLP]]. '''URL-адрес''' должен заканчиваться на <code>/api/v2/otlp</code>.

=== Получение токена доступа API ===
Токен доступа для сбора трассировок, логов и метрик можно создать в разделе [[Токен доступа|Токены доступа]].

Экспорт с помощью '''OTLP''' содержит более подробную информацию о формате и необходимых областях доступа.

== Инициализирование OpenTelemetry ==
1. Выполните следующую команду <code>npm</code>, чтобы установить необходимые библиотеки и зависимости.
{| class="wikitable"
|npm install \

  @opentelemetry/api \

  @opentelemetry/exporter-metrics-otlp-proto \

  @opentelemetry/exporter-trace-otlp-proto \

  @opentelemetry/instrumentation \

  @opentelemetry/resources \

  @opentelemetry/sdk-metrics \

  @opentelemetry/sdk-trace-node \

  @opentelemetry/semantic-conventions
|}
В зависимости от используемых вашим приложением библиотек могут также потребоваться дополнительные библиотеки поддержки инструментирования, которые вы захотите добавить в зависимости. Список библиотек поддержки можно найти [https://www.npmjs.com/search?q=%40opentelemetry%2Finstrumentation здесь]. Примерами типичных библиотек '''HTTP''' и сетевых библиотек являются [https://www.npmjs.com/package/@opentelemetry/instrumentation-http @opentelemetry/instrumentation-http] и [https://www.npmjs.com/package/@opentelemetry/instrumentation-net @opentelemetry/instrumentation-net].

2. Создайте файл с именем <code>otel.js</code> в директории вашего приложения и сохраните следующее содержимое.
{| class="wikitable"
|const opentelemetry = require("@opentelemetry/api");

const { resourceFromAttributes, emptyResource, defaultResource } = require("@opentelemetry/resources");

const { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } = require("@opentelemetry/semantic-conventions");

const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");

const { registerInstrumentations } = require("@opentelemetry/instrumentation");

const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");

const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-proto");

const { OTLPMetricExporter } = require("@opentelemetry/exporter-metrics-otlp-proto");

const { MeterProvider, PeriodicExportingMetricReader, AggregationTemporality } = require('@opentelemetry/sdk-metrics');

const DT_API_URL = <nowiki>''</nowiki>; // TODO: Provide your SaaS/Managed URL here

const DT_API_TOKEN = <nowiki>''</nowiki>; // TODO: Provide the OpenTelemetry-scoped access token here

// ===== GENERAL SETUP =====

registerInstrumentations({

  instrumentations: [ /* TODO Register your auto-instrumentation libraries here */ ],

});

const fs = require("fs");

let dtmetadata = emptyResource();

for (let name of ['dt_metadata_e617c525669e072eebe3d0f08212e8f2.json', '/var/lib/astromkey/enrichment/dt_metadata.json', '/var/lib/astromkey/enrichment/dt_host_metadata.json']) {

  try {

    dtmetadata = dtmetadata.merge(

      resourceFromAttributes(JSON.parse(fs.readFileSync(name.startsWith("/var") ?

        name : fs.readFileSync(name).toString('utf-8').trim()).toString('utf-8'))));

    break

  } catch { }

}

const resource =

  defaultResource().merge(

    resourceFromAttributes({

      [ATTR_SERVICE_NAME]: "js-agent",

      [ATTR_SERVICE_VERSION]: "0.1.0",

    })

  ).merge(dtmetadata);

// ===== TRACING SETUP =====

const exporter = new OTLPTraceExporter({

    url: DT_API_URL + '/v1/traces',

    headers: { Authorization: 'Api-Token ' + DT_API_TOKEN }

});

const processor = new BatchSpanProcessor(exporter);

const provider = new NodeTracerProvider({

    resource: resource,

    spanProcessors: [ processor ]

});

provider.register();

// ===== METRIC SETUP =====

const metricExporter = new OTLPMetricExporter({

    url: DT_API_URL + '/v1/metrics',

    headers: { Authorization: 'Api-Token ' + DT_API_TOKEN },

    temporalityPreference: AggregationTemporality.DELTA

});

const metricReader = new PeriodicExportingMetricReader({

    exporter: metricExporter,

    exportIntervalMillis: 3000

});

const meterProvider = new MeterProvider({

    resource: resource,

    readers: [ metricReader ]

});

// Set this MeterProvider to be global to the app being instrumented.

opentelemetry.metrics.setGlobalMeterProvider(meterProvider);
|}
<u>Расширение данных Ключ-АСТРОМ</u>

Операции чтения файлов, анализирующие файлы <code>dt_metadata</code> в примере кода, пытаются прочитать файлы данных ЕдиногоАгента, чтобы расширить запрос '''OTLP''' и гарантировать, что вся соответствующая информация о топологии доступна в Ключ-АСТРОМ.

3. Если вы экспортируете с помощью '''OTLP''', настройте две переменные <code>DT_API_URL</code> и <code>DT_API_TOKEN</code>с их соответствующими значениями <code>otel.js</code>.

4. Измените вызов '''Node.js''' для вашего приложения, включив параметр командной строки [https://nodejs.org/api/cli.html#-r---require-module –require] и указав его на <code>otel.js</code>.
{| class="wikitable"
|node --require ./otel.js ./myapplication.js
|}

== Инструментирование приложения вручную ==

=== Добавление трассировки ===
1. Получите ссылку на '''API OpenTelemetry'''.
{| class="wikitable"
|const opentelemetry = require("@opentelemetry/api");
|}
2. Теперь мы можем получить объект трассировки.
{| class="wikitable"
|const tracer = opentelemetry.trace.getTracer('my-tracer');
|}
3. С помощью <code>tracer</code>, мы можем использовать конструктор интервалов для создания и запуска новых интервалов.
{| class="wikitable"
|const span = tracer.startSpan('Call to /myendpoint');

span.setAttribute('http.method', 'GET');

span.setAttribute('net.protocol.version','1.1');

// TODO your code goes here

span.end();
|}
В приведенном выше коде мы:

* Создали новый диапазон и назвали его «'''Call to /myendpoint'''».
* Добавили два атрибута, следуя [https://opentelemetry.io/docs/specs/semconv/general/trace/ семантическому соглашению об именовании], специфичные для действия этого диапазона: информацию о методе '''HTTP''' и версии.
* Добавили <code>TODO</code> вместо конечной бизнес-логики
* Вызвали метод span <code>end()</code> для завершения span.

=== Сбор метрик ===
1. Как и в случае с трассировкой, нам сначала нужно получить ссылку на '''API OpenTelemetry'''.
{| class="wikitable"
|const opentelemetry = require("@opentelemetry/api");
|}
2. Далее нам необходимо получить объект метрики.
{| class="wikitable"
|const meter = opentelemetry.metrics.getMeter('my-meter');
|}
3. С помощью <code>meter</code> мы теперь можем создавать отдельные инструменты, например, метрики.
{| class="wikitable"
|const requestCounter = meter.createCounter('request_counter', {

  description: 'The number of requests we received'

});
|}
4. Теперь мы можем вызвать метод <code>add()</code> для записи новых значений <code>requestCounter</code> с помощью метрики и сохранения дополнительных атрибутов (например, <code>action.type</code>).
{| class="wikitable"
|requestCounter.add(1, { 'action.type': 'create' });
|}
Вы также можете создать асинхронный датчик, для которого потребуется функция обратного вызова, которая будет вызываться '''OpenTelemetry''' при сборе данных.

В следующем примере при каждом вызове записывается доступная память:
{| class="wikitable"
|const gauge = meter.createObservableGauge('free_memory');

gauge.addCallback(r => {

    r.observe(require('os').freemem());

});
|}

=== Подключение логов ===
Примера пока нет, поскольку '''OpenTelemetry''' для '''Node.js''' пока не имеет стабильной поддержки логов.

В зависимости от статуса '''OpenTelemetry SDK''' предварительная версия может уже разрешать прием ваших логов.

=== Обеспечение распространения контекста (необязательно) ===
Распространение контекста особенно важно, когда задействованы сетевые вызовы (например, '''REST''').

Если вы используете автоматическое инструментирование и ваши сетевые библиотеки также им охватываются, то это будет автоматически реализовано библиотеками инструментирования. В противном случае ваш код должен это учитывать.

==== Извлечение контекста при получении запроса ====
В следующих примерах предполагается, что мы получили сетевой вызов через <code>[https://nodejs.org/api/http.html#class-httpclientrequest ClientRequest]</code> и используем <code>extract()</code> для создания объекта контекста <code>remoteCtx</code> на основе контекстной информации, полученной из '''HTTP-заголовков'''. Это позволяет нам продолжить предыдущую трассировку с нашими интервалами. 

==== Внедрение контекста при отправке запросов ====
В следующем примере мы используем '''HTTP'''-клиент '''[https://www.npmjs.com/package/axios axios]''' для отправки '''REST'''-запроса другой службе и предоставляем наш существующий контекст как часть '''HTTP'''-заголовков нашего запроса.

Для этого мы создаём объект <code>ctx</code>, передаём ему текущий диапазон и помечаем его как активный. Затем мы передаём этот объект контекста и пустой объект <code>my_headers</code> в <code>inject()</code>, и после возврата вызова в находятся соответствующие заголовки <code>my_headers</code>, которые мы можем в конечном итоге передать в наш '''HTTP'''-вызов.
{| class="wikitable"
|const ctx = opentelemetry.trace.setSpan(

    opentelemetry.context.active(),

    serverSpan

);

const my_headers = {};

opentelemetry.propagation.inject(ctx, my_headers);

await axios.get(URL, {headers: my_headers});

serverSpan.end();
|}

== Настройте сбор данных в соответствии с требованиями конфиденциальности (необязательно) ==
Хотя Ключ-АСТРОМ автоматически собирает все атрибуты '''OpenTelemetry''', в веб-интерфейсе Ключ-АСТРОМ сохраняются и отображаются только значения атрибутов, указанные в списке разрешенных. Это предотвращает случайное сохранение персональных данных, позволяя вам соблюдать требования к конфиденциальности и контролировать объем хранимых данных мониторинга.

Чтобы просматривать пользовательские атрибуты, необходимо сначала разрешить их использование в веб-интерфейсе Ключ-АСТРОМ.

== Проверка загрузки данных в Ключ-АСТРОМ ==
После завершения инструментирования вашего приложения выполните несколько тестовых действий для создания и отправки демонстрационных трассировок, метрик и логов, а также проверьте, что они были правильно загружены в Ключ-АСТРОМ.

Чтобы сделать это для трассировок, перейдите в раздел '''Трассировки''' и выберите вкладку '''Распределенные трассировки'''. Если вы используете ЕдиныйАгент, выберите '''PurePaths''' .

Для просмотра метрик и логов перейдите в раздел '''Метрики''' или '''Логов''' или '''Логи и события'''.