Gostaria de compartilhar a forma como normalmente analiso problemas em fluxos do Architect.
Minha abordagem depende bastante da organização em que estou trabalhando e dos recursos que estão habilitados nela.
O primeiro ponto que costumo verificar é o Operational Console. Por meio dele, consigo identificar eventos operacionais e erros relacionados às execuções dos fluxos. Quando existe um evento como o ARCHITECT-0002, por exemplo, o próprio console pode direcionar a investigação para o Replay Mode do Architect. Os eventos permanecem disponíveis no console por dez dias.
Também verifico se o Historical Execution Data está habilitado para a organização. Quando tenho autorização para configurá-lo, normalmente considero o nível Notes suficiente para a maioria das investigações, pois ele permite visualizar o caminho percorrido e os valores das variáveis sem necessariamente armazenar todo o detalhamento de entradas e saídas das ações.
Quando o Execution Data não está habilitado, ou quando preciso manter uma informação de rastreamento diretamente na interação, utilizo uma abordagem semelhante à mencionada pelo Satish: registro os principais passos do fluxo em uma variável e, ao final, salvo o resultado em Participant Data.
Entretanto, faço isso com cautela. É necessário considerar:
- O tipo de fluxo.
- A quantidade de etapas que serão registradas.
- O tamanho máximo da variável.
- Os limites aplicáveis aos atributos.
- A possibilidade de expor dados pessoais ou sensíveis.
- O impacto da alteração na leitura e manutenção do fluxo.
As variáveis String do Architect suportam até 32.000 caracteres, embora os recursos disponíveis também possam limitar o tamanho prático. Para bot flows, a documentação estabelece o limite de 500 caracteres por valor de Participant Data.
Por esse motivo, normalmente prefiro salvar códigos numéricos curtos, em vez de descrições completas:
Mantenho um arquivo de correspondência documentado e versionado com o fluxo:
Também considero importante armazenar a versão do mapa utilizado:
Dessa maneira, conseguimos interpretar corretamente o rastreamento mesmo após alterações futuras no fluxo.
Data Actions
Para monitorar Data Actions, costumo utilizar a visualização Data Actions Performance, que permite analisar métricas históricas, códigos de resposta e o comportamento de ações específicas. A tela também ajuda a identificar cenários relacionados a limites de requisições e execuções concorrentes.
Quando existe um problema que impacta produção, considero essencial trabalhar em conjunto com o cliente, principalmente para correlacionar:
- Horário da falha.
- Conversation ID.
- Endpoint consumido.
- Código HTTP.
- Tempo de resposta.
- Logs do sistema de origem.
- Alterações recentes na API.
Além disso, gosto de registrar em Participant Data informações resumidas sobre as Data Actions consumidas durante a interação, como o código da ação executada, o resultado e o caminho seguido. Evito armazenar payloads completos, credenciais ou informações sensíveis.
APIs externas para rastreamento
Eu normalmente não adiciono ao fluxo uma chamada de API cujo único objetivo seja registrar o seu rastreamento.
Minha preocupação é criar uma nova dependência dentro do caminho crítico da interação. Essa chamada também estará sujeita a:
- Limites de execução e concorrência.
- Timeout.
- Indisponibilidade do endpoint.
- Erros de rede.
- Falhas de autenticação.
- Perda do próprio registro quando o serviço de logging estiver indisponível.
Nesse cenário, o mecanismo criado para rastrear o fluxo também pode falhar ou até influenciar sua execução.
Isso não significa que eu descarte o uso das Analytics APIs para investigações posteriores, relatórios ou extrações em lote. Minha ressalva é especificamente sobre executar uma chamada externa dentro da jornada apenas para produzir logs.
Na prática, minha ordem de análise costuma ser:
Essa combinação normalmente me oferece rastreabilidade suficiente sem adicionar dependências desnecessárias ao fluxo.
________________________________________________________________________________
I would like to share the approach I normally use when troubleshooting Architect flows.
My approach depends significantly on the organization I am working with and on which troubleshooting features are enabled.
The first place I usually check is the Operational Console. It allows me to identify operational events and errors related to flow executions. For events such as ARCHITECT-0002, the console can also provide a supporting link to Architect Replay Mode and indicate the affected area of the flow.
I also verify whether Historical Execution Data is enabled for the organization. When I am authorized to configure it, I normally consider the Notes level sufficient for most investigations because it provides the execution path and variable values without necessarily storing the complete input and output details for every action.
When Execution Data is not enabled, or when I need trace information to remain attached to the interaction, I use an approach similar to the one Satish described: I record the main flow steps in a variable and save the final result as Participant Data.
However, I use this approach carefully. The design must consider:
- The flow type.
- The number of steps being recorded.
- String-variable limits.
- Applicable participant-attribute limits.
- The possibility of exposing sensitive information.
- The impact on flow readability and maintenance.
For this reason, I normally store short numeric codes instead of complete descriptions:
I then maintain a documented and version-controlled mapping file:
I also recommend including the mapping version in the trace:
This ensures that the recorded path can still be interpreted correctly after future flow changes.
Data Actions
For Data Action monitoring, I normally use the Data Actions Performance view. It provides historical metrics, observed HTTP response codes, and details for individual actions.
When an issue affects production, I also work with the customer to correlate:
- Failure timestamp.
- Conversation ID.
- Consumed endpoint.
- HTTP response code.
- Response time.
- Source-system logs.
- Recent API changes.
In addition, I usually store summarized information about the Data Actions consumed during the interaction in Participant Data, such as the action code, result, and selected path. I avoid storing complete payloads, credentials, or sensitive information.
External APIs for flow tracing
I generally avoid adding an API call to the flow when its only purpose is to send trace logs to an external system.
My concern is that this introduces another dependency into the interaction's critical path. The logging request is also subject to:
- Execution and concurrency limits.
- Timeouts.
- Endpoint unavailability.
- Network errors.
- Authentication failures.
- Loss of traceability when the logging service itself is unavailable.
In that situation, the mechanism created to track the flow may also fail or even affect the customer journey.
This does not mean that I would avoid Analytics APIs for offline investigations, reporting, or batch extraction. My concern is specifically about making an external call from inside the flow solely for logging purposes.
In practice, my troubleshooting sequence is usually:
This combination normally provides enough traceability without introducing unnecessary dependencies into the flow.
------------------------------
Matheus Mendonca
------------------------------