API de métricas

O servidor CPqD ASR disponibiliza um conjunto de métricas relacionadas ao reconhecimento de fala que podem ser acessadas através de duas interfaces: HTTP e JMX. Através dessas métricas, combinadas com métricas que podem ser coletadas do próprio sistema operacional (CPU, memória, I/O, etc.), o administrador pode avaliar o nível de utilização e desempenho do sistema.

Aviso

Embora várias métricas sejam retornadas pelo CPqD ASR, apenas um certo conjunto deve ser considerado para a monitoração do reconhecimento de fala. As métricas não apresentadas aqui não devem ser usadas. Algumas delas ainda estão em desenvolvimento e podem ser modificadas ou até removidas. Outras métricas são internas e não estão diretamente relacionadas ao ASR.

Há os seguintes tipos de métrica:

Contador
Valor que pode ser incrementado ou subtraído (ex. Número requisições processadas).
Histograma
Mede a distribuição estatística em uma sequência de valores. Temos o valor máximo, mínimo, média e desvio padrão, além de quantis. A medida corresponde às amostras mais recentes, dentro de uma janela de aproximadamente 5 min. Essa janela move-se apenas quando ocorrem novas amostras, e não considera o tempo em si.
Timer
Taxa de execução de uma função e a distribuição da duração.
Gauge
Valor instantâneo de uma medida qualquer.
Meter
Mede a taxa de ocorrência de um evento em um intervalo de tempo. Registra a taxa média em uma janela de tempo móvel (-1, -5, -15 minutos). Essa janela move-se apenas quando existem novas amostras, e não considera o tempo em si.

Métricas ASR

Sessões de reconhecimento

gauges/br.com.cpqd.asr.session.open
Número de sessões de reconhecimento em andamento (abertas).
timers/br.com.cpqd.asr.session.duration
Histograma da duração da sessão e taxa de criação de sessões.

Requisições de reconhecimento

gauges/br.com.cpqd.asr.recognition.active
Número de reconhecimentos em andamento. Atualmente, corresponde ao número de canais em uso da licença.
counters/br.com.cpqd.asr.recognition.requests
Valor acumulado da quantidade total de requisições de reconhecimento realizadas até o momento.

Áudio de entrada

counters/br.com.cpqd.asr.engine.audio.duration
Valor acumulado da duração do áudio de entrada em milissegundos.
counters/br.com.cpqd.asr.engine.speech.duration
Valor acumulado do tempo de fala no áudio de entrada em milissegundos.

Tempo de reconhecimento

counters/br.com.cpqd.asr.engine.recognition.time
Valor acumulado do tempo de reconhecimento em milissegundos.
histograms/br.com.cpqd.asr.recognition.time
Histograma do tempo de reconhecimento em milissegundos.

RTF do reconhecimento

histograms/br.com.cpqd.asr.engine.rtf100.grammar
Histograma do valor percentual de RTF para gramáticas. Um valor indicado aqui como 80, corresponde a um RTF=0.8.
histograms/br.com.cpqd.asr.engine.rtf100.slm
Histograma do valor percentual de RTF para modelos de fala livre. Um valor indicado aqui como 120, corresponde a um RTF=1.2.

Resultado do reconhecimento

