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

# Queue

> Envie, receba e confirme mensagens em filas padrão e FIFO.

Queue mantém mensagens até que um consumidor as processe e confirme. Use filas padrão para entrega ao menos uma vez com ordenação de melhor esforço ou FIFO para processamento ordenado dentro de cada grupo.

O serviço é regional. O endpoint de São Paulo é `https://queue.sa-saopaulo-1.basaltic.sh`. As chamadas usam bearer token e o identificador da conta em `X-Account-Id`; veja [Autenticação](/pt/authentication).

<span id="receiving-is-a-lease" />

## Receber é obter uma concessão

Receber oculta a mensagem durante o timeout de visibilidade e retorna um recibo. Exclua a mensagem com esse recibo após processá-la com sucesso. Se a concessão vencer antes, a mensagem volta a ficar disponível. Um novo recebimento gera outro recibo; um recibo vencido não pode confirmar a concessão de outro consumidor.

Use o endpoint de visibilidade para estender ou reduzir uma concessão atual. A inspeção é uma operação e permissão separadas: lê mensagens sem concedê-las.

<span id="queue-contracts" />

## Contratos das filas

| Contrato | Comportamento |
| - | - |
| Padrão | Entrega ao menos uma vez e ordenação de melhor esforço. Consumidores devem tolerar reentrega. |
| FIFO | O nome termina em `.fifo`; a ordem é por `message_group_id`. O tipo é fixado na criação. |
| Long polling | `wait_time_seconds` aguarda até 20 segundos por uma mensagem. |
| Confirmação | Exclua usando o recibo da concessão atual. |
| Criptografia | Corpos são criptografados em repouso. Uma chave KMS própria usa `kms_key`. |

As respostas expõem a criptografia gerenciada pelo cliente como referência `kms_key` com `id`, `crn` e `name`. A criptografia da plataforma omite o campo. Se os metadados estiverem indisponíveis, a referência mantém ID e CRN sem nome. Isso não muda a fila para criptografia da plataforma.

`redrive_policy.dead_letter_queue` é uma referência com `id`, `crn` e `name` da fila de destino. Solicitações de criação e atualização aceitam UUID, nome ou CRN como string nesse campo. `max_receive_count` controla quando a mensagem é movida.

Nas atualizações, omitir `kms_key` ou `redrive_policy` preserva o valor atual. Envie `kms_key: null` para restaurar a criptografia da plataforma em novas mensagens ou `redrive_policy: null` para remover a política de mensagens não entregues. Mensagens existentes mantêm a chave original.

<span id="metrics" />

## Métricas

Abra a aba **Metrics** da fila para gráficos de profundidade, tráfego, idade da mensagem disponível mais antiga e conteúdo armazenado. Use o intervalo de tempo para comparar mudanças. As mesmas séries estão em [Telemetry](/pt/telemetry#metrics) e podem alimentar alertas.

As séries são amostradas a cada 30 segundos e incluem os rótulos `queue_id` e `region`. Leituras exigem `telemetry:ReadMetrics` na conta e região selecionadas. Em FIFO, uma mensagem anterior do grupo ainda pode bloquear uma mensagem contada como disponível.

| Métrica | Tipo | Significado |
| - | - | - |
| `basaltic_queue_messages_available` | Gauge | Mensagens não expiradas cujo tempo de visibilidade terminou. |
| `basaltic_queue_messages_in_flight` | Gauge | Mensagens não expiradas com concessão ativa. |
| `basaltic_queue_messages_delayed` | Gauge | Mensagens não expiradas cujo atraso inicial não terminou. |
| `basaltic_queue_stored_bytes` | Gauge | Bytes de conteúdo em mensagens não expiradas. |
| `basaltic_queue_oldest_available_message_age_seconds` | Gauge | Tempo desde o envio da mensagem disponível mais antiga; zero quando vazia. |
| `basaltic_queue_messages_enqueued_total` | Contador | Mensagens armazenadas, incluindo redirecionamento; exclui envios deduplicados. |
| `basaltic_queue_messages_received_total` | Contador | Concessões de mensagens, incluindo reentregas. |
| `basaltic_queue_messages_removed_total` | Contador | Remoções por confirmação, expiração, limpeza ou redirecionamento. |
| `basaltic_queue_bytes_enqueued_total` | Contador | Bytes de conteúdo aceitos na fila. |

Use `last` para profundidade atual e `rate` para tráfego por segundo. Contadores começam na implantação das métricas e persistem após excluir mensagens ou reiniciar workers. Não há preenchimento retroativo. Filas ociosas emitem gauges zero; observações ausentes deixam lacunas, não zeros.

<CardGroup cols={2}>
  <Card title="Criar uma fila" href="/pt/queue/creating">Choose type, timing, encryption, and a dead-letter destination.</Card>
  <Card title="Enviar e consumir" href="/pt/queue/messages">Lease messages, extend visibility, and acknowledge processing.</Card>
  <Card title="Filas FIFO e de mensagens não entregues" href="/pt/queue/fifo-and-dead-letter-queues">Control ordering and isolate repeated failures.</Card>
  <Card title="Permissões" href="/pt/queue/permissions">Separate producers, consumers, and queue administrators.</Card>
</CardGroup>


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