Integrações do Marketplace

O Marketplace permite conectar serviços externos ao Archyl e exibir seus dados como widgets ao vivo nos dashboards da sua arquitetura. Monitore deploys, acompanhe a qualidade do código, observe métricas e revise alertas de segurança — tudo diretamente junto ao seu modelo C4.

Visão Geral

As integrações do Marketplace funcionam em três camadas:

1. Produtos — Os serviços externos disponíveis para integração (Datadog, GitHub, SonarQube etc.)
2. Conexões — Credenciais com escopo de organização que se autenticam na API de um produto
3. Widgets — Cartões visuais colocados nos dashboards dos projetos que exibem dados ao vivo de uma conexão

Uma única conexão pode alimentar vários widgets em diferentes projetos. Os widgets são atualizados automaticamente a cada 30 segundos.

Produtos Suportados

Datadog

Monitore a saúde da infraestrutura e das aplicações.

GitHub

Acompanhe repositórios, workflows e descobertas de segurança.

GitLab

Monitore pipelines, merge requests e scanners de segurança.

Prometheus

Consulte métricas e monitore alvos.

SonarQube

Acompanhe a qualidade do código e a análise de segurança.

ArgoCD

Monitore deploys de aplicações Kubernetes.

PagerDuty

Monitore incidentes, escalas de plantão e a saúde dos serviços.

Configurando uma Conexão

As conexões são gerenciadas no nível da organização. Apenas administradores da organização podem criar ou modificar conexões.

1. Navegue até o Marketplace

Vá para Configurações da Organização e selecione a aba Integrações. Todos os produtos disponíveis são listados por categoria.

2. Adicione uma Conexão

1. Encontre o produto que deseja conectar
2. Clique em Conectar
3. Insira um nome para a conexão (ex.: "Datadog Produção" ou "GitHub - Repos Backend")
4. Preencha as credenciais necessárias

Cada produto exige campos de configuração diferentes:

3. Teste a Conexão

Clique em Testar Conexão antes de salvar. O Archyl verifica as credenciais e exibe uma mensagem de sucesso ou de erro. Se o teste falhar, verifique se:

• A chave de API ou o token tem as permissões necessárias
• A URL do servidor está acessível pela internet
• As credenciais não expiraram

4. Salve

Quando o teste passar, clique em Salvar. A conexão passa a ficar disponível em todos os projetos da sua organização.

Gerenciando Conexões

• Editar: Atualize o nome ou as credenciais de uma conexão existente
• Excluir: Remova uma conexão. Os widgets que a usam param de funcionar e exibem um estado de erro
• Indicadores de status: Verde (ativa), vermelho (erro), cinza (desconectada)

Você pode criar várias conexões para o mesmo produto — por exemplo, conexões separadas para as contas Datadog de staging e de produção.

Adicionando Widgets

Os widgets exibem dados ao vivo das suas conexões nos dashboards dos projetos.

1. Abra a Aba Integrações

No seu projeto, navegue até a visualização Integrações. Clique em Personalizar para entrar no modo de edição.

2. Adicione um Widget

1. Clique no botão Adicionar Widget
2. Etapa 1 — Selecionar Conexão: Escolha qual conexão usar. As conexões são agrupadas por produto.
3. Etapa 2 — Escolher Tipo de Widget: Selecione o tipo de widget (status, contador, lista, gráfico ou embed). Os tipos disponíveis dependem do produto.
4. Etapa 3 — Configurar: Defina o título do widget e as opções específicas do produto

3. Configure as Opções do Widget

Cada tipo de widget tem campos de configuração específicos:

Widgets do GitHub exigem:

• Proprietário: Organização ou nome de usuário do GitHub
• Repositório: Nome do repositório
• Severidade (widgets de segurança): Filtra por severidade do alerta

Widgets do Datadog exigem:

• Tags do Monitor (monitores/alertas): Filtro de tags separadas por vírgula
• Consulta (métrica): String de consulta de métrica do Datadog
• Período (métrica): 1h, 4h, 1d ou 1w
• URL de Embed (dashboard): URL do dashboard compartilhado

Widgets do Prometheus exigem:

• Consulta: Expressão PromQL
• Período (gráfico): 15m, 1h, 4h, 1d ou 1w
• Rótulo do Eixo Y e Unidade (gráfico): Formatação de exibição opcional
• Filtro de Job (status do alvo): Nome do job de scrape

Widgets do SonarQube exigem:

• Chave do Projeto: Identificador do projeto no SonarQube
• Métrica (métricas): coverage, bugs, vulnerabilities, code_smells etc.
• Severidade e Tipo de Issue (issues): Filtros opcionais

Widgets do ArgoCD exigem:

• Nome da Aplicação (status/recursos): Nome de uma única aplicação
• Filtro de Aplicação (lista/contagem): Padrão regex que corresponde aos nomes das aplicações
• Projeto (lista): Filtro de projeto do ArgoCD
• Filtro de Saúde (contagem): Healthy, Degraded, Progressing etc.

Widgets do PagerDuty exigem:

