dats

дата

Минималистичный клиент статистики UDP/TCP с нулевой зависимостью для Node.js

Бывают случаи, когда вам нужно собрать показатели, и вам нужно что-то простое, не написав слишком много шаблонов, dats вам на помощь!

Этот клиент стремится иметь простой API-интерфейс, совместимый со statsd, с некоторыми дополнительными вариантами для расширенного использования, например: буферизованные метрики и транспорты UDP/TCP!

Поддерживает Node.js >=14.0.0 . Если вы являетесь пользователем Node.js v12 обратитесь к [email protected] .

Содержание

• Установка
• Использование
  • Общий
  • Пространство имен с именем хоста/PID
  • TCP-клиент
• API
  • Client
    • new Client(options)
    • Client.close([cb])
    • Client.connect()
    • Client.counter(string[, value, sampling])
    • Client.timing(string, value[, sampling])
    • Client.gauge(string, value)
    • Client.set(string, value)
• Датс Мок
• Интерфейс командной строки
  • Использование интерфейса командной строки
  • датасрк
  • Предварительно скомпилированный двоичный файл
• Тесты
• Мощные приложения
• Поддержка и вклад
• Лицензия

Установка

Пакет доступен на npm.

Вы можете установить его с помощью npm

 # lastest stable version
$ npm i -S @immobiliarelabs/dats
# latest development version
$ npm i -S @immobiliarelabs/dats@next

или yarn

 # lastest stable version
$ yarn add @immobiliarelabs/dats
# latest development version
$ yarn @immobiliarelabs/dats@next

Использование

Общий

 import Client from '@immobiliarelabs/dats' ;

const stats = new Client ( {
    host : 'udp://someip:someport' ,
    namespace : 'myGrafanaNamespace' ,
    // Optionally register a global handler to track errors.
    onError : ( error ) => {
        processError ( error ) ;
    } ,
} ) ;

// Send counter (myGrafanaNamespace.some.toCount)
stats . counter ( 'some.toCount' , 3 ) ;
stats . counter ( 'some.toCount' ) ; // defaults to 1
stats . counter ( 'some.toCount' , 1 , 10 ) ; // set sampling to 10
// Send timing (myGrafanaNamespace.some.toTime)
stats . timing ( 'some.toTime' , 10 ) ;
stats . timing ( 'some.toTime' , 10 , 0.1 ) ; // set sampling to 0.1

// Send gauge (myGrafanaNamespace.some.toGauge)
stats . gauge ( 'some.toGauge' , 23 ) ;

// Send set (myGrafanaNamespace.some.set)
stats . set ( 'some.set' , 765 ) ;

Пространство имен с именем хоста/PID

 // Scope your stats per hostname and/or pid
import Client from '@immobiliarelabs/dats' ;

const stats = new Client ( {
    host : 'udp://someip:someport' ,
    namespace : 'myGrafanaNamespace.${hostname}.${pid}' ,
} ) ;

// Send counter (myGrafanaNamespace.myMachine.123.some.toCount)
stats . counter ( 'some.toCount' , 3 ) ;

Если имя хоста содержит какие-либо файлы . , клиент заменит их на _ .

TCP-клиент

 import Client from '@immobiliarelabs/dats' ;

// TCP usage
const stats = new Client ( {
    host : 'tcp://someip:someport' ,
    namespace : 'myGrafanaNamespace.${hostname}.${pid}' ,
} ) ;

// Calling connect is required in TCP environment
await stats . connect ( ) ;

// Send counter (myGrafanaNamespace.myMachine.123.some.toCount)
stats . counter ( 'some.toCount' , 3 ) ; 

API

Этот модуль экспортирует:

• Client

Client

Клиент статистики

new Client(options)

