dats

dados

Cliente de estatísticas UDP/TCP minimalista e sem dependência para Node.js

Há momentos em que você precisa coletar métricas e deseja algo simples, sem escrever muitos clichês, dats para ajudá-lo!

Este cliente pretende ter uma API simples compatível com statsd com algum tipo opcional para uso avançado, como: métricas em buffer e transportes UDP/TCP!

Suporta Node.js >=14.0.0 , se você for um usuário do Node.js v12 consulte [email protected] .

Índice

• Instalação
• Uso
  • Genérico
  • Namespace com nome de host/PID
  • Cliente 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)
• Simulação de dados
• Interface CLI
  • Uso CLI
  • dadosrc
  • Binário pré-compilado
• Referências
• Aplicativos avançados
• Apoie e contribua
• Licença

Instalação

O pacote está disponível em npm.

Você pode instalá-lo com 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

Uso

Genérico

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

Namespace com nome de host/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 ) ;

Se o nome do host contiver algum arquivo . , o cliente os substituirá por _ .

Cliente 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

Este módulo exporta:

• Client

Client

O cliente statsd

new Client(options)

• options : objeto de configuração.
  • host : statsd host ( udp://{ip}:{port} ou tcp://{ip}:{port} ), você também pode usar ipv6. Se você deseja forçar o uso do udp6: udp6://{host}:{port} , ao usar TCP, você deve chamar o método Client.connect .
  • namespace : opcional. Prefixo a ser usado para as métricas. A métrica será enviada como namespace. + a string métrica. Opcionalmente, você pode usar os espaços reservados ${hostname} e ${pid} no namespace e substituí-los pelo nome do host da máquina e pelo ID do processo.
  • bufferSize : Opcional. O padrão é 0 . Definir este valor para um número maior que zero ativará o modo buffer, que em vez de enviar métricas em cada chamada, irá armazená-las e enviá-las quando ocorrer uma destas condições: o buffer está cheio ou o bufferFlushTimeout expirou. Usar essa abordagem tem melhor desempenho, mas você deve ter cuidado ao usar um valor compatível com o MTU disponível em sua rede, caso contrário, seus pacotes poderão ser descartados silenciosamente. Consulte pacotes multimétricos.
  • bufferFlushTimeout : opcional. O padrão é 100 . Tempo limite em milissegundos para esperar antes de liberar o buffer de métricas.
  • debug : opcional. debuglog('dats') . A função de registrador.
  • udpDnsCache : Opcional. Padrão verdadeiro. Ative a pesquisa DNS do cache para udp.
  • udpDnsCacheTTL : Opcional. Padrão 120 . Cache DNS Tempo de vida em segundos.
  • onError : Opcional. Padrão (err) => void . Chamado quando há um erro. Permite verificar também erros de envio.
  • customSocket : Opcional. Padrão null . Soquete customizado utilizado pelo cliente, este é um recurso para mock não recomendamos seu uso em produção.
  • tags : Opcional Padrão null . Se fornecidas, as métricas incluirão tags no formato #key1:value1,key2:value2 .

Client.close([cb])

feche o soquete do cliente

• cb : opcional. Uma função de retorno de chamada a ser chamada quando o soquete estiver fechado. Se nenhum cb for fornecido, uma Promise será retornada.

Retorna : uma Promise se nenhum cb for aprovado.

Client.connect()

conecte o soquete TCP. Chamar esta função é necessário apenas em TCP.

Retorno : uma Promise .

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

envie uma métrica do tipo contador

• string : a string métrica
• value : opcional. O valor da métrica ( Number ). O padrão é 1 .
• sampling : Opcional. A amostragem métrica.

Todos os erros de envio são tratados pelo retorno de chamada onError .

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

envie uma métrica do tipo timing

• string : a string métrica
• value : o valor da métrica ( Number ).
• sampling : Opcional. A amostragem métrica.

Todos os erros de envio são tratados pelo retorno de chamada onError .

Client.gauge(string, value)

envie uma métrica do tipo medidor

• string : a string métrica
• value : o valor da métrica ( Number ).

Todos os erros de envio são tratados pelo retorno de chamada onError .

Client.set(string, value)

envie uma métrica do tipo set

• string : a string métrica
• value : O valor da métrica ( Number ).

Todos os erros de envio são tratados pelo retorno de chamada onError .

Simulação de dados

Dats exporta seu mock, você pode usá-lo da seguinte maneira:

 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 também é exposto como uma CLI que pode ser instalada como um pacote global npm ou um binário pré-compilado.

O binário pré-compilado pode ser encontrado na seção de lançamento para Linux, MacOS ou Windows.

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

dadosrc

Cada sinalizador de comando também pode ser especificado no formato JSON no arquivo .datsrc , o processo em tempo de execução irá pesquisá-lo no diretório de trabalho atual e mesclar a configuração e os sinalizadores do arquivo antes de executar!

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

Binário pré-compilado

Se você quiser usar o binário pré-compilado, obtenha o link correto para o seu sistema operacional na seção de lançamento e faça o seguinte:

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

Referências

O benchmarking automático para cada commit pode ser encontrado nos seguintes links: next e main.

Os testes foram feitos utilizando autocannon apontando para um servidor HTTP node.js que envia a cada solicitação uma métrica de contagem. Com esse tipo de teste avaliamos o quanto a biblioteca influencia no desempenho da aplicação.

Abaixo estão relatados os benchmarks com os clientes statsd node.js mais famosos:

BIBLIOTECA	Necessidade/seg (97,5º)	Necessidade/seg (média)
dados	45503	43174.4
tiros quentes	46975	43319,47
estatísticas do nó	14935	11632,34
cliente-statsd	42463	35790,67
Base	50271	43312,54

Base é o servidor HTTP sem métricas.

Aplicativos avançados

dats foi criado pela incrível equipe Node.js da ImmobiliareLabs, o departamento de tecnologia da Immobiliare.it, a empresa imobiliária número 1 na Itália.

Atualmente, estamos usando dados em nossos produtos, bem como em nossas ferramentas internas.

Se você estiver usando dats em produção, envie-nos uma mensagem .

Apoie e contribua

Feito com ❤️ por ImmobiliareLabs & Contributors

Adoraríamos que você contribuísse para o dats! Se você tiver alguma dúvida sobre como usar dats, bugs e melhorias, sinta-se à vontade para entrar em contato abrindo um problema no GitHub.

Licença

dats é licenciado sob a licença do MIT. Consulte o arquivo LICENSE para obter mais informações.