> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/pt-br/console/analytics) 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](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

**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á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`.

**3. Valide e inicie o coletor**

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

```bash theme={null}
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 organização.

```yaml collector.yaml theme={null}
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. |

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](/pt-br/console/analytics#ler-as-análises-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 theme={null}
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](/pt-br/console/calls).

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

## Enviar retratos JSON por hora

Consulte [Destinos](/pt-br/console/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](/api-reference/platform/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](/pt-br/console/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](/pt-br/console/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](/pt-br/console/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](/pt-br/console/analytics#atividade-dos-destinatários-e-horário-comercial).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.