• ID do Serviço (incidentes/status): Filtro opcional por serviço do PagerDuty
• ID da Política de Escalonamento (plantão): Filtro opcional por política de escalonamento

Tipos de Widget

Contador

Exibe um único valor numérico em destaque. Use para métricas como uso de CPU, contagem de requisições, porcentagem de cobertura ou contagem de stars.

• Número grande e formatado, com unidade opcional
• Rótulo opcional abaixo do valor
• Tamanho do texto se adapta às dimensões do widget

Status

Mostra um indicador de saúde com codificação por cores. Use para status de CI, quality gates, saúde de monitores ou estado de sincronização de deploys.

• Badge com código de cores: verde (ok), âmbar (alerta), vermelho (crítico)
• Contagens detalhadas opcionais (ok, alerta, crítico)
• Mensagem contextual quando disponível

Lista

Exibe uma lista rolável de itens. Use para pull requests, alertas, issues ou inventários de aplicações.

• Cada item mostra título, subtítulo opcional e badge de status
• Itens clicáveis levam ao serviço externo
• Badges de status com código de cores (sucesso, alerta, erro, crítico, pendente)

Gráfico

Renderiza um gráfico de linha de séries temporais. Use para consultas de intervalo do Prometheus ou qualquer métrica ao longo do tempo.

• Suporte a várias séries com linhas coloridas
• Formatação adaptativa do eixo de tempo
• Tooltip ao passar o mouse com valores formatados
• Rótulo e unidade do eixo Y opcionais

Embed

Exibe uma página externa em um iframe. Use para dashboards do Datadog, painéis do Grafana ou qualquer URL incorporável.

• Renderização completa em iframe
• Isolado em sandbox por segurança
• Responsivo ao tamanho do widget

Organizando Widgets

Seções

Os widgets são organizados em seções nomeadas. A seção padrão é Geral.

• Criar uma seção: No modo de edição, use o campo de seção para adicionar uma nova seção
• Renomear: Clique no ícone de lápis no cabeçalho da seção
• Excluir: Clique no ícone de lixeira. Os widgets da seção excluída vão para Geral
• Recolher/Expandir: Clique na seta para alternar a visibilidade da seção

Reordenando

No modo de edição:

• Arraste widgets para reposicioná-los dentro de uma seção ou movê-los para outra seção
• Arraste cabeçalhos de seção para reordenar seções inteiras
• Redimensione widgets pela alça no canto inferior direito

As posições dos widgets e a atribuição às seções são salvas automaticamente.

Grade de Widgets

A grade usa um layout de 12 colunas. Os widgets podem ser redimensionados de 1 coluna de largura até as 12 colunas completas, e de 3 linhas de altura até qualquer altura. A grade se compacta verticalmente — os widgets sobem para preencher os espaços vazios.

Escopo

Os widgets podem ter escopo em três níveis:

Os widgets de toda a organização são configurados na página Integrações de nível superior. Os widgets de projeto e de elemento são configurados na aba Integrações do projeto.

Resolução de Problemas

O widget mostra "Credenciais inválidas"

As credenciais da conexão expiraram ou foram revogadas. Vá em Configurações da Organização > Integrações, encontre a conexão e atualize as credenciais. Clique em Testar Conexão para verificar.

O widget mostra "Não foi possível carregar dados"

O serviço externo pode estar inacessível ou a consulta pode ser inválida. Verifique se:

• O serviço está no ar e acessível
• A configuração da consulta ou do filtro está correta
• A chave de API da conexão tem permissão para acessar o recurso solicitado

Nenhuma conexão disponível ao adicionar um widget

As conexões são criadas no nível da organização. Se você não é administrador, peça ao administrador da sua organização para configurar uma conexão em Configurações da Organização > Integrações.

Boas Práticas

Nomeie as Conexões com Clareza

Use nomes descritivos que indiquem o ambiente e a finalidade:

• "Datadog — Produção"
• "GitHub — Equipe Backend"
• "SonarQube — Projeto Principal"

Organize com Seções

Agrupe widgets relacionados em seções:

• "Monitoramento" para widgets do Datadog e do Prometheus
• "Segurança" para widgets de scanning de segurança do SonarQube e do GitHub
• "CI/CD" para widgets de status de workflow e de deploy
• "Resposta a Incidentes" para widgets de incidentes e de plantão do PagerDuty

Comece com Widgets de Status

Os widgets de status dão uma visão rápida da saúde. Adicione widgets de contador e de lista para mais detalhes depois de identificar as métricas principais.

Use Widgets com Escopo de Elemento

Vincule widgets diretamente a elementos C4 para que seus diagramas de arquitetura mostrem contexto operacional ao vivo. Por exemplo, vincule um widget de status de workflow do GitHub ao contêiner que representa o seu serviço de API.

Próximos Passos

• Gerenciamento de Releases — Rastreie deploys na sua arquitetura
• Insights de Arquitetura — Detecte problemas arquiteturais
• Fluxos — Visualize como os dados se movem pelo seu sistema