dats

dates

Client de statistiques UDP/TCP minimaliste sans dépendances pour Node.js

Il y a des moments où vous devez rassembler des métriques et vous voulez quelque chose de simple sans écrire trop de passe-partout, dats à votre aide !

Ce client vise à disposer d'une API simple conforme à statsd avec des options facultatives pour une utilisation avancée, comme : des métriques mises en mémoire tampon et des transports UDP/TCP !

Prend en charge Node.js >=14.0.0 , si vous êtes un utilisateur Node.js v12 reportez-vous à [email protected] .

Table des matières

• Installation
• Usage
  • Générique
  • Espace de noms avec nom d'hôte/PID
  • Client 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)
• Dats Mock
• Interface CLI
  • Utilisation de la CLI
  • datsrc
  • Binaire précompilé
• Repères
• Applications optimisées
• Soutenir et contribuer
• Licence

Installation

Le package est disponible sur npm.

Vous pouvez l'installer avec npm

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

ou yarn

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

Usage

Générique

 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 ) ;

Espace de noms avec nom d'hôte/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 ) ;

Si le nom d'hôte contient des fichiers . , le client les remplacera par _ .

Client 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

Ce module exporte :

• Client

Client

Le client statistiques

new Client(options)

• options : objet de configuration.
  • host : statsd host ( udp://{ip}:{port} ou tcp://{ip}:{port} ), vous pouvez également utiliser ipv6. Si vous souhaitez forcer l'utilisation de udp6, utilisez : udp6://{host}:{port} , lorsque vous utilisez TCP, vous devez appeler la méthode Client.connect .
  • namespace : facultatif. Préfixe à utiliser pour les métriques. La métrique sera envoyée sous forme namespace. + la chaîne métrique. Vous pouvez éventuellement utiliser des espaces réservés ${hostname} et ${pid} dans l'espace de noms et les remplacer par le nom d'hôte de la machine et l'ID du processus.
  • bufferSize : Facultatif. La valeur par défaut est 0 . Définir cette valeur sur un nombre supérieur à zéro activera le mode tamponné qui, au lieu d'envoyer des métriques à chaque appel, les mettra en tampon et les enverra lorsque l'une de ces conditions se produit : le tampon est plein ou le bufferFlushTimeout a expiré. Utiliser cette approche est plus performante, mais vous devez faire attention à utiliser une valeur compatible avec la MTU disponible sur votre réseau, sinon vos paquets pourraient être abandonnés silencieusement. Voir paquets multi-métriques.
  • bufferFlushTimeout : facultatif. La valeur par défaut est 100 . Délai d'attente en millisecondes avant de vider le tampon des métriques.
  • debug : facultatif. debuglog('dats') par défaut. La fonction enregistreur.
  • udpDnsCache : facultatif. Vrai par défaut. Activez la recherche DNS du cache pour udp.
  • udpDnsCacheTTL : facultatif. Par défaut 120 . Cache DNS Durée de vie en secondes.
  • onError : facultatif. Par défaut (err) => void . Appelé en cas d'erreur. Vous permet de vérifier également les erreurs d'envoi.
  • customSocket : facultatif. null par défaut. Socket personnalisé utilisé par le client, il s'agit d'une fonctionnalité de moquerie que nous déconseillons de l'utiliser en production.
  • tags : facultatif, valeur null par défaut. Si elles sont fournies, les métriques incluront des balises au format #key1:value1,key2:value2 .

Client.close([cb])

fermez le socket client

• cb : facultatif. Une fonction de rappel à appeler lorsque le socket est fermé. Si aucune cb n’est fournie, une Promise est retournée.

Renvoie : une Promise si aucun cb n'est passé.

Client.connect()

connectez le socket TCP. L'appel de cette fonction n'est requis que sur TCP.

Retours : une Promise .

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

envoyer une métrique de type compteur

• string : La chaîne métrique
• value : Facultatif. La valeur métrique ( Number ). La valeur par défaut est 1 .
• sampling : Facultatif. L'échantillonnage métrique.

Toutes les erreurs d'envoi sont gérées par le rappel onError .

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

envoyer une métrique de type timing

• string : La chaîne métrique
• value : La valeur métrique ( Number ).
• sampling : Facultatif. L'échantillonnage métrique.

Toutes les erreurs d'envoi sont gérées par le rappel onError .

Client.gauge(string, value)

envoyer une métrique de type jauge

• string : La chaîne métrique
• value : La valeur métrique ( Number ).

Toutes les erreurs d'envoi sont gérées par le rappel onError .

Client.set(string, value)

envoyer une métrique de type set

• string : La chaîne métrique
• value : La valeur métrique ( Number ).

Toutes les erreurs d'envoi sont gérées par le rappel onError .

Dats Mock

Dats exporte sa maquette, vous pouvez l'utiliser comme suit :

 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:
    []
*/ 

Interface CLI

dats est également exposé en tant que CLI qui peut être installé à la fois en tant que package global npm ou en tant que binaire précompilé.

Le binaire de précompilation se trouve dans la section des versions pour Linux, MacOS ou Windows.

Utilisation de la CLI

$ 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`

datsrc

Chaque indicateur de commande peut également être spécifié au format JSON dans le fichier .datsrc , le processus au moment de l'exécution le recherchera dans le répertoire de travail actuel et fusionnera à la fois la configuration du fichier et les indicateurs avant de s'exécuter !

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

Binaire précompilé

Si vous souhaitez utiliser le binaire précompilé, obtenez le lien correct pour votre système d'exploitation dans la section des versions et procédez comme suit :

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

Repères

L'analyse comparative automatique pour chaque commit peut être trouvée sur les liens suivants : next et main.

Les tests ont été effectués à l'aide d'un canon automatique pointant vers un serveur HTTP node.js qui envoie à chaque requête une métrique de comptage. Avec ce genre de test, nous évaluons à quel point la bibliothèque influence les performances de l'application.

Vous trouverez ci-dessous les benchmarks avec les clients node.js statsd les plus connus :

BIBLIOTHÈQUE	Requête/Sec (97,5ème)	Req/Sec (moy.)
dates	45503	43174.4
coups chauds	46975	43319.47
nœud-statistiques	14935	11632.34
client statsd	42463	35790.67
Base	50271	43312.54

Base est le serveur HTTP sans métriques.

Applications optimisées

dats a été créé par l'incroyable équipe Node.js d'ImmobiliareLabs, le département technique d'Immobiliare.it, la société immobilière n°1 en Italie.

Nous utilisons actuellement des données dans nos produits ainsi que dans nos outils internes.

Si vous utilisez des données en production, envoyez-nous un message .

Soutenir et contribuer

Réalisé avec ❤️ par ImmobiliareLabs & Contributeurs

Nous serions ravis que vous contribuiez à dats ! Si vous avez des questions sur l'utilisation des données, des bugs et des améliorations, n'hésitez pas à nous contacter en ouvrant un problème GitHub.

Licence

dats est sous licence MIT. Voir le fichier LICENSE pour plus d'informations.