Recuperar um pipeline após a falha de um ponto de verificação de streaming

Recupere um pipeline Lakeflow quando um checkpoint de streaming se tornar inválido ou corrompido, usando uma atualização completa, backup e backfill, ou um reset seletivo do checkpoint.

O que é um ponto de verificação de streaming?

No Apache Spark Structured Streaming, um ponto de verificação é um mecanismo usado para persistir o estado de uma consulta de streaming. Este estado inclui:

  • Informação de progresso: Indica que offsets na origem foram processados.
  • Estado intermédio: Dados que têm de ser mantidos entre micro-lotes para operações com estado (por exemplo, agregações, mapGroupsWithState).
  • Metadados: Informação sobre a execução da consulta de streaming.

Os pontos de verificação são essenciais para garantir a tolerância a falhas e a consistência dos dados em aplicativos de streaming:

  • Tolerância a falhas: Se uma aplicação de streaming falhar (por exemplo, devido a uma falha de nó ou a uma falha da aplicação), o checkpoint permite que a aplicação seja reiniciada a partir do último estado guardado no checkpoint com êxito, em vez de reprocessar todos os dados desde o início. Isso evita a perda de dados e garante o processamento incremental.
  • Processamento único: Para muitas origens de streaming, os checkpoints, em conjunto com destinos idempotentes, permitem garantias de processamento único, assegurando que cada registo é processado exatamente uma vez, mesmo perante falhas, evitando duplicações ou omissões.
  • Gestão do estado: Para transformações com estado, os checkpoints preservam o estado interno destas operações, permitindo que a consulta de streaming continue corretamente a processar novos dados com base no estado histórico acumulado.

Pontos de verificação de oleodutos

Os pipelines assentam no Structured Streaming e ocultam grande parte da gestão subjacente dos pontos de verificação, oferecendo uma abordagem declarativa. Quando você define uma tabela de streaming em seu pipeline, há um estado de ponto de verificação para cada fluxo de gravação na tabela de streaming. Esses locais de ponto de verificação são internos ao pipeline e não são acessíveis aos usuários.

Normalmente, não precisa de gerir nem compreender os checkpoints subjacentes das tabelas de streaming. Quando o fazes, a ferramenta certa depende da tua situação:

  • Se quiseres recuperar o pipeline para uma versão anterior devido a uma má transformação, alteração de esquema, entrada mal formada ou um deployment de código deficiente: Rebobina o pipeline. O Rewind restaura os dados da tabela, os deslocamentos de origem e o estado do operador em conjunto para um ponto anterior e reprocessa apenas os dados afetados, preservando o estado do operador. Esta é a forma recomendada de reprocessar a partir de um determinado momento, embora possam aplicar-se limitações da Beta.
  • O checkpoint está corrompido, ou uma alteração de código incompatível com checkpoint bloqueia o pipeline: o Rewind não recupera estes casos, porque não relaxa as regras de compatibilidade do Structured Streaming. Use um dos métodos de recuperação por pontos de controlo nas opções de recuperação:
    • Atualização completa da tabela: Redefine a tabela e elimina os dados existentes.
    • Atualização completa da tabela com cópia de segurança e reposição retroativa: Crie uma cópia de segurança da tabela antes de uma atualização completa e depois reponha retroativamente os dados antigos. Isto é caro e deve ser o último recurso.
    • Reiniciar o checkpoint e continuar incrementalmente: Preserve os dados existentes e reinicie o checkpoint para os fluxos de streaming afetados.

Exemplo: Falha de pipeline devido a alteração de código

Considere um cenário em que você tenha um pipeline que processa um feed de dados de alteração junto com o snapshot inicial da tabela de um sistema de armazenamento em nuvem, como o Amazon S3, e grava em uma tabela de streaming SCD-1.

