Привет всем, Тедсуо здесь. Мы проходим важный этап на opentelemetry: Спецификация отслеживания Собирается, что заморожены, а выпуск кандидатов на реализацию отслеживания OpenTelemetry будут приходить в ближайшие пару месяцев, с метриками в течение следующих нескольких месяцев.
Пока мы собираем нашу основную документацию вместе, я думал, что теперь будет хорошее время, чтобы указать, насколько это просто использовать распределенные трассировки в JavaScript. OpenTelemetry — это крупные рамки, у него много вариантов и много площади поверхности. Но, как конечный пользователь, вам не нужно беспокоиться обо всем этом. Итак, забудьте подробности: этот прохождение содержит все, что вам нужно знать, чтобы на самом деле использовать OpenTelemetry в узле. Примените этот прохождение к вашей заявке, и вы хотите пойти.
TL; доктор
Все, что вам нужно знать, это:
- Инициализация: как начать и отключить чисто.
- Методы Tracer: GetTracer, GetCurrentsPan, Startspan и Mainspan.
- Методы охвата: SetAttribute, Addevent, RecordException, SetStatus и End.
Серьезно, вот и все. Если вы хотите попробовать, следуйте руководству ниже. Сильно комментированная версия готового учебника можно найти в https://github.com/tedsuo/otel-node-basics Отказ
Привет мир
Для этого учебника мы собираемся сделать очень простое приложение: экспресс-служба, которая отвечает на http://localhost: 9000/hello с «Hello World. » Это так же простое, как это оригинально!
Во-первых, сделайте каталог, чтобы содержать ваш проект и установить Express:
npm i express
Как только у нас есть, давайте доберемся до кодирования. Сделать файл под названием Server.js и служить доверим миром Hello:
const express = require('express');
const app = express();
app.get('/hello', (req, res) => {
res.status(200).send('Hello World');
});
app.listen(9000);
Тогда сделайте файл под названием Client.js который отправляет 5 запросов на сервер, а затем выходит.
const http = require('http');
function makeRequest() {
http.get({
host: 'localhost',
port: 9000,
path: '/hello',
}, (response) => {
const body = [];
response.on('data', (chunk) => body.push(chunk));
response.on('end', () => {
console.log(body.toString());
});
});
}
for (let i = 0; i < 5; i++) {
makeRequest();
}
Загрузить сервер и убедитесь, что он работает:
> node server.js
С помощью сервера запустите, тестируйте клиента на другой вкладке:
> node client.js Hello World Hello World Hello World
Архитектура opentelemetry за 30 секунд
Хорошо, я не сказал никаких подробностей, но вот один, который на самом деле полезно. У клиентов Opentelemetry есть два основных компонента: SDK и API. SDK — это фактическая структура, API — это то, что вы используете для инструмента вашего кода.
Это разделение обеспечивает свободную муфту: ваш код приложения зависит только от API, который практически не имеет зависимостей и действует как NO-OP, когда SDK не установлен. Это позволяет пакетам добавлять приборы без автоматического вытягивания в цепочку зависимости внедрения (думаю, GRPC и т. Д.). Это разделение проблем особенно полезно для библиотек OSS, которые хотят выпекать в приборостроении, но не хотят создавать конфликты накладных или зависимостей, когда opentelemetry не используется.
Совет: Никогда не ссылайтесь на любой пакет SDK вне установки и настройки. Все остальные пакеты и код приложения должны зависеть только от API.
Если вам было интересно, пока есть два JavaScript Sdks — один для Nodejs и один для браузера — есть только один JavaScript API. Примеренный код остается портативным между обеими средами.
Выберите спинку OpenTelemetry
ОК, давайте добавим opentelemetry на это приложение. Чтобы проверить нашу трассировку, вам нужно место для отправки данных.
На LightStep мы создали Свободные счета для жизни сообщества В частности, для создания OpenTelemetry легко экспериментировать с. Если у вас еще нет, пожалуйста, возьмите аккаунт.
Если вы хотите использовать Zipkin или Jaeger вместо этого Начало работы Руководство проведу тебя через установку. Как только вы установитесь, вы можете вернуться сюда и следуйте за остальным уроком.
Установить Nodejs opentelemetry Launcher
Поскольку мы подключаемся к Lightstep, мы также будем использовать Lightstep Distro opentelemetry, Opentelemetry Launchers Отказ Distros Package Up And Any Plugins и конфигурация, необходимая для того, чтобы поговорить с определенной бэкэной. На данный момент мы все еще любим полное определение дистрибутива (что разрешено, а что нет), но основной момент состоит в том, чтобы сделать начало проще, уменьшая конфигурацию Boaterplate. Если вы хотите более подробно, вы можете проверить Этот блог пост где я изначально предложил концепцию.
Установка пакета OpenTelemetry Launcher также установит OpenTelemetry, а также все доступные в настоящее время Приборы Отказ
npm i lightstep-opentelemetry-launcher-node
Создайте файл инициализации opentelemetry
Чтобы прибор вашего сервера вам нужно запустить OpenTelemetry SDK перед загрузкой вашего приложения. Что касается V0.12, opentelemetry nodejs загружает асинхронно, это на самом деле самый сложный бит opentelemetry прямо сейчас, а в будущих версиях будет двигаться в более простой синхронный запуск. Однако на данный момент вы можете скопировать и вставить подход ниже, и он будет работать для любого приложения.
Создайте файл под названием Server_init.js. Это будет служить вашим новым точкой входа. Вы можете скопировать и вставить код ниже.
const {
lightstep,
opentelemetry,
} = require('lightstep-opentelemetry-launcher-node');
const sdk = lightstep.configureOpenTelemetry({
accessToken: '',
serviceName: 'hello-server-1',
serviceVersion: 'v1.2.3',
propagators: 'tracecontext,b3',
});
sdk.start().then(() => {
require('./server');
});
function shutdown() {
sdk.shutdown().then(
() => console.log("SDK shut down successfully"),
(err) => console.log("Error shutting down SDK", err),
).finally(() => process.exit(0))
};
process.on('exit', shutdown);
process.on('SIGINT', shutdown);
process.on('SIGTERM', shutdown);
Настройте пусковую установку с помощью вашего LightStep Access. Токен (Вы можете найти ваш токен доступа на странице настроек). Создайте файл Client_init.js таким же образом, изменяйте только сервисное значение для «Hello-Client» и требуемый файл запуска «./Client».
Используйте Launcher, чтобы начать SDK. Как только SDK завершит настройки, потребуйте вашу первоначальную точку входа, чтобы начать свое приложение.
Зачем загружать ваше приложение в два этапа таз? Если ваше приложение начинает требовать пакеты (или бегать) до настройки OpenTelemetry, он может создавать проблемы. Инициализация OpenTelemetry в отдельном файле, и требуя только остальной части вашего приложения после начала SDK, OpenTelemetry имеет возможность автоматически применить любые доступные приборы, а также Автоопределение Любая доступна Системные ресурсы Прежде чем ваша приложение начинает работать. Это также гарантирует, что ваше приложение загружает нормально.
Запустите свое приложение с OpenTelemetry
Начните свой недавно автоматически приборный сервер и клиент. Давайте также включаем журналы отладки, чтобы мы могли видеть, что делает opentelemetry.
export OTEL_LOG_LEVEL=debug node server_init.js
export OTEL_LOG_LEVEL=debug node client_init.js
При запуске журналы отладки будут распечатаны конфигурацию и перечислите все успешно загруженные приборной библиотеки. Каждый раз, когда Tracer промывает данные, все пролеты, которые были экспортированы, напечатаны. Это может быть действительно полезно для отладки, когда вы настраиваете.
Проверьте, какое автоматическое приборостроение дает вам
Переключитесь на LightStep или вашу бэкэнду выбора, и подтвердить пролеты были получены:
Да, мы видим промежуток. Нажмите и посмотрите на трассировку:
Обратите внимание, что мы видим клиентский пролет из Hello-Client, Server Spant от Hello-Server, а несколько внутренних пролетов, представляющих встроенные экспресс-компоненты. Кроме того, обратите внимание, что клиентские и серверные пролеты уже заполняются HTTP, Network и другими атрибутами.
Вся эта общая информация стандартизирована через приборостроение как Семантические конвенции Отказ HTTP-запрос всегда будет описан с одинаковыми клавишами и значениями, независимо от того, от какого языка или пакета.
Это много действительно полезной информации. У нас уже есть полный след, с большим количеством деталей, и мы еще не написали никаких приборов. При выкату от OpenTelemetry это подход, который я рекомендую. Получите OpenTelemetry, установленные в каждый сервис и убедитесь, что контекст распространяется правильно, прежде чем добавлять дополнительную информацию. Это будет достаточно информации для настройки мониторинга ошибок и выявления проблем задержки.
Apentelemetry javascript API
Хорошо, поэтому опыт вне коробки дал вам долгий путь, но, конечно, вы в конечном итоге хотите добавить дополнительные данные приложения. Промедления должны быть идеально управляться вашей структурой приложения. В этом случае экспресс-структура управляет промежуткой для вас. В вашем приложении вы можете продолжать украшать эти промежутки с большим количеством информации. Существует два основных типа данных, которые вы захотите добавить: атрибуты и события.
Атрибуты охвата Индексы для сегментирования ваших данных. Например, вы можете добавить Project.id или аккаунт .id Чтобы понять, если медленные запросы и ошибки специфичны для определенного набора счетов или затрагивания каждого.
Прекрасная регистрация зерна может быть добавлена как Продолжительность событий . События являются формой структурированной регистрации — используйте их, как вы будете регистрировать. Преимущество с событиями охвата состоит в том, что вы можете автоматически найти все журналы, связанные с определенной транзакцией, а не на необходимость охоты с кучей поисков и фильтров. Когда вы масштабируете, это становится спасением (или, по крайней мере, большая экономия времени).
Во-первых, требуется APIPETELEMETRY API. На уровне пакета создайте трассировку и назовите его после пакета:
const opentelemetry = require('@opentelemetry/api');
const express = require('express');
// create a tracer and name it after your package
const tracer = opentelemetry.trace.getTracer('@otel-node-basics/server');
const app = express();
Имя траслера появляется на каждом промежутке, как приборостроение. Несколько ... атрибут. Это полезно для расследования проблем приборов.
После того, как у вас есть Tracer, вы можете использовать его для доступа к серверу промежуток, созданный экспрессовой приборами. Призыв tracer.getcurrentspan () вернет диапазон для текущего контекста. После того, как у вас есть доступ к диапазону, вы можете добавить атрибуты и события.
const app = express();
app.get('/hello', (req, res) => {
// access the span created by express instrumentation
span = tracer.getCurrentSpan();
// add an attribute to segment your data by projectID
span.setAttribute('projectID', '123');
// log an event and include some structured data.
span.addEvent('setting timeout', { sleep: 300 });
setTimeout(()=> {
span.addEvent(responding after timeout);
res.status(200).send('Hello World');
}, 300);
});
app.listen(9000);
Вы также можете цепи эти методы, которые могут быть немного более лаконичными.
app.get('/hello', (req, res) => {
tracer.getCurrentSpan()
.setAttribute('projectID', '123')
.addEvent('setting timeout', { sleep: 300 });
setTimeout(()=> {
tracer.getCurrentSpan().addEvent('sending response');
res.status(200).send('Hello World');
}, 300);
});
Запустите свой сервер и клиент еще раз, и вы увидите эти новые атрибуты и события, появляющиеся на одних и тех же пропанах.
Создавая свои собственные промежутки
Вы также можете создать свои собственные пролеты. Эти промежутки автоматически станут детьми текущего пролета и добавлены в след.
Management Management включает в себя три шага: запуск диапазона, устанавливая его в качестве текущего промежутка и заканчивая промежуток.
Чтобы начать детский пролет, снова возьмите трассировку и позвоните Tracer.Startspan (имя) Отказ Назовите SPAN после операции, которую вы измеряете. Советы по именованию можно найти в трассировке Технические характеристики .
ВАЖНЫЙ: Обязательно заканчивайте диапазон, когда ваша операция заканчивается, или у вас будет утечка!
После Span.end () называется, пролеты в очереди должны быть экспортированы на следующий мошенчковый. Звонки на SetAttribute и addevent стать без операции после Span.end () называется.
app.get('/hello', (req, res) => {
// start a new span named "sleeper"
const childSpan = tracer.startSpan("sleeper");
setTimeout(()=> {
// childSpan works normally when referenced
childSpan.addEvent('finished sleeping');
// However, starting a span does not automatically
// set it to the current span. getCurrentSpan still
// returns the parent span.
tracer.getCurrentSpan();
res.status(200).send('Hello World');
// Ending the span is a requirement. It measures the duration
// of the operation, and then sends the span to the exporter.
childSpan.end();
}, 300);
});
Итак, вышеупомянутые «работает», кроме детского диапазона не был установлен в качестве текущего пролета. Почти все обстоятельства это критично. Вы хотите, чтобы остальная часть вашего кода сможет получить доступ к пролету, не передавая его в качестве параметра. И если вы не установите новый пролет в качестве текущего, getcurrentspan вернет родительский пролет, который был бы неверным.
Итак, после начнете промежуток, создайте закрытие, в котором промежуток активен, вызывая Tracer.withspan (SPAN, CB) Отказ В обратном вызове новый Span теперь будет активным.
app.get('/hello', (req, res) => {
// start a new span named "sleeper"
const childSpan = tracer.startSpan("sleeper");
// use withSpan to create a new context
tracer.withSpan(childSpan,()=> {
setTimeout(()=> {
// getCurrentSpan now correctly returns childSpan
const span = tracer.getCurrentSpan();
span.addEvent('sending response');
res.status(200).send('Hello World');
span.end();
}, 300);
});
});
Мой совет — избегать создания детей детей, за исключением случаев, когда вы действительно нуждаетесь в новом контексте — разделяя операции базы данных из приложений-кода. В идеале управление промежутками должно произойти в каком-то структуре, а не разбросана о вашем коде приложения. О пользу добавления событий на создание детей-охвата. Если вы объедините все свои атрибуты на тот же пролет, вы получите лучшую индексацию.
Обработка ошибок
Существует один последний тип события, который заслуживает особого внимания: исключения. В OpenTelemetry исключения регистрируются как события. Но, чтобы убедиться, что исключение правильно отформатировано, span.recordexception (ошибка) Метод должен быть использован вместо addevent. .
app.get('/hello', (req, res) => {
try {
throw ("ooops");
} catch (error) {
// Add the exception as a properly formatted event.
span.recordException(error);
// Set the status code to make the exception count
// as an error.
span.setStatus({ code:
opentelemetry.CanonicalCode.UNKNOWN });
}
По умолчанию исключения не считаются ошибками. В OpenTelemetry ошибка означает, что общая операция не завершилась. Ожидается, что множество исключений, и исключение обрабатываемого исключения не означает, что вся операция не удалась завершить. В других случаях операция может потерпеть неудачу без брошенного исключения.
Чтобы объявить операцию сбой, позвоните Span.SetStatus () и пропустите код ошибки. Коды состояния используются инструментами анализа для автоматического запуска оповещения, измерения частоты ошибок и т. Д.
Примечание. Коды состояния будут упрощены в следующей версии OpenTelemetry.
Это все, люди!
И именно это. Все, что вам нужно знать, чтобы начать с трассировкой в Nodejs. Надеюсь, это было довольно прямыми вперед, и очищает любые загадки о том, как использовать opentelemetry.
Если вы придерживаетесь вышеуказанных шаблонов, вы можете получить много видимости с очень мало работы. Конечно, есть еще много деталей и вариантов; Вы можете проверить Документация API Чтобы получить больше информации. У меня также есть более вовлеченные Начало работы Руководство ; Он работает как удобная ссылка на все процедуры, описанные выше.
OpenTelemetry еще в бета-версии из-за изменения API, но она также уже в производстве во многих организациях. Если вы придерживаетесь Дистрибутив И автоматизированные приборы, вы можете использовать OpenTelemetry сегодня без особого страха на разрывное изменение, так как эти изменения, скорее всего, будут включать в себя API.
Если вы пишете ручное приборостроение во время бета-бета, рассмотрите возможность создания функций HELPER, которые упрощают API для ваших случаев использования и предоставляют вам централизованное место для управления любым потенциальным потенциалом.
Также: рассмотреть присоединение к нашему сообществу! Есть много библиотек, оставленных на инструмент. Вы можете найти нас на Github или сказать привет на Gitter Отказ
Оригинал: «https://dev.to/lightstep/opentelemetry-nodejs-all-you-need-to-know-1ngd»