Semântica de entrega de eventos
Esta página descreve e define como o Currents gerencia os dados de eventos de arquivo simples que enviamos aos parceiros do Data Warehouse Storage.
O Currents for Data Storage é um fluxo contínuo de dados da nossa plataforma para um bucket de armazenamento em uma das conexões de nossos parceiros de data warehouse. O Currents grava arquivos Avro no seu bucket de armazenamento em intervalos regulares, permitindo que você processe e analise os dados do evento usando seu próprio conjunto de ferramentas de business intelligence (BI).
Este conteúdo se aplica apenas aos dados de eventos de arquivo simples que enviamos aos parceiros do Data Warehouse Storage (Google Cloud Storage, Amazon S3 e Microsoft Azure Blob Storage).
Para obter o conteúdo que se aplica a outros parceiros, consulte nossa lista de parceiros disponíveis e verifique suas respectivas páginas.
Eventos de teste
Ao configurar uma integração do Currents, clique em Enviar eventos de teste para verificar a conexão com seu bucket de armazenamento. Esses eventos de teste confirmam que sua integração consegue receber e processar dados corretamente.
Formato dos dados de eventos de teste: Os eventos de teste contêm valores de espaço reservado que correspondem aos tipos de dados corretos de cada campo, mas não contêm dados realistas ou precisos. Por exemplo, um campo timezone pode conter uma string semelhante a um UUID em vez de um identificador de fuso horário válido (como “America/Chicago”). Outros campos, como campaign_name e ip_pool, também podem conter valores de espaço reservado em vez de dados reais.
Esse é o comportamento esperado. Os eventos de teste servem principalmente para testar a conexão e a configuração da integração, não para validar a precisão dos dados. Para ver eventos reais com dados precisos, use uma integração de teste do Currents para enviar dados de eventos reais pelo seu pipeline.
Entrega pelo menos uma vez
Como um sistema de alto rendimento, o Currents oferece uma entrega de eventos “pelo menos uma vez”. Isso significa que, ocasionalmente, eventos duplicados podem ser gravados no seu bucket de armazenamento. Isso pode acontecer quando os eventos são reprocessados a partir da nossa fila por qualquer motivo.
Se os seus casos de uso exigirem uma entrega “exatamente uma vez”, você pode usar o campo de identificador exclusivo enviado com cada evento (id) para eliminar eventos duplicados. Como o arquivo sai do nosso controle quando é gravado no seu bucket de armazenamento, não temos como garantir a eliminação de duplicatas do nosso lado.
Carimbos de data/hora
Todos os registros de data e hora exportados pelo Currents são enviados no fuso horário UTC. Em alguns eventos, quando disponível, também é incluído um campo de fuso horário. Esse campo traz o fuso local do usuário no momento do evento, no formato da Internet Assigned Numbers Authority (IANA).
Latência
Os eventos enviados à Braze por meio do SDK ou da API podem incluir um registro de data e hora do passado. O exemplo mais comum é quando os dados do SDK ficam em fila, como quando não há conectividade móvel. Nesse caso, o registro de data e hora do evento vai refletir o momento em que o evento foi gerado. Por isso, uma porcentagem dos eventos vai parecer ter alta latência.
Os SDKs da Braze para Android, Swift e web armazenam no dispositivo os eventos não enviados e tentam enviá-los novamente depois que o dispositivo se reconecta, sem limite de tempo. No SDK para web, os eventos em fila são limitados apenas pelo armazenamento do navegador (cerca de 5 MB).
Não existe uma janela máxima para eventos que chegam com atraso. O Currents foi projetado para exportar todos os eventos que recebe, independentemente da idade do registro de data e hora do evento. Um evento atrasado é gravado na partição date= correspondente à hora em que entrou na fila de processamento da Braze e mantém o registro de data e hora original no campo time. A Braze não reprocessa eventos atrasados em partições anteriores.
Como os eventos atrasados chegam às partições atuais, a Braze recomenda processar os arquivos à medida que são gravados no seu bucket de armazenamento, em vez de verificar novamente partições date= mais antigas com uma janela retroativa. Para remover duplicatas, use o campo id do evento, conforme descrito em Entrega pelo menos uma vez.
Formato Apache Avro
As integrações de armazenamento de dados do Braze Currents geram dados no formato .avro. Escolhemos o Apache Avro porque ele é um formato de dados flexível, que oferece suporte nativo à evolução de esquemas e é compatível com uma grande variedade de produtos de dados:
- O Avro é compatível com quase todos os principais data warehouses.
- Caso você queira manter seus dados no S3, o Avro compacta melhor do que CSV e JSON. Assim, você paga menos pelo armazenamento e pode usar menos CPU para analisar os dados.
- O Avro exige esquemas quando os dados são gravados ou lidos. Os esquemas podem evoluir com o tempo para lidar com a adição de campos sem quebras.
O Currents cria um arquivo para cada tipo de evento usando o seguinte formato:
<your-bucket-prefix>/dataexport.<cluster-identifier>.<connection-type-identifier>.integration.<integration-id>/event_type=<event-type>/date=<date>/version=<currents_version>/<environment>/dataexport.<cluster-identifier>.<connection-type-identifier>.integration.<integration-id>+<partition>+<offset>.avro
Não consegue ver o código por causa da barra de rolagem? Saiba como corrigir isso na página inicial do Guia do Usuário da Braze.
Por exemplo, o caminho de um evento de envio de push pode ser assim:
currents-export/dataexport.prod-01.S3.integration.69cadaaed2d51b7c75b1a3e5/event_type=users.messages.pushnotification.Send/date=2025-04-01-17/version=6/us-01/dataexport.prod-01.S3.integration.69cadaaed2d51b7c75b1a3e5+0+123456.avro
O segmento de caminho version é um valor inteiro simples da versão do Currents, como version=6.
O segmento de caminho version indica que o esquema dos arquivos mudou. Use-o apenas como um indicador, e não como uma coluna de dados para consultas.
Algumas ferramentas leem segmentos de caminho key=value no estilo Hive, como version=6, como colunas de partição (por exemplo, tabelas externas do BigQuery com particionamento Hive). Quando você carrega arquivos dessa forma, a chave de partição version pode entrar em conflito com campos de eventos que também se chamam version, como o campo version nos eventos users.messages.inappmessage.Abort.
Para evitar esse conflito, configure seu pipeline para que ele não trate o segmento de caminho version como uma coluna. Você pode ignorar o valor do campo version da mensagem no app. Ele é um campo legado que distinguia as mensagens no app legadas, que não são mais usadas, das mensagens no app disparadas.
| Segmento do nome do arquivo | Definição |
|---|---|
<your-bucket-prefix> |
O prefixo definido para essa integração do Currents. |
<cluster-identifier> |
Para uso interno da Braze. Será uma string como “prod-01”, “prod-02”, “prod-03” ou “prod-04”. Todos os arquivos terão o mesmo identificador de cluster. |
<connection-type-identifier> |
O identificador do tipo de conexão. As opções são “S3”, “AzureBlob” ou “GCS”. |
<integration-id> |
O ID exclusivo dessa integração do Currents. A Braze define esse ID quando você cria a integração, e ele não muda quando você edita as configurações da integração (como transformações de campo). |
<event-type> |
O tipo do evento no arquivo. |
<date> |
A hora em que os eventos entram na fila do nosso sistema para processamento, no fuso horário UTC. Formatado como AAAA-MM-DD-HH. |
version=<currents_version> |
A versão do Currents para o caminho do pipeline. Esse valor é um número inteiro simples, como 6. |
<environment> |
Para uso interno da Braze. |
<partition> |
Para uso interno da Braze. Número inteiro. |
<offset> |
Para uso interno da Braze. Número inteiro. Note que arquivos diferentes enviados dentro da mesma hora terão um parâmetro <offset> diferente. |
As convenções de nomenclatura de arquivos podem mudar. A Braze recomenda pesquisar todas as chaves no seu bucket que tenham o prefixo <your-bucket-prefix>.
Limite de gravação do Avro
Em circunstâncias normais, a Braze grava arquivos de dados no seu bucket de armazenamento a cada 5 minutos ou a cada 15.000 eventos, o que ocorrer primeiro. Sob carga pesada, podemos gravar arquivos de dados maiores, com até 100.000 eventos por arquivo.
O Currents foi projetado para armazenar internamente em buffer grandes picos de eventos, como os eventos de uma mensagem enviada para milhões de usuários. Você não precisa planejar capacidade extra de gravação ou de E/S no seu bucket de armazenamento para esses picos.
O Currents nunca grava arquivos vazios.
Alterações no esquema Avro
De tempos em tempos, a Braze pode fazer alterações no esquema Avro quando campos são adicionados, alterados ou removidos. Para nossos propósitos aqui, existem dois tipos de alterações: com quebra e sem quebra. Todas as alterações de esquema são agrupadas em versões do Currents, e cada versão avança o segmento version=<currents_version> no caminho de armazenamento (por exemplo, de version=6 para version=7). Os eventos do Currents gravados no Azure Blob Storage, no Google Cloud Storage e no Amazon S3 usam o seguinte formato de caminho:
<your-bucket-prefix>/<currents-integration-id>/event_type=<event-type>/date=<date>/version=<currents_version>/<environment>/<avro-file>
Alterações sem quebra
Quando um campo é adicionado ao esquema Avro, consideramos isso uma alteração sem quebra. Os campos adicionados sempre serão campos Avro “opcionais” (por exemplo, com um valor padrão de null), então eles vão “corresponder” aos esquemas mais antigos de acordo com a especificação de resolução de esquemas do Avro. Essas adições não devem afetar os processos existentes de extração, transformação e carregamento (ETL), já que o campo será simplesmente ignorado até ser adicionado ao seu processo de ETL.
Recomendamos que sua configuração de ETL seja explícita quanto aos campos que processa, para evitar quebras no fluxo quando novos campos forem adicionados.
Alterações com quebra
Quando um campo é removido ou alterado no esquema Avro, consideramos isso uma alteração com quebra. As alterações com quebra podem exigir modificações nos processos de ETL existentes, já que campos que estavam em uso podem não ser mais registrados como esperado.
Todas as alterações com quebra serão comunicadas antes do lançamento.
Para ver o histórico completo de alterações por versão, consulte o changelog do Currents.