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

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

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

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

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

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

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

• Instrumentation for Next.js
• Instrumentation for SvelteKit

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

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

Наприклад, бібліотека інструментування для Express автоматично створюватиме відрізки на основі вхідних HTTP-запитів.

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

Кожна бібліотека інструментування є пакунком NPM. Наприклад, ось як ви можете встановити бібліотеки інструментування instrumentation-express та instrumentation-http для інструментування вхідного та вихідного HTTP-трафіку:

npm install --save @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express

OpenTelemetry JavaScript також визначає метапакунки auto-instrumentation-node та auto-instrumentation-web, які обʼєднують усі бібліотеки інструментування для Node.js або веб в один пакунок. Це зручний спосіб додати автоматично згенеровану телеметрію для всіх ваших бібліотек з мінімальними зусиллями:

• Node.js
• Browser

npm install --save @opentelemetry/auto-instrumentations-node

npm install --save @opentelemetry/auto-instrumentations-web

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

Реєстрація

Після встановлення необхідних бібліотек інструментування зареєструйте їх в OpenTelemetry SDK для Node.js. Якщо ви слідували Початку роботи, ви вже використовуєте метапакунки. Якщо ви слідували інструкціям для ініціалізації SDK для ручного інструментування, оновіть ваш instrumentation.ts (або instrumentation.js) наступним чином:

• TypeScript
• JavaScript

/*instrumentation.ts*/
...
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  ...
  // Це реєструє всі пакунки інструментування
  instrumentations: [getNodeAutoInstrumentations()]
});

sdk.start()

/*instrumentation.js*/
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');

const sdk = new NodeSDK({
  ...
  //Це реєструє всі пакунки інструментування
  instrumentations: [getNodeAutoInstrumentations()]
});

Щоб вимкнути окремі бібліотеки інструментування, ви можете застосувати наступну зміну:

• TypeScript
• JavaScript

/*instrumentation.ts*/
...
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  ...
  // Це реєструє всі пакунки інструментування
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-fs': {
        enabled: false,
      },
    }),
  ],
});

sdk.start()

/*instrumentation.js*/
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');

const sdk = new NodeSDK({
  ...
  // Це реєструє всі пакунки інструментування
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-fs': {
        enabled: false,
      },
    }),
  ],
});

Щоб завантажити лише окремі бібліотеки інструментування, замініть [getNodeAutoInstrumentations()] на список тих, які вам потрібні:

• TypeScript
• JavaScript

/*instrumentation.ts*/
...
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

const sdk = new NodeSDK({
  ...
  instrumentations: [
    // Інструментування Express очікує інструментування HTTP рівня
    new HttpInstrumentation(),
    new ExpressInstrumentation(),
  ]
});

sdk.start()

/*instrumentation.js*/
const { HttpInstrumentation } = require("@opentelemetry/instrumentation-http");
const { ExpressInstrumentation } = require("@opentelemetry/instrumentation-express");

const sdk = new NodeSDK({
  ...
  instrumentations: [
    // Інструментування Express очікує інструментування HTTP рівня
    new HttpInstrumentation(),
    new ExpressInstrumentation(),
  ]
});

Конфігурація

Деякі бібліотеки інструментування пропонують додаткові параметри конфігурації.

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

• TypeScript
• JavaScript

import { Span } from '@opentelemetry/api';
import {
  ATTR_HTTP_REQUEST_METHOD,
  ATTR_URL_FULL,
} from '@opentelemetry/semantic-conventions';
import {
  ExpressInstrumentation,
  ExpressLayerType,
  ExpressRequestInfo,
} from '@opentelemetry/instrumentation-express';

const expressInstrumentation = new ExpressInstrumentation({
  requestHook: function (span: Span, info: ExpressRequestInfo) {
    if (info.layerType === ExpressLayerType.REQUEST_HANDLER) {
      span.setAttribute(ATTR_HTTP_REQUEST_METHOD, info.request.method);
      span.setAttribute(ATTR_URL_FULL, info.request.baseUrl);
    }
  },
});

/*instrumentation.js*/
const {
  ATTR_HTTP_REQUEST_METHOD,
  ATTR_URL_FULL,
} = require('@opentelemetry/semantic-conventions');
const {
  ExpressInstrumentation,
  ExpressLayerType,
} = require('@opentelemetry/instrumentation-express');

const expressInstrumentation = new ExpressInstrumentation({
  requestHook: function (span, info) {
    if (info.layerType === ExpressLayerType.REQUEST_HANDLER) {
      span.setAttribute(ATTR_HTTP_REQUEST_METHOD, info.request.method);
      span.setAttribute(ATTR_URL_FULL, info.request.baseUrl);
    }
  },
});

Вам потрібно буде звернутися до документації кожної бібліотеки інструментування для розширеної конфігурації.

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

Ви можете знайти список доступних інструментів в реєстрі.

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

Якщо ви хочете додати нативне інструментування до вашої бібліотеки, вам слід ознайомитися з наступною документацією:

• Сторінка концепції Бібліотеки надає вам уявлення про те, коли інструментувати та що інструментувати
• Ручне інструментування надає вам необхідні приклади коду для створення трас, метрик і логів для вашої бібліотеки
• Посібник з реалізації інструментування для Node.js та оглядача містить найкращі практики для створення інструментування бібліотек.

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

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

Щоб створити таку бібліотеку, дотримуйтесь Посібника з реалізації інструментування для Node.js та оглядача.