Assembly Execution Progress

Aviso

Este recurso ainda está em estágio experimental. Seu comportamento exato, sua API e seus preços podem mudar enquanto continuamos trabalhando nele. Se você encontrar bugs ou comportamentos estranhos, entre em contato conosco.

O Assembly Execution Progress fornece estimativas em tempo real sobre o quanto a execução de uma Assembly já avançou. Um valor percentual é calculado para o progresso da Assembly inteira, bem como para cada arquivo enviado por upload (e para quaisquer importações que incluam um original_id). Isso fornece informações precisas de progresso mesmo que os arquivos sejam processados de maneiras diferentes na mesma Assembly, por exemplo por causa de tipos de arquivo diferentes.

Para calcular esses valores percentuais, nosso motor de Assembly prevê quais Steps provavelmente serão executados no restante da Assembly. Essa previsão é então comparada aos Steps já concluídos para obter a estimativa de progresso. Em seguida, aprimoramos essa estimativa incorporando informações de progresso dos Steps em execução no momento. Por exemplo, para os Steps /video/encode, incluímos informações sobre quanto do vídeo já foi codificado até o momento.

O Assembly Execution Progress é um ótimo complemento para sua interface de usuário, dando aos seus usuários uma visão do que está acontecendo com os arquivos deles. Combinado com o progresso de upload comum, que mostra o andamento da transferência dos arquivos dos usuários para nossos servidores, o Assembly Execution Progress ajuda a mostrar aos seus usuários que os arquivos deles estão sendo bem cuidados e que as coisas estão acontecendo nos bastidores.

Assemblies compatíveis

Tentamos fornecer o Execution Progress para toda Assembly, mas isso não é possível de forma confiável em todos os casos. Se sua Assembly incluir um Step com uma quantidade de resultados imprevisível, nenhum progresso pode ser estimado até que esse Step seja concluído. No entanto, assim que todos esses Steps forem concluídos, o Execution Progress pode ser calculado.

Os Steps cuja quantidade de resultados não pode ser prevista são:

Importar diretórios via /s3/import, /azure/import etc. Isso não inclui importar um número fixo de arquivos.
/file/decompress: extrair um arquivo compactado em um número variável de arquivos.
/document/thumbs: gerar miniaturas de um documento sem especificar o número da página.

Se sua Assembly não incluir esses Steps, o Execution Progress fica disponível desde o início. Se ela incluir esses Steps, o progresso fica disponível depois que esses Steps forem concluídos.

O Execution Progress não está disponível para Assemblies de URL Transform (a flag emit_execution_progress é ignorada). Para uploads multipart, o progresso só pode começar depois que os metadados do upload são extraídos, o que acontece assim que os uploads terminam.

Como ativar o Assembly Execution Progress

Você precisa ativar explicitamente esse recurso para cada Assembly na qual deseja receber o Execution Progress. Isso é feito quando a Assembly é criada (English), incluindo a propriedade "emit_execution_progress": true nas Assembly Instructions, por exemplo:

{
  "steps": {
    "resized": {
      "robot": "/image/resize",
      "use": ":original",
      "width": 100,
      "height": 100,
      "resize_strategy": "fillcrop",
    },
    // ...
  },
  // ...

  // Enable execution progress
  "emit_execution_progress": true,
}

Início rápido

Adicione "emit_execution_progress": true às suas Assembly Instructions.
Abra o stream de atualizações da Assembly (English).
Escute o evento assembly_execution_progress e atualize sua UI.

Como receber o Execution Progress

O Assembly Execution Progress pode ser obtido pelo stream de atualizações da Assembly. Em resumo, depois que uma Assembly é criada, o Assembly Status contém uma URL na qual você pode obter mensagens e eventos em tempo real sobre o status da Assembly. Os detalhes exatos são descritos na documentação (English).

Assim que o stream de atualizações de uma Assembly é aberto e o Execution Progress está ativado, você recebe atualizações de progresso regularmente, a cada 2 segundos aproximadamente. A atualização é enviada pelo evento assembly_execution_progress. Ela inclui um payload JSON que descreve o progresso da Assembly inteira e de cada arquivo original (uploads e quaisquer importações que incluam um original_id), por exemplo:

{
  "progress_combined": 75,
  "progress_per_original_file": [
    {
      "original_id": "6bb16f6cd49a44b4ae431f576e016c6d",
      "progress": 50
    },

    {
      "original_id": "56921a2dd46246d3b4d3a98b9f8ed4e1",
      "progress": 100
    }
  ]
}

No exemplo acima, a Assembly inteira está 75% processada. O arquivo com o original_id 56921a2dd46246d3b4d3a98b9f8ed4e1 terminou o processamento, ou seja, passou por todos os seus Steps. O arquivo com o original_id 6bb16f6cd49a44b4ae431f576e016c6d ainda não terminou, com 50% de progresso até agora.

Se nenhuma estimativa de progresso estiver disponível porque a Assembly inclui Steps inacabados cuja quantidade de resultados não pode ser prevista, nenhum evento será emitido até que esses Steps sejam concluídos.