counters/br.com.cpqd.asr.recognition.result.RECOGNIZED
Valor acumulado da quantidade de requisições de reconhecimento finalizadas com sucesso, ou seja, com uma frase reconhecida. Reconhecimento com sucesso não significa «resultado correto».
counters/br.com.cpqd.asr.recognition.result.CANCELED
Valor acumulado da quantidade de requisições de reconhecimento que foram «canceladas».
counters/br.com.cpqd.asr.recognition.result.ERR_MAX_LICENSES
Valor acumulado da quantidade de requisições de reconhecimento rejeitadas por ultrapassar o limite máximo de canais da licença.
counters/br.com.cpqd.asr.recognition.result.FAILURE
Valor acumulado da quantidade de requisições de reconhecimento finalizadas com «falha».
counters/br.com.cpqd.asr.recognition.result.MAX_SPEECH
Valor acumulado da quantidade de requisições de reconhecimento finalizadas porque ultrapassaram o limite interno máximmo de fala.
counters/br.com.cpqd.asr.recognition.result.NO_INPUT_TIMEOUT
Valor acumulado da quantidade de requisições de reconhecimento finalizadas porque o sistema não detectou fala por um tempo maior que o limite (parâmetro noInputTimeout.value).
counters/br.com.cpqd.asr.recognition.result.NO_MATCH
Valor acumulado da quantidade de requisições de reconhecimento finalizadas porque o sistema não conseguiu reconhecer o áudio de entrada ou o índice de confiança ficou abaixo do limiar (parâmetro decoder.confidenceThreshold).
counters/br.com.cpqd.asr.recognition.result.NO_SPEECH
Valor acumulado da quantidade de requisições de reconhecimento finalizadas porque o sistema não detectou fala no áudio de entrada.
counters/br.com.cpqd.asr.recognition.result.RECOGNITION_TIMEOUT
Valor acumulado da quantidade de requisições de reconhecimento finalizadas porque o sistema não realizou o reconhecimento dentro do limite de tempo configurado (parâmetro recognitionTimeout.value).

Interface HTTP

Através da interface HTTP, as métricas do ASR podem ser lidas enviando uma requisição HTTP GET para a URL http://ASR_HOST:8081/metrics, onde ASR_HOST é o IP do Servidor ASR desejado. Para exemplificar, abra um console na máquina do Servidor ASR e execute o comando abaixo:

curl http://localhost:8081/metrics?pretty=true

O resultado deve ser similar ao seguinte (removemos linhas não relevantes para simplificar o exemplo):

$ curl http://localhost:8081/metrics?pretty=true

{
  "gauges" : {
    "br.com.cpqd.asr.recognition.active" : {
      "value" : 0
    },
    "br.com.cpqd.asr.session.open" : {
      "value" : 0
    },
  },
  "counters" : {
    "br.com.cpqd.asr.engine.audio.duration" : {
      "count" : 0
    },
    "br.com.cpqd.asr.engine.recognition.time" : {
      "count" : 0
    },
    "br.com.cpqd.asr.engine.speech.duration" : {
      "count" : 0
    },
    "br.com.cpqd.asr.recognition.requests" : {
      "count" : 0
    },
    "br.com.cpqd.asr.recognition.result.CANCELED" : {
      "count" : 0
    },
    "br.com.cpqd.asr.recognition.result.ERR_MAX_LICENSES" : {
      "count" : 0
    },
    "br.com.cpqd.asr.recognition.result.FAILURE" : {
      "count" : 0
    },
    "br.com.cpqd.asr.recognition.result.MAX_SPEECH" : {
      "count" : 0
    },
    "br.com.cpqd.asr.recognition.result.NO_INPUT_TIMEOUT" : {
      "count" : 0
    },
    "br.com.cpqd.asr.recognition.result.NO_MATCH" : {
      "count" : 0
    },
    "br.com.cpqd.asr.recognition.result.NO_SPEECH" : {
      "count" : 0
    },
    "br.com.cpqd.asr.recognition.result.RECOGNITION_TIMEOUT" : {
      "count" : 0
    },
    "br.com.cpqd.asr.recognition.result.RECOGNIZED" : {
      "count" : 0
    },
  },
  "histograms" : {
    "br.com.cpqd.asr.engine.rtf100.grammar" : {
      "count" : 0,
      "max" : 0,
      "mean" : 0.0,
      "min" : 0,
      "p50" : 0.0,
      "p75" : 0.0,
      "p95" : 0.0,
      "p98" : 0.0,
      "p99" : 0.0,
      "p999" : 0.0,
      "stddev" : 0.0
    },
    "br.com.cpqd.asr.engine.rtf100.slm" : {
      "count" : 0,
      "max" : 0,
      "mean" : 0.0,
      "min" : 0,
      "p50" : 0.0,
      "p75" : 0.0,
      "p95" : 0.0,
      "p98" : 0.0,
      "p99" : 0.0,
      "p999" : 0.0,
      "stddev" : 0.0
    },
    "br.com.cpqd.asr.recognition.time" : {
      "count" : 0,
      "max" : 0,
      "mean" : 0.0,
      "min" : 0,
      "p50" : 0.0,
      "p75" : 0.0,
      "p95" : 0.0,
      "p98" : 0.0,
      "p99" : 0.0,
      "p999" : 0.0,
      "stddev" : 0.0
    }
  },
  "timers" : {
    "br.com.cpqd.asr.session.duration" : {
      "count" : 0,
      "max" : 0.0,
      "mean" : 0.0,
      "min" : 0.0,
      "p50" : 0.0,
      "p75" : 0.0,
      "p95" : 0.0,
      "p98" : 0.0,
      "p99" : 0.0,
      "p999" : 0.0,
      "stddev" : 0.0,
      "m15_rate" : 0.0,
      "m1_rate" : 0.0,
      "m5_rate" : 0.0,
      "mean_rate" : 0.0,
      "duration_units" : "seconds",
      "rate_units" : "calls/second"
    },
  }
}

