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

Recupere um pipeline do Lakeflow quando um ponto de verificação de streaming se tornar inválido ou corrompido, usando uma atualização completa, um backup e um provisionamento, ou uma redefinição seletiva do ponto de verificação.

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

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

  • Informações de progresso: Quais offsets da fonte foram processados.
  • Estado intermediário: Dados que precisam ser mantidos entre micro-lotes para operações com estado (por exemplo, agregações, mapGroupsWithState).
  • Metadados: Informações 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 de dados em aplicativos de streaming:

  • Tolerância a falhas: Se uma aplicação de streaming falhar (por exemplo, devido a falha de nó, crash da aplicação), o checkpoint permite que a aplicação reinicie a partir do último estado de checkpoint bem-sucedido, em vez de reprocessar todos os dados do início. Isso evita a perda de dados e garante o processamento incremental.
  • Processamento exatamente uma vez: Para muitas fontes de streaming, checkpoints, em conjunto com sumidouros idempotentes, permitem garantias de processamento exatamente uma vez, de modo que cada registro seja processado exatamente uma vez, mesmo diante de falhas, evitando duplicações ou omissões.
  • Gerenciamento de estado: Para transformações com estado, os checkpoints persistem o estado interno dessas operações, permitindo que a consulta em streaming continue processando corretamente novos dados com base no estado histórico acumulado.

Pontos de controle do pipeline

Pipelines se baseiam no Streaming Estruturado e abstraem grande parte do gerenciamento de pontos de verificação subjacente, oferecendo uma abordagem declarativa. Quando você define uma tabela de streaming em seu pipeline, há um estado de ponto de verificação para cada gravação de fluxo 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, você não precisa gerenciar nem entender os checkpoints subjacentes das tabelas de streaming. Quando você faz isso, a ferramenta certa depende da sua situação:

  • Se você quiser recuperar o pipeline para uma versão anterior devido a uma transformação ruim, mudança de esquema, entrada mal formada ou uma implementação de código ruim: Rewind o pipeline. O Rewind restaura em conjunto os dados da tabela, os offsets da origem e o estado do operador para um momento anterior e reprocessa apenas os dados afetados, preservando o estado do operador. Essa é a forma recomendada de reprocessar a partir de um determinado momento, embora possam se aplicar limitações do Beta.
  • O checkpoint está corrompido, ou uma alteração de código incompatível com checkpoint está bloqueando o pipeline: o Rewind não recupera esses casos porque não relaxa as regras de compatibilidade do Structured Streaming. Use um dos métodos de recuperação por checkpoint nas opções de recuperação:
    • Atualização completa da tabela: Reinicia a tabela e apaga os dados existentes.
    • Atualização completa da tabela com backup e preenchimento: Faça backup da tabela antes de uma atualização completa e depois preencha os dados antigos. Isso é caro e deve ser o último recurso.
    • Resetar o checkpoint e continuar incrementalmente: Preserve os dados existentes e reinicie o checkpoint para os fluxos de streaming afetados.

Exemplo: falha de pipeline devido à alteração de código

Considere um cenário em que você tem um pipeline que processa um fluxo de dados de alterações juntamente com o instantâneo da tabela inicial 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 registros duplicados e os insere na tabela de destino.
  • customers_snapshot_flow: Lê uma vez o snapshot inicial da tabela fonte customers e faz upsert dos registros na tabela de destino.

Exemplo de CDC de pipelines para recuperação de falha de checkpoint

@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 esse pipeline, ele é executado e começa a processar o fluxo de dados de alteração e o instantâneo inicial.

Posteriormente, você percebe que a lógica de eliminação de duplicação na customers_incremental_view consulta é redundante e causa um gargalo de desempenho. Você remove 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 falhará 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:

  • Adicionando ou removendo operadores de estado (por exemplo, introduzindo ou descartando dropDuplicates() ou agregações) em uma consulta de streaming existente.
  • Adicionando, removendo ou combinando fontes de streaming em uma consulta com ponto de verificação anteriormente (por exemplo, a união de uma consulta de streaming existente com uma nova ou a adição/remoção de fontes de uma operação de união existente).
  • Modificando o esquema de estado de operações de streaming com estado (como alterar as colunas usadas para eliminação de duplicação ou agregação).

Para obter uma lista abrangente de alterações com suporte e sem suporte, 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 a seguir compara 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. Eles diferem em complexidade, custo e requisitos de durabilidade dos dados:

Methods Complexidade Custo Possível perda de dados Duplicação de dados em potencial Requer instantâneo inicial Redefiniçã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 Medium 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 na tabela de destino.) Yes Yes
Atualização completa da tabela com backup e backfill Medium High Não Não (Para coletores idempotentes. Por exemplo, CDC automático.) Não Não
Redefinir checkpoint da tabela Médio-Alto (Médio para fontes somente acrescentar que fornecem deslocamentos imutáveis.) Low Não (Requer consideração cuidadosa.) Não (Somente para gravadores idempotentes. Por exemplo, CDC automático apenas para a tabela de destino.) Não Não

