Conectar um coletor de análises
Leia métricas de engajamento, conexão e chamadas dos números com Prometheus ou OpenTelemetry.
Envie medições de engajamento, conexão, respostas e chamadas para o seu backend de telemetria. Um coletor busca as métricas na Polymorfa uma vez por minuto e depois as exporta por OTLP sobre HTTP.
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 equipe 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#
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.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 docollector.yaml.Defina estas variáveis de ambiente no serviço ou contêiner do coletor:
Variável Valor OTLP_ENDPOINTA URL base OTLP HTTP do seu backend, como https://telemetry.example.com:4318OTLP_AUTHORIZATIONO valor completo do cabeçalho exigido pelo seu backend, como Bearer YOUR_BACKEND_TOKENO exporter acrescenta
/v1/metricsaoOTLP_ENDPOINT. Se o seu provedor fornecer uma URL completa de métricas, substituaendpointpormetrics_endpointno YAML. Para um backend sem autenticação, remova o blocoheaderse omitaOTLP_AUTHORIZATION.Valide e inicie o coletor
Execute estes comandos com o mesmo ambiente e as mesmas montagens de arquivo do serviço do coletor:
Shell otelcol-contrib validate --config=collector.yaml otelcol-contrib --config=collector.yamlA configuração gerada dá ao exporter HTTP o nome
otlphttp. Se a sua distribuição listarotlp_http, use esse nome emexporterse emservice.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.
Confira as primeiras medições
Depois do primeiro minuto, procure
polymorfa_analytics_enabledno seu backend. Um valor1confirma que a exportação leu as Análises ativadas. Confirapolymorfa_analytics_window_end_timestamp_secondspara o limite da medição epolymorfa_analytics_generated_timestamp_secondspara o horário da coleta.O receiver também informa a saúde da coleta do Prometheus por
uppara o jobpolymorfa_analytics. Um valor0indica 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. Substitua PROJECT_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 equipe.
receivers:
prometheus:
config:
scrape_configs:
- job_name: polymorfa_analytics
scrape_interval: 60s
scrape_timeout: 20s
scheme: https
metrics_path: /platform/projects/PROJECT_ID/analytics/metrics
authorization:
type: Bearer
credentials_file: /run/secrets/polymorfa_key
params:
windowHours: ["24"]
format: [prometheus]
segments: ["false"]
static_configs:
- targets: ["api.polymorfa.com"]
exporters:
otlphttp:
endpoint: ${env:OTLP_ENDPOINT}
headers:
Authorization: ${env:OTLP_AUTHORIZATION}
service:
pipelines:
metrics:
receivers: [prometheus]
exporters: [otlphttp]Usar o Prometheus diretamente#
Copie o job em receivers.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#
| Parâmetro | Significado |
|---|---|
projectId | Seleciona um projeto em API Export team analytics metrics. Um token de projeto sempre lê o próprio projeto. |
sessionId | Seleciona um número pelo UUID do registro, dentro do projeto ou da equipe que você tem autorização para ler. |
windowHours | 1–168 horas UTC completas; padrão 24. O período termina no limite de hora mais recente. |
segments | true adiciona detalhamentos por metadados; padrão false. |
format | prometheus para texto 0.0.4 ou openmetrics para texto 1.0. |
Para ler o texto das métricas a partir do seu próprio código:
API
curl --get "$POLYMORFA_API_URL/platform/analytics/metrics" \
--header "Authorization: Bearer $POLYMORFA_API_KEY" \
--data-urlencode "projectId=$PROJECT_ID" \
--data-urlencode "windowHours=24" \
--data-urlencode "format=openmetrics"const metrics = await platform.analytics.metrics({
projectId: "22222222-2222-4222-8222-222222222222",
windowHours: 24,
segments: true,
format: "openmetrics",
});
console.log(metrics.data, metrics.metadata.status);TypeScript:
data contém o texto das métricas e metadata, os detalhes HTTP. Os clientes de equipe e de projeto aceitam o método, com o mesmo filtro de número.
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 com polymorfa_analytics_.
| Família de métricas | O que mede |
|---|---|
enabled, window_start_timestamp_seconds, window_end_timestamp_seconds, generated_timestamp_seconds | Estado da adesão, período de medição e horário de geração da coleta. |
numbers, connected, message_measured, message_observed_hours, message_last_observed_timestamp_seconds | Cobertura de números, estado da conexão ao vivo e última observação de mensagem. Horas medidas não são tempo de conexão ativa. |
requests, request_failures, request_error_ratio | Contagem de requisições de API/MCP, contagem de falhas e proporção de falhas. |
messages, send_failure_ratio, business_response_seconds | Tentativas de envio, envios bem-sucedidos, falhas de envio, mensagens diretas recebidas, respostas da empresa e atraso de resposta. |
conversations, engagement_ratio, customer_response_seconds | Contagens de coortes de conversas diretas de 24 horas concluídas, proporções de entrega/leitura/resposta e atraso de resposta do cliente. outcome="completed" fornece o denominador da proporção. |
engagement_complete, segments_complete, dropped_observations | Completude dos intervalos observados e contagens de dados descartados. A completude não prova observação contínua ao longo de todo o período. |
online_seconds, connection_events | Tempo de presença online anunciada, desconexões, falhas de conexão, erros de stream e timeouts de keepalive. Tempo de presença online não é tempo de conexão ativa. |
customer_activity_observed, customer_presence_signals | Sinais observados de online/offline/digitando vindos de inscrições de presença ativas. Os sinais não contam pessoas únicas nem quanto tempo elas ficam online. |
phone_interval_average_seconds, phone_interval_seconds | Períodos de atividade e intervalos sem sinais do celular, concluídos e observados. O rótulo kind separa activity e quiet; não são durações online/offline do celular. |
account_activity_observed, account_activity, account_response_seconds, primary_phone_last_timestamp_seconds | Atividade do celular e de outros dispositivos, respostas e tempos de resposta. Os períodos ativos do celular não são ciclos de energia. |
awaiting_reply, oldest_awaiting_reply_seconds, queue_observed_timestamp_seconds, queue_complete | Última fila de respostas medida, idade no momento da observação e cobertura. |
calls, call_starts, short_answered_calls, video_calls, call_answer_eligible, call_answer_ratio | Chamadas por direção/resultado, o denominador da taxa de atendimento e a proporção de atendimento. Chamadas ainda tocando ficam fora desse denominador. Chamadas atendidas curtas têm menos de 10 segundos de conexão medidos. |
call_talk_seconds, call_talk_measured, call_talk_duration_seconds, call_pickup_measured, call_pickup_delay_seconds | Tempo conectado medido e tempos de média/mediana/p95 por número. |
call_quality_measured, call_jitter_seconds, call_rtt_seconds, call_packets_lost, call_packet_loss_ratio, call_reconnects | Cobertura dos relatórios de qualidade e medições informadas de áudio/conexão. Os relatórios de mídia e do app ficam separados. |
missed_call_follow_up, missed_call_follow_up_ratio, missed_call_follow_up_delay_seconds | Uma chamada feita e atendida para o mesmo contato em até 24 horas depois de uma chamada recebida perdida. Janelas elegíveis concluídas, chamadas retornadas, janelas pendentes e contatos desconhecidos ficam separados. |
multi_participant_calls, call_diagnostics | Contagens de chamadas com vários participantes e categorias limitadas de motivo de encerramento, erro do app e transporte. |
segment_observations, segment_ratio, segment_customer_response_seconds | Detalhamentos opcionais por tipo de mensagem, tamanho do texto, origem do envio, código de chamada e dispositivo do cliente. |
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 use rate() 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:
sum(
polymorfa_analytics_conversations{outcome="read"}
and on(job, instance, project_id, number_id)
(polymorfa_analytics_engagement_complete == 1)
)
/
sum(
polymorfa_analytics_conversations{outcome="completed"}
and on(job, instance, project_id, number_id)
(polymorfa_analytics_engagement_complete == 1)
)Recibos de leitura são leituras observadas, não aberturas do app. As categorias de metadados agrupam a primeira mensagem bem-sucedida de uma conversa; as parcelas por código de chamada e por dispositivo contam conversas, não clientes únicos nem locais físicos. Compare dentro de uma única 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 apenas enabled=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:
| Campo | Significado |
|---|---|
id | Identidade estável do registro para a revisão do destino, a hora e o número |
type | analytics.window |
projectId, numberId | UUIDs dos registros do projeto e do número |
period.start, period.end | Limites do período em milissegundos Unix |
windowHours | Período móvel selecionado: 1, 24 ou 168 |
generatedAt | Horário de preparação do retrato em milissegundos Unix |
data | As métricas do número vindas da API JSON de Análises, incluindo engajamento, detalhamentos por metadados, chamadas, conexão e observações de atividade |
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 inclui phone_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:
| Gauge | Significado |
|---|---|
polymorfa_analytics_device_platforms_measured | Se existem observações de família de cliente no período selecionado |
polymorfa_analytics_device_platforms_complete | Se todos os intervalos retidos têm cobertura completa |
polymorfa_analytics_device_platform_messages | Mensagens diretas observadas, rotuladas por direction (customer ou account) e pela platform estimada |
polymorfa_analytics_device_platform_share | Parcela da plataforma; omitida quando a cobertura está incompleta |
polymorfa_analytics_owned_device_list_current | Se a última lista completa de dispositivos próprios não tem mudança observada depois dela |
polymorfa_analytics_owned_devices | Quantidade na última lista completa; omitida quando desatualizada ou não observada |
polymorfa_analytics_owned_device_list_observed_timestamp_seconds | Horário da última observação de lista completa |
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#
Com segments=true, a atividade medida dos destinatários adiciona estes gauges de período móvel:
| Métrica | Significado |
|---|---|
polymorfa_analytics_recipient_activity_measured | Existem observações de destinatários nos intervalos retidos |
polymorfa_analytics_recipient_activity_complete | Todos os intervalos retidos têm cobertura completa de destinatários |
polymorfa_analytics_recipient_signals | Contagens de mensagens recebidas, entrega, leitura, online, offline e digitando, separadas por signal |
polymorfa_analytics_recipient_last_signal_timestamp_seconds | Horário do último sinal observado |
polymorfa_analytics_recipient_quiet_gaps | Intervalos concluídos de pelo menos 15 minutos entre sinais do mesmo dispositivo |
polymorfa_analytics_recipient_quiet_gap_seconds | Soma desses intervalos concluídos; não é tempo offline |
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.