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

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

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

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

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

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

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

• Instrumentation for Next.js

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

Якщо бібліотека не постачається з 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 {
  SEMATTRS_HTTP_METHOD,
  SEMATTRS_HTTP_URL,
} 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(SEMATTRS_HTTP_METHOD, info.request.method);
      span.setAttribute(SEMATTRS_HTTP_URL, info.request.baseUrl);
    }
  },
});

/*instrumentation.js*/
const {
  SEMATTRS_HTTP_METHOD,
  SEMATTRS_HTTP_URL,
} = 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(SEMATTRS_HTTP_METHOD, info.request.method);
      span.setAttribute(SEMATTRS_HTTP_URL, info.request.baseUrl);
    }
  },
});

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

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

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

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

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

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

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

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

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