A complexidade Média-Alta depende do tipo de fonte de streaming e da complexidade da consulta.

Rewind requer um pipeline no canal Preview com o sinalizador de configuração pipelines.rewind.betaEnabled definido e fontes e destinos compatíveis. Ele reprocessa um pipeline a partir de um ponto anterior; não restaura um checkpoint inválido ou corrompido, nem uma alteração de código incompatível com o checkpoint. Para esses, use um dos outros três métodos. Consulte Retroceder e reexecutar um pipeline.

Recommendations

  • Use Retroceder quando o pipeline estiver íntegro, mas tiver produzido dados incorretos a partir de um ponto conhecido no tempo, e você quiser preservar o estado do operador enquanto reprocessa apenas a janela afetada. É a opção mais simples quando se aplica, mas requer o canal Preview e as fontes e os destinos suportados, e não pode recuperar um checkpoint corrompido nem uma alteração incompatível com o checkpoint.
  • Use uma atualização completa da tabela se você não quiser lidar com a complexidade de uma redefinição de ponto de verificação e puder recalcular a tabela inteira. Uma atualização completa também oferece uma opção para fazer alterações de código.
  • Use a atualização completa da tabela com backup e provisionamento se você não quiser lidar com a complexidade da redefinição de ponto de verificação e se estiver bem com o custo adicional de fazer um backup e preencher os dados históricos.
  • Use o ponto de verificação da tabela de redefinição se você precisar preservar os dados existentes na tabela e continuar processando novos dados incrementalmente. No entanto, essa abordagem exige um manuseio cuidadoso da redefinição do ponto de verificação para assegurar que os dados existentes na tabela não sejam perdidos e que o pipeline possa continuar processando novos dados.

Redefinir ponto de verificação e continuar incrementalmente

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

  1. Pare o pipeline: verifique se o pipeline não tem atualizações ativas em execução.

  2. Determine a posição de início para o novo ponto de verificação: identifique o último deslocamento bem-sucedido ou carimbo de data e hora a partir do qual deseja continuar processando. Geralmente, este é o deslocamento mais recente que foi processado antes de ocorrer a falha.

    Como você está lendo os arquivos JSON usando o Carregador Automático no exemplo anterior, você pode usar a opção modifiedAfter para definir um carimbo de data/hora para quando o Carregador Automático iniciar o processamento de novos arquivos.

    Para fontes Kafka, você pode usar a opção startingOffsets 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 opção startingVersion para especificar a versão da qual a consulta de streaming deve começar a processar novos dados.

  3. Faça alterações de código: você pode modificar a consulta de streaming para remover a dropDuplicates() API ou fazer outras alterações. Verifique também se você adicionou a opção modifiedAfter ao caminho de leitura do Carregador Automático.

    @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 timestamp incorreto modifiedAfter pode resultar em perda ou duplicação de dados. Verifique se o timestamp está definido corretamente para evitar o processamento de dados antigos novamente ou perder novos dados.

    Se a consulta tiver uma junção ou uma união de fluxos, você deverá aplicar a estratégia acima a todas as fontes de streaming envolvidas. 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 de fluxo associados à tabela de streaming para a qual você deseja redefinir o ponto de verificação. Você deve passar cada nome de fluxo em um formato totalmente qualificado catalog.schema.flow_name. No exemplo, o nome do fluxo totalmente qualificado é my_catalog.my_schema.customers_incremental_flow. O fluxo usa um parâmetro explícito name de customers_incremental_flow. Se você não definir um nome de fluxo explícito, o nome do fluxo padrão será o nome da tabela de destino totalmente qualificado no catalog.schema.table formato (por exemplo, my_catalog.my_schema.customers). Você pode encontrar nomes de fluxo no código do pipeline, na interface do usuário do pipeline ou nos logs de eventos do pipeline.

  5. Resete o checkpoint e inicie uma atualização: crie um notebook em Python e anexe-o a um cluster do 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 do pipeline
    • Nome do fluxo para o qual 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, verifique se a atualização está rodando. O reset processa novos dados da posição inicial especificada com um novo checkpoint, e os dados existentes da tabela são preservados.

Práticas recomendadas

  • Evite usar recursos de visualização privada em produção.
  • Teste suas alterações antes de fazer alterações em seu ambiente de produção.
    • Crie um pipeline de teste, idealmente em um ambiente inferior. Se isso não for possível, tente usar um catálogo e um esquema diferentes para seu teste.
    • Reproduza o erro.
    • Aplique as alterações.
    • Valide os resultados e tome uma decisão de seguir em frente ou não.
    • Implemente as alterações nos pipelines de produção.