Pular para o conteúdo
Atalho: /, ⌘K ou Ctrl+K

Conectar um coletor de análises

Leia métricas de engajamento, conexão e chamadas dos números com Prometheus ou OpenTelemetry.

Ver em Markdown

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#

  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:

    VariávelValor
    OTLP_ENDPOINTA URL base OTLP HTTP do seu backend, como https://telemetry.example.com:4318
    OTLP_AUTHORIZATIONO valor completo do cabeçalho exigido pelo seu backend, como Bearer YOUR_BACKEND_TOKEN

    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:

    Shell
    otelcol-contrib validate --config=collector.yaml
    otelcol-contrib --config=collector.yaml

    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. 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.

collector.yaml
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âmetroSignificado
projectIdSeleciona um projeto em API Export team analytics metrics. Um token de projeto sempre lê o próprio projeto.
sessionIdSeleciona um número pelo UUID do registro, dentro do projeto ou da equipe que você tem autorização para ler.
windowHours1–168 horas UTC completas; padrão 24. O período termina no limite de hora mais recente.
segmentstrue adiciona detalhamentos por metadados; padrão false.
formatprometheus 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
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"
TypeScript
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étricasO que mede
enabled, window_start_timestamp_seconds, window_end_timestamp_seconds, generated_timestamp_secondsEstado 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_secondsCobertura 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_ratioContagem de requisições de API/MCP, contagem de falhas e proporção de falhas.
messages, send_failure_ratio, business_response_secondsTentativas de envio, envios bem-sucedidos, falhas de envio, mensagens diretas recebidas, respostas da empresa e atraso de resposta.
conversations, engagement_ratio, customer_response_secondsContagens 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_observationsCompletude 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_eventsTempo 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_signalsSinais 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_secondsPerí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_secondsAtividade 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_ratioChamadas 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_secondsTempo 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_reconnectsCobertura 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_secondsUma 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_diagnosticsContagens 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_secondsDetalhamentos 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:

promql
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:

CampoSignificado
idIdentidade estável do registro para a revisão do destino, a hora e o número
typeanalytics.window
projectId, numberIdUUIDs dos registros do projeto e do número
period.start, period.endLimites do período em milissegundos Unix
windowHoursPeríodo móvel selecionado: 1, 24 ou 168
generatedAtHorário de preparação do retrato em milissegundos Unix
dataAs 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:

GaugeSignificado
polymorfa_analytics_device_platforms_measuredSe existem observações de família de cliente no período selecionado
polymorfa_analytics_device_platforms_completeSe todos os intervalos retidos têm cobertura completa
polymorfa_analytics_device_platform_messagesMensagens diretas observadas, rotuladas por direction (customer ou account) e pela platform estimada
polymorfa_analytics_device_platform_shareParcela da plataforma; omitida quando a cobertura está incompleta
polymorfa_analytics_owned_device_list_currentSe a última lista completa de dispositivos próprios não tem mudança observada depois dela
polymorfa_analytics_owned_devicesQuantidade na última lista completa; omitida quando desatualizada ou não observada
polymorfa_analytics_owned_device_list_observed_timestamp_secondsHorá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étricaSignificado
polymorfa_analytics_recipient_activity_measuredExistem observações de destinatários nos intervalos retidos
polymorfa_analytics_recipient_activity_completeTodos os intervalos retidos têm cobertura completa de destinatários
polymorfa_analytics_recipient_signalsContagens de mensagens recebidas, entrega, leitura, online, offline e digitando, separadas por signal
polymorfa_analytics_recipient_last_signal_timestamp_secondsHorário do último sinal observado
polymorfa_analytics_recipient_quiet_gapsIntervalos concluídos de pelo menos 15 minutos entre sinais do mesmo dispositivo
polymorfa_analytics_recipient_quiet_gap_secondsSoma 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.