# 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](https://docs.polymorfa.com/pt-br/numbers/analytics) 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](https://opentelemetry.io/docs/collector/installation/)
  que inclua o [receiver do Prometheus](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver)
  e o [exporter OTLP HTTP](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/otlphttpexporter/README.md).
  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 do `collector.yaml`.

Defina estas variáveis de ambiente no serviço ou contêiner do coletor:

| Variável | Valor |
| --- | --- |
| `OTLP_ENDPOINT` | A URL base OTLP HTTP do seu backend, como `https://telemetry.example.com:4318` |
| `OTLP_AUTHORIZATION` | O 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`.

### Valide e inicie o coletor

Execute estes comandos com o mesmo ambiente e as mesmas montagens de arquivo do serviço do coletor:

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

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

```yaml 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âmetro     | Significado                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| `projectId`   | Seleciona um projeto em `/platform/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:**

```bash 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 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](https://docs.polymorfa.com/pt-br/numbers/analytics#ler-as-analises-pela-api).

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

```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](https://docs.polymorfa.com/pt-br/calls/console).

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](https://docs.polymorfa.com/api/analytics/export-team-analytics-metrics)
e a [referência de exportação do projeto](https://docs.polymorfa.com/api/analytics/export-project-analytics-metrics).

## Enviar retratos JSON por hora

Consulte [Destinos](https://docs.polymorfa.com/pt-br/development/drains) 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](https://docs.polymorfa.com/api/analytics/read-project-analytics), 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](https://docs.polymorfa.com/pt-br/development/log-forwarding#receba-as-entregas). 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](https://docs.polymorfa.com/pt-br/numbers/analytics#atividade-do-celular-da-polymorfa-e-dos-clientes)
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](https://docs.polymorfa.com/pt-br/development/log-forwarding#verifique-as-assinaturas) 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](https://docs.polymorfa.com/pt-br/numbers/analytics#atividade-dos-destinatarios-e-horario-comercial).
