Antes de começar
- Ative as Análises para a sua equipe.
- Crie uma chave de API de projeto com
sessions:read, ou uma chave de API da organização com o mesmo escopo para todos os projetos. Tokens de cliente não podem ler métricas de análises. - Instale uma distribuição do OpenTelemetry Collector
que inclua o receiver do Prometheus
e o exporter OTLP HTTP.
A distribuição Contrib inclui os dois. Confira os componentes disponíveis com
otelcol-contrib components. - Obtenha a URL base OTLP HTTP e o cabeçalho de autorização do seu backend de telemetria. Essa credencial é separada da sua chave de API da Polymorfa.
Conectar o OpenTelemetry
1
Copie a configuração do seu escopo
Em Análises, escolha um projeto no cabeçalho do Console e use
Todos os números para selecionar um número ou manter a visualização combinada.
Abra … → Conectar um coletor.Escolha um Período móvel de 1, 24 ou 168 horas. Ative
Incluir comparações de mensagens e público se você precisar dessas dimensões.
Selecione Copiar configuração e salve o YAML como
collector.yaml.
Ele contém o escopo selecionado e o endereço da API do ambiente do seu Console.
O período do coletor é independente das datas do calendário da página.2
Informe as credenciais e o destino
Monte um arquivo que contenha apenas a sua chave de API da Polymorfa em
/run/secrets/polymorfa_key. O usuário que executa o coletor precisa de acesso
de leitura a esse arquivo. Mantenha a chave fora do collector.yaml.Defina estas variáveis de ambiente no serviço ou contêiner do coletor:O exporter acrescenta
/v1/metrics ao OTLP_ENDPOINT. Se o seu provedor
fornecer uma URL completa de métricas, substitua endpoint por metrics_endpoint
no YAML. Para um backend sem autenticação, remova o bloco
headers e omita OTLP_AUTHORIZATION.3
Valide e inicie o coletor
Execute estes comandos com o mesmo ambiente e as mesmas montagens de arquivo do serviço do coletor:A configuração gerada dá ao exporter HTTP o nome
otlphttp. Se a sua
distribuição listar otlp_http, use esse nome em exporters
e em service.pipelines.metrics.exporters. Um erro de componente desconhecido significa
que a distribuição não tem um componente necessário ou usa outro nome de componente.Configure uma instância do coletor por job de coleta. Várias instâncias buscando
o mesmo escopo enviam observações duplicadas para o seu backend.4
Confira as primeiras medições
Depois do primeiro minuto, procure
polymorfa_analytics_enabled no seu backend.
Um valor 1 confirma que a exportação leu as Análises ativadas. Confira
polymorfa_analytics_window_end_timestamp_seconds para o limite da medição
e polymorfa_analytics_generated_timestamp_seconds para o horário da coleta.O receiver também informa a saúde da coleta do Prometheus por up para o
job polymorfa_analytics. Um valor 0 indica uma coleta com falha; confira os
logs do coletor. Erros de exportação depois de uma coleta bem-sucedida apontam para a URL,
a autorização ou a conectividade do seu backend. A falta de métricas de negócio depois de uma
coleta bem-sucedida significa que as medições delas estão ausentes, não que são zero.Exemplo de configuração
Este exemplo lê todos os números de um projeto. SubstituaPROJECT_ID, forneça
o arquivo da chave e as variáveis de ambiente acima e valide a configuração com o seu coletor.
Use a configuração gerada pelo Console para incluir um filtro de número ou o escopo da organização.
collector.yaml
Usar o Prometheus diretamente
Copie o job emreceivers.prometheus.config.scrape_configs para a lista
scrape_configs da sua configuração do Prometheus. Monte o mesmo arquivo de chave.
As seções exporters e service pertencem ao OpenTelemetry e ficam de fora
da configuração do Prometheus.
Use format: [openmetrics] para solicitar o texto OpenMetrics 1.0 em vez do texto
Prometheus 0.0.4. A resposta inclui o Content-Type e o marcador de fim obrigatório.
format seleciona a representação.
Escolher o escopo e o período
Use um nome de job de coleta separado para cada escopo/período que você coletar. Todas as
amostras de número carregam
project_id e number_id. As amostras de todo o escopo carregam scope e
project_id; as contagens de requisições de API continuam valendo para toda a equipe/projeto quando você seleciona um número.
Nomes, números de telefone, contatos, corpos de mensagens e participantes de chamadas não aparecem.
O período usa horas completas para que os intervalos de mensagens e as janelas de chamadas fiquem alinhados.
O status de conexão descreve o número no momento da leitura. As filas de respostas e a atividade
do celular têm os próprios horários de observação; eles podem ser mais antigos que uma coleta.
Para intervalos históricos exatos e comparações de tempo, use a
API JSON de Análises.
O que você recebe
Todo nome de métrica começa compolymorfa_analytics_.
Consultar os gauges corretamente
Estes são gauges por período, incluindo as métricas de contagem. Coletas repetidas observam períodos sobrepostos. Não userate() nem increase(), nem some amostras
ao longo do tempo para contar eventos.
Para uma proporção de leitura da frota, divida a soma das leituras pela soma das conversas
concluídas, filtrando pela cobertura de engajamento completa:
dimension; somar dimensões diferentes conta a mesma atividade várias vezes.
Todas as durações usam segundos e todas as proporções usam 0–1. Medições ausentes e proporções
nulas são omitidas. Um zero informado é um valor medido, não um substituto para
dados ausentes. As contagens de chamadas podem ser zero quando não existem chamadas retidas e atribuíveis.
Nunca some nem tire a média de percentis por número para produzir um percentil da frota.
Desativar ou solucionar problemas
Desativar as Análises interrompe as exportações de negócio. A partir daí, as coletas bem-sucedidas contêm apenasenabled=0 e os timestamps de período/geração. Isso não exclui os dados já enviados
ao seu backend de telemetria nem altera a retenção de Chamadas.
Um escopo ausente ou um token de cliente retorna 403. Um projeto ou número inacessível
retorna 404. Filtros inválidos retornam 400. Um tempo limite de consulta de análises retorna
503 sem métricas parciais; reduza o período ou tente novamente mais tarde. Autenticação,
revogação de credenciais e limites de taxa da API também se aplicam às coletas. As coletas com falha
retornam uma resposta de erro da API; elas nunca substituem a medição por zeros.
Consulte a referência de exportação da equipe
e a referência de exportação do projeto.
Enviar retratos JSON por hora
Consulte Destinos para a configuração compartilhada e os controles de entrega. Para um endpoint de ingestão personalizado, abra Configurações do projeto → Destinos → Adicionar destino → Análises. Um proprietário ou administrador da equipe seleciona todos os números desse projeto ou um único número, um período móvel de 1, 24 ou 168 horas e um destino HTTPS público. A ação Destinos de análises nas Análises abre o mesmo fluxo com o número selecionado. As Análises precisam estar ativadas para a equipe antes que você ative um destino de análises. Novos retratos são preparados a cada hora para a hora UTC concluída mais recente. Cada registro entregue contém as análises agregadas de um número:
O POST HTTPS usa o envelope, as assinaturas, as novas tentativas e os cabeçalhos de deduplicação dos destinos. O corpo é JSON da Polymorfa, então o destino precisa de um receptor para esse schema. Use o receiver do Prometheus acima ao coletar métricas OTLP.
Os períodos móveis se sobrepõem. Trate cada retrato como uma observação de um período; somar retratos sucessivos de 24 horas conta a atividade em dobro. As regras de amostragem de logs não fazem amostragem desses agregados. Pausar interrompe novos retratos e os claims de entrega; retomar envia os registros elegíveis na fila e prepara o período mais recente sem preencher todas as horas puladas.
Desativar as Análises exclui os retratos de análises na fila e interrompe a nova coleta. Uma entrega em andamento pode terminar. Os dados já aceitos pelo seu endpoint seguem a sua própria política de retenção. Reativar inicia um novo período de consentimento; retratos antigos na fila não podem voltar.
Intervalos do celular e NDJSON
A exportação de métricas incluiphone_interval_average_seconds{kind="activity|quiet"}
e phone_interval_seconds{kind="activity|quiet"}. O gauge account_activity
inclui as contagens de amostras completed_phone_activity_periods e phone_quiet_gaps.
São gauges de período móvel para períodos de atividade e intervalos concluídos e observados,
não contadores nem medições online/offline do celular. Uma amostra ausente deixa a
média ausente. Use as definições das medições
ao comparar intervalos.
Os destinos de análises aceitam JSON ou NDJSON. O NDJSON envia um envelope
{version, deliveryId, record} terminado por quebra de linha, usando application/x-ndjson. O JSON mantém
o envelope {version, deliveryId, records}. O segredo de assinatura gerado e a
verificação de assinatura valem para os dois;
verifique os bytes exatos, incluindo a quebra de linha final do NDJSON.
Plataformas estimadas e cobertura de dispositivos próprios
Os gauges de dispositivos por período incluem:
Esses valores são gauges do período móvel, não contadores cumulativos. Não aplique o
rate() de contadores às contagens de mensagens. Os rótulos nunca incluem identificadores de destinatários nem índices de dispositivos individuais. As plataformas baseadas em prefixo são estimativas, e Desconhecido continua sendo uma categoria. Use JSON com escopo ou um destino de análises para linhas de conversa conjuntas e observações individuais de dispositivos próprios; o coletor não expande as linhas conjuntas em rótulos de métrica de alta cardinalidade.
Gauges de atividade dos destinatários
Comsegments=true, a atividade medida dos destinatários adiciona estes gauges de período móvel:
Os gauges de sinais e de tempo adicionam os rótulos
recipient_country, recipient_device_count e
device_source ao escopo de número/projeto. As horas com as mesmas dimensões
são combinadas em uma amostra por coleta. As categorias de país/quantidade incluem Desconhecido.
A presença não identifica um dispositivo principal ou vinculado. Os dois gauges de cobertura
continuam disponíveis quando segments=false.
As contagens incluem vários recibos de dispositivos para uma mesma mensagem. Esses valores são gauges,
não contadores: não use rate() nem increase(). Use JSON com escopo ou um destino de análises
JSON/NDJSON para linhas por hora. A entrega não estabelece uma leitura, e os intervalos
sem sinais não estabelecem tempo offline. Consulte as definições das medições.