O pipeline tem dois fluxos de streaming:

  • customers_incremental_flow: Lê incrementalmente o customer feed CDC da tabela de origem, filtra os registos duplicados e insere-os na tabela alvo.
  • customers_snapshot_flow: Lê uma única vez o instantâneo inicial da customers tabela de origem e atualiza os registos para a tabela alvo.

Exemplo de CDC de pipelines para recuperação de falha de ponto de controlo

@dp.temporary_view(name="customers_incremental_view")
def query():
    return (
    spark.readStream.format("cloudFiles")
        .option("cloudFiles.format", "json")
        .option("cloudFiles.inferColumnTypes", "true")
        .option("cloudFiles.includeExistingFiles", "true")
        .load(customers_incremental_path)
        .dropDuplicates(["customer_id"])
    )

@dp.temporary_view(name="customers_snapshot_view")
def full_orders_snapshot():
    return (
        spark.readStream
        .format("cloudFiles")
        .option("cloudFiles.format", "json")
        .option("cloudFiles.includeExistingFiles", "true")
        .option("cloudFiles.inferColumnTypes", "true")
        .load(customers_snapshot_path)
        .select("*")
    )

dp.create_streaming_table("customers")

dp.create_auto_cdc_flow(
    name = "customers_incremental_flow",
    target = "customers",
    source = "customers_incremental_view",
    keys = ["customer_id"],
    sequence_by = col("sequenceNum"),
    apply_as_deletes = expr("operation = 'DELETE'"),
    apply_as_truncates = expr("operation = 'TRUNCATE'"),
    except_column_list = ["operation", "sequenceNum"],
    stored_as_scd_type = 1
)
dp.create_auto_cdc_flow(
    name = "customers_snapshot_flow",
    target = "customers",
    source = "customers_snapshot_view",
    keys = ["customer_id"],
    sequence_by = lit(0),
    stored_as_scd_type = 1,
    once = True
)

Depois de implantar o pipeline, ele executa-se com sucesso e começa a processar o feed de dados de alteração e a captura inicial de dados.

Mais tarde, você percebe que a lógica de desduplicação na consulta customers_incremental_view é redundante e está causando um gargalo de desempenho. Remova o dropDuplicates() para melhorar o desempenho.

@dp.temporary_view(name="customers_raw_view")
def query():
    return (
    spark.readStream.format("cloudFiles")
        .option("cloudFiles.format", "json")
        .option("cloudFiles.inferColumnTypes", "true")
        .option("cloudFiles.includeExistingFiles", "true")
        .load()
        # .dropDuplicates()
    )

Depois de remover a dropDuplicates() API e reimplantar o pipeline, a atualização falha com o seguinte erro:

Streaming stateful operator name does not match with the operator in state metadata.
This is likely to happen when a user adds/removes/changes stateful operators of existing streaming query.
Stateful operators in the metadata: [(OperatorId: 0 -> OperatorName: dedupe)];
Stateful operators in current batch: []. SQLSTATE: 42K03 SQLSTATE: XXKST

Esse erro indica que a alteração não é permitida devido a uma incompatibilidade entre o estado do ponto de verificação e a definição de consulta atual, impedindo que o pipeline progrida ainda mais.

Falhas relacionadas ao ponto de verificação podem ocorrer por vários motivos além de apenas remover a dropDuplicates API. Cenários comuns incluem:

  • Adicionar ou remover operadores com estado (por exemplo, introduzindo ou descartando dropDuplicates() ou agregações) numa consulta de streaming existente.
  • Adicionar, remover ou combinar fontes de streaming numa consulta que já foi alvo de ponto de verificação (por exemplo, concatenar uma consulta de streaming existente com uma nova ou adicionar/remover fontes de uma operação de concatenação existente).
  • Modificar o esquema de estado de operações de streaming com estado (como alterar as colunas usadas para desduplicação ou agregação).

Para obter uma lista abrangente de alterações suportadas e não suportadas, consulte o Guia de Streaming Estruturado do Spark e Tipos de alterações em consultas de Streaming Estruturado.

Opções de recuperação