Interface JMX

As métricas apresentadas podem ser lidas através da interface JMX usando a porta 9999. Por padrão, o servidor CPqD ASR vem com a interface JXM desabilitada. Habilite a interface JMX seguindo as instruções:

  1. Defina a variável ASR_JMX_ENABLED=true através do comando systemctl set-environment
  2. Confira a variável configurada através do comando systemctl show-environment
  3. Reinicie o servidor ASR

Veja o exemplo seguinte:

$ systemctl set-environment ASR_JMX_ENABLED=true

$ systemctl show-environment

ASR_JMX_ENABLED=true
LANG=en_US.UTF-8
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin

$ systemctl restart asr-server

Verifique se o servidor ASR foi iniciado com sucesso e observe a presença da configuração para acesso JMX, conforme mostrado no exemplo abaixo:

$ systemctl status asr-server

● asr-server.service - CPqD Speech Recognition Server
   Loaded: loaded (/usr/lib/systemd/system/asr-server.service; disabled; vendor preset: disabled)
   Active: active (running) since Fri 2018-06-15 20:24:24 UTC; 7s ago
     Docs: https://speechweb.cpqd.com.br/asr/docs/latest
 Main PID: 1320 (java)
   CGroup: /docker/a6645a54c667c4bf2d7e49d08e80ddc60fad1383cc2e698740a967cc135fe91f/system.slice/asr-server.service
           └─1320 java -Xms128m -Xmx256m -XX:MaxDirectMemorySize=512m -XX:ErrorFile=/var/log/cpqd/asr/server/hs_err_pid%p.log
            -Dcom.sun.management.jmxremote.port=9999 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.m...

Jun 15 20:24:24 a6645a54c667 systemd[1]: Started CPqD Speech Recognition Server.
Jun 15 20:24:24 a6645a54c667 systemd[1]: Starting CPqD Speech Recognition Server...
Jun 15 20:24:24 a6645a54c667 start-server[1320]: Starting process asr-server...

Teste o acesso JMX a partir de uma máquina com Java (Oracle) instalado através da ferramenta VisualVM, com o comando jvisualvm --openjmx HOST_IP:9999, onde HOST_IP é o IP do servidor CPqD ASR. A Fig. 7 mostra a tela de consulta aos MBeans.

../_images/visualvm-jmx.png

Fig. 7 Acesso JMX através da ferramenta VisualVM

Problemas na conexão JMX

Algumas vezes o Java pode não identificar corretamente o IP da máquina e a conexão JMX resulta em erro (Cannot connect to ... using service:jmx:rmi ...). Neste caso, efetue a configuração do IP através do comando seguinte. Substitua HOST_IP pelo IP correto da máquina com o servidor CPqD ASR. Lembre de reiniciar o servidor ASR depois da configuração.

systemctl set-environment ASR_JMX_OPTS="-Dcom.sun.management.jmxremote.port=9999 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=HOST_IP"