• options : объект конфигурации.
  • host : хост статистики ( udp://{ip}:{port} или tcp://{ip}:{port} ), вы также можете использовать ipv6. Если вы хотите принудительно использовать udp6, используйте: udp6://{host}:{port} , при использовании TCP вам необходимо вызвать метод Client.connect .
  • namespace : необязательно. Префикс, используемый для метрик. Метрика будет отправлена ​​как namespace. + метрическая строка. При желании вы можете использовать заполнители ${hostname} и ${pid} в пространстве имен и заменить их именем хоста компьютера и идентификатором процесса.
  • bufferSize : необязательно. По умолчанию — 0 . Установка этого значения на число больше нуля активирует режим буферизации, в котором вместо отправки метрик при каждом вызове они будут буферизоваться и отправляться при возникновении одного из следующих условий: буфер заполнен или истек срок действия bufferFlushTimeout . Использование этого подхода более производительно, но вы должны быть осторожны и использовать значение, совместимое с MTU, доступным в вашей сети, иначе ваши пакеты могут быть отброшены без уведомления. См. мультиметрические пакеты.
  • bufferFlushTimeout : необязательно. По умолчанию — 100 . Тайм-аут в миллисекундах перед очисткой буфера метрик.
  • debug : необязательно. debuglog('dats') . Функция логгера.
  • udpDnsCache : необязательно. По умолчанию правда. Активируйте поиск кэша DNS для udp.
  • udpDnsCacheTTL : необязательно. По умолчанию 120 . DNS-кеш Время жизни в секундах.
  • onError : Необязательно. По умолчанию (err) => void . Вызывается при возникновении ошибки. Позволяет проверять и отправлять ошибки.
  • customSocket : необязательно. По умолчанию null . Пользовательский сокет, используемый клиентом. Это функция для насмешки. Мы не рекомендуем использовать ее в рабочей среде.
  • tags : Необязательно. Значение по умолчанию — null . Если это предусмотрено, метрики будут включать теги в форме #key1:value1,key2:value2 .

Client.close([cb])

закрыть клиентский сокет

• cb : необязательно. Функция обратного вызова, вызываемая при закрытии сокета. Если cb не указан, возвращается Promise .

Возвращает : Promise , если cb не передано.

Client.connect()

подключите TCP-сокет. Вызов этой функции требуется только по TCP.

Возвращает : Promise .

Client.counter(string[, value, sampling])

отправить метрику типа счетчика

• string : метрическая строка
• value : Необязательно. Значение метрики ( Number ). По умолчанию 1 .
• sampling : Необязательно. Метрическая выборка.

Все ошибки отправки обрабатываются обратным вызовом onError .

Client.timing(string, value[, sampling])

отправить метрику времени типа

• string : метрическая строка
• value : значение метрики ( Number ).
• sampling : Необязательно. Метрическая выборка.

Все ошибки отправки обрабатываются обратным вызовом onError .

Client.gauge(string, value)

отправить метрику типа манометра

• string : метрическая строка
• value : значение метрики ( Number ).

Все ошибки отправки обрабатываются обратным вызовом onError .

Client.set(string, value)

отправить метрику набора типов

• string : метрическая строка
• value : значение метрики ( Number ).

Все ошибки отправки обрабатываются обратным вызовом onError .

Датс Мок

Датс экспортирует свой макет, вы можете использовать его следующим образом:

 import ClientMock from '@immobiliarelabs/dats/dist/mock' ;

const host = new URL ( `udp://127.0.0.1:8232` ) ;
const namespace = 'ns1' ;
const client = new ClientMock ( { host , namespace } ) ;

client . gauge ( 'some.metric' , 100 ) ;
client . set ( 'some.metric' , 100 ) ;
// metrics is an array with all metrics sent
console . log ( client . metrics ) ;
/* stdout:
    [
        'ns1.some.metric:100|g',
        'ns1.some.metric:100|s',
    ]
*/
// Check if a metric is in the metrics array
client . hasSent ( 'ns1.some.metric:100|s' ) ; // -> true
client . hasSent ( 'ns1.some.metric:10|s' ) ; // -> false
client . hasSent ( / ns1.some.metric:d+|s / ) ; // -> true
client . hasSent ( / ns1.some.test:d+|s / ) ; // -> false

// Clean the metrics array with
client . cleanMetrics ( ) ;
console . log ( client . metrics ) ;
/* stdout:
    []
*/ 

Интерфейс командной строки

dats также предоставляется как CLI, который можно установить как глобальный пакет npm, так и предварительно скомпилированный двоичный файл.

Бинарный файл прекомпиляции можно найти в разделе релизов для Linux, MacOS или Windows.

Использование интерфейса командной строки

$ npm i -g @immobiliarelabs/dats
dats --help
#   The following are required input flags:
#
#         --host {string} []
#         --port {string} []
#         --type {string} [Metric type can be one of: counter, timing, gauge, set]
#         --prefix {string} [Metric prefix]
#         --namespace {string} [Metric full namespace, use dots `.` to separate metrics]
#         --value {string} [Metric value]
#         --quiet {boolean} [Suppress all console output]
#         --dryRun {boolean} [Metric wont be sent, use for debug]
#
# If unsure of output run the command prepended with `DRY_RUN=1`

датасрк

Каждый флаг команды также можно указать в формате JSON в файле .datsrc , процесс во время выполнения будет искать его в текущем рабочем каталоге и объединять конфигурацию файла и флаги перед запуском!

{
    "host" : " 123.123.123.123 " ,
    "port" : " 1234 " ,
    "prefix" : " my_metric_prefix "
}

Предварительно скомпилированный двоичный файл

Если вы хотите использовать предварительно скомпилированный двоичный файл, получите правильную ссылку для вашей ОС в разделе выпуска и выполните следующие действия:

curl https://github.com/immobiliare/dats/releases/download/v{{VERSION_TAG}}/dats-cli-{{VERSION_OS}} -L -o dats-cli
chmod +x dats-cli
./dats-cli

Тесты

Автоматический тест для каждого коммита можно найти по следующим ссылкам: next и main.

Тесты проводились с использованием autocannon, указывающего на HTTP-сервер node.js, который отправляет при каждом запросе метрику счетчика. С помощью такого теста мы оцениваем, насколько библиотека влияет на производительность приложения.

Ниже приведены тесты с наиболее известными клиентами node.js statsd:

БИБЛИОТЕКА	Запрос/сек (97,5-й)	Запрос/сек (в среднем)
дата	45503	43174.4
горячие шишки	46975	43319.47
узел-statsd	14935	11632,34
statsd-клиент	42463	35790,67
База	50271	43312.54

База — это HTTP-сервер без метрик.

Мощные приложения

dats был создан замечательной командой Node.js из ImmobiliareLabs, технического отдела Immobiliare.it, компании по недвижимости №1 в Италии.

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

Если вы используете Dats в производстве, напишите нам сообщение .

Поддержка и вклад

Сделано с ❤️ авторами ImmobiliareLabs и участниками

Мы будем рады, если вы внесете свой вклад в развитие дат! Если у вас есть вопросы о том, как использовать данные, ошибки и улучшения, задайте их, открыв выпуск на GitHub.

Лицензия

dats лицензируется по лицензии MIT. Дополнительную информацию смотрите в файле LICENSE.