A tabela seguinte compara as suas opções. Rebobinar um pipeline saudável de um ponto anterior no tempo; os outros três recuperam um pipeline bloqueado por um checkpoint inválido ou corrompido. Diferem em complexidade, custo e requisitos de durabilidade dos dados:

Methods Complexidade Custo Perda potencial de dados Potencial duplicação de dados Requer instantâneo inicial Reinicialização completa da tabela
Rebobinar Low Baixo (reprocessa apenas a janela afetada) Não Não Não Não
Atualização completa da tabela Low Médio Sim (Se nenhum instantâneo inicial estiver disponível ou se os arquivos brutos tiverem sido excluídos na origem.) Não (Para aplicar alterações à tabela de destino.) Yes Yes
Atualização completa da mesa com backup e backfill Médio High Não Não (Para pias idempotentes. Por exemplo, auto CDC.) Não Não
Repor ponto de controlo da tabela Médio-Alto (Médio para fontes apenas anexar que fornecem offsets imutáveis.) Low Não (Requer uma consideração cuidadosa.) Não (Para escritores idempotentes. Por exemplo, auto CDC apenas para a tabela de destino.) Não Não

A complexidade média-alta depende do tipo de origem de streaming e da complexidade da consulta.

Rewind requer um pipeline no canal Pré-visualização com a opção de configuração pipelines.rewind.betaEnabled definida e origens e destinos suportados. Reprocessa um pipeline a partir de um ponto anterior; não recupera um checkpoint inválido ou corrompido, nem uma alteração de código incompatível com o checkpoint. Para esses, usa um dos outros três métodos. Veja Rebobinar e reproduzir um pipeline.

Recommendations

  • Use Rewind quando o pipeline estiver saudável mas produziu dados incorretos de um momento conhecido, e quiser preservar o estado do operador enquanto reprocessa apenas a janela afetada. É a opção mais simples quando se aplica, mas requer o canal de pré-visualização e origens e destinos compatíveis, e não consegue recuperar um checkpoint corrompido nem uma alteração incompatível com o checkpoint.
  • Use uma atualização de tabela completa se não quiser lidar com a complexidade de uma reinicialização de ponto de verificação, podendo assim recalcular a tabela inteira. Uma atualização completa também te dá a opção de fazer alterações no código.
  • Use o refresh completo da tabela com backup e preenchimento retroativo se não quiser lidar com a complexidade da redefinição do ponto de verificação e concordar com o custo adicional de efetuar backup e preencher retroativamente os dados históricos.
  • Use o ponto de verificação de reinicialização da tabela se precisar preservar os dados existentes na tabela e continuar a processar novos dados de forma incremental. No entanto, esta abordagem requer um tratamento cuidadoso da reposição do ponto de verificação para garantir que os dados existentes na tabela não sejam perdidos e assegurar que o pipeline possa continuar a processar novos dados.

Redefinindo o ponto de controlo e continuando de forma incremental

Para redefinir o ponto de verificação e continuar o processamento incrementalmente, siga estas etapas:

  1. Parar o pipeline: certifique-se de que o pipeline não tenha atualizações ativas em execução.

  2. Determinar a posição inicial para o novo ponto de verificação: identifique o último deslocamento bem-sucedido ou timestamp a partir do qual é necessário continuar o processamento. Normalmente, este é o último offset processado com êxito antes da ocorrência da falha.

    Como está a ler os ficheiros JSON usando o Auto Loader no exemplo anterior, pode usar a modifiedAfter opção para definir um carimbo temporal para quando o Auto Loader começar a processar novos ficheiros.

    Para fontes Kafka, você pode usar a startingOffsets opção para especificar os deslocamentos a partir dos quais a consulta de streaming deve começar a processar novos dados.

    Para fontes Delta Lake, você pode usar a startingVersion opção para especificar a versão a partir da qual a consulta de streaming deve começar a processar novos dados.

  3. Fazer alterações de código: você pode modificar a consulta de streaming para remover a dropDuplicates() API ou fazer outras alterações. Verifica também se adicionaste a modifiedAfter opção ao caminho de leitura do Auto Loader.

    @dp.temporary_view(name="customers_incremental_view")
    def query():
        return (
        spark.readStream.format("cloudFiles")
            .option("cloudFiles.format", "json")
            .option("cloudFiles.inferColumnTypes", "true")
            .option("cloudFiles.includeExistingFiles", "true")
            .option("modifiedAfter", "2025-04-09T06:15:00")
            .load(customers_incremental_path)
            # .dropDuplicates(["customer_id"])
        )
    

    Observação

    Fornecer um carimbo de data/hora incorreto modifiedAfter pode levar à perda ou duplicação de dados. Verifique se o carimbo de data/hora está definido corretamente para evitar o processamento de dados antigos novamente ou a perda de novos dados.

    Se a sua consulta tiver uma junção entre fluxos ou uma união de fluxo-fluxo, deve aplicar a estratégia acima para todas as fontes de fluxo contínuo participantes. Por exemplo:

    cdc_1 = spark.readStream.format("cloudFiles")...
    cdc_2 = spark.readStream.format("cloudFiles")...
    cdc_source = cdc_1.union(cdc_2)
    
  4. Identifique os nomes dos fluxos associados à tabela de streaming para os quais pretende reiniciar o checkpoint. Deve passar cada nome de fluxo num formato totalmente qualificado catalog.schema.flow_name . No exemplo, o nome do fluxo totalmente qualificado é my_catalog.my_schema.customers_incremental_flow. O fluxo utiliza um parâmetro explícito name de customers_incremental_flow. Se não definir um nome de fluxo explícito, o nome padrão do fluxo é o nome totalmente qualificado da tabela alvo no catalog.schema.table formato (por exemplo, my_catalog.my_schema.customers). Pode encontrar nomes de fluxos no código do pipeline, na interface do pipeline ou nos registos de eventos do pipeline.

  5. Reinicie o checkpoint e inicie uma atualização: Crie um caderno Python e anexe-o a um cluster Azure Databricks.

    Você precisará das seguintes informações para poder redefinir o ponto de verificação:

    • URL do espaço de trabalho do Azure Databricks
    • ID da Pipeline
    • Nome(s) de fluxo para o(s) qual(is) você está redefinindo o ponto de verificação
    import requests
    import json
    
    # Define your Databricks instance and pipeline ID
    databricks_instance = "<DATABRICKS_URL>"
    token = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiToken().get()
    pipeline_id = "<YOUR_PIPELINE_ID>"
    flows_to_reset = ["<YOUR_FLOW_NAME>"]
    # Set up the API endpoint
    endpoint = f"{databricks_instance}/api/2.0/pipelines/{pipeline_id}/updates"
    
    
    # Set up the request headers
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
    
    # Define the payload
    payload = {
        "reset_checkpoint_selection": flows_to_reset
    }
    
    # Make the POST request
    response = requests.post(endpoint, headers=headers, data=json.dumps(payload))
    
    # Check the response
    if response.status_code == 200:
        print("Pipeline update started successfully.")
    else:
        print(f"Error: {response.status_code}, {response.text}")
    
  6. Na interface do pipeline, verifica se a atualização está a correr. Os fluxos de reinício processam novos dados a partir da posição inicial especificada com um novo ponto de controlo, e os dados existentes da tabela são preservados.

Melhores práticas

  • Evite usar recursos de visualização privada na produção.
  • Teste as alterações antes de fazer alterações no ambiente de produção.
    • Crie um pipeline de teste, idealmente em um ambiente mais baixo. Se isso não for possível, tente usar um catálogo e esquema diferentes para seu teste.
    • Reproduza o erro.
    • Aplique as alterações.
    • Valide os resultados e tome uma decisão de avançar/não avançar.
    • Aplique as alterações nos seus pipelines de produção.