Integraciones del Marketplace
El Marketplace te permite conectar servicios externos a Archyl y mostrar sus datos como widgets en tiempo real en tus paneles de arquitectura. Monitorea despliegues, rastrea la calidad del código, observa métricas y revisa alertas de seguridad — todo directamente junto a tu modelo C4.
Descripción general
Las integraciones del marketplace funcionan en tres capas:
- Productos — Los servicios externos disponibles para integración (Datadog, GitHub, SonarQube, etc.)
- Conexiones — Credenciales a nivel de organización que se autentican con la API de un producto
- Widgets — Tarjetas visuales colocadas en los paneles de proyecto que muestran datos en tiempo real desde una conexión
Una sola conexión puede alimentar múltiples widgets en diferentes proyectos. Los widgets se actualizan automáticamente cada 30 segundos.
Productos soportados
Datadog
Monitorea la infraestructura y la salud de las aplicaciones.
| Widget | Tipo | Descripción |
|---|---|---|
| Estado de monitores | Estado | Salud de los monitores Datadog filtrados por tag |
| Consulta de métricas | Contador | Valor actual de una consulta de métricas Datadog |
| Alertas activas | Lista | Lista de monitores actualmente activados |
| Dashboard integrado | Embed | Dashboard o notebook de Datadog integrado |
GitHub
Rastrea repositorios, workflows y hallazgos de seguridad.
| Widget | Tipo | Descripción |
|---|---|---|
| Estado del workflow | Estado | Estado de la última ejecución del workflow CI |
| Pull requests abiertas | Lista | PRs activas con badges de estado |
| Estadísticas del repositorio | Contador | Stars, forks, issues abiertas o PRs abiertas |
| Alertas Dependabot | Lista | Alertas de vulnerabilidad de dependencias |
| Estado Dependabot | Estado | Severidad general de alertas Dependabot |
| Alertas Secret Scanning | Lista | Secretos detectados en el repositorio |
| Alertas Code Scanning | Lista | Hallazgos de CodeQL o análisis de terceros |
| Estado Code Scanning | Estado | Salud general del análisis de código |
GitLab
Monitorea pipelines, merge requests y escáneres de seguridad.
| Widget | Tipo | Descripción |
|---|---|---|
| Estado del pipeline | Estado | Estado de la última ejecución del pipeline |
| Merge requests abiertas | Lista | MRs activas con estado |
| Estadísticas del proyecto | Contador | Stars, forks, issues abiertas o MRs abiertas |
| Alertas de vulnerabilidad | Lista | Hallazgos del análisis de dependencias |
| Estado de vulnerabilidades | Estado | Severidad general de vulnerabilidades |
| Alertas SAST | Lista | Hallazgos del análisis estático |
| Alertas de detección de secretos | Lista | Secretos detectados |
| Alertas DAST | Lista | Hallazgos del análisis dinámico |
Prometheus
Consulta métricas y monitorea objetivos.
| Widget | Tipo | Descripción |
|---|---|---|
| Consulta instantánea | Contador | Valor actual de una consulta PromQL |
| Consulta de rango | Gráfico | Gráfico de líneas de series temporales en un rango configurable |
| Estado de objetivos | Estado | Salud de los objetivos de scraping por nombre de job |
SonarQube
Rastrea la calidad del código y el análisis de seguridad.
| Widget | Tipo | Descripción |
|---|---|---|
| Estado Quality Gate | Estado | Estado aprobado/rechazado del quality gate del proyecto |
| Medidas del proyecto | Contador | Cobertura, bugs, vulnerabilidades, code smells, deuda técnica, etc. |
| Issues | Lista | Bugs, vulnerabilidades y code smells por severidad |
| Security Hotspots | Lista | Ubicaciones de código que requieren revisión de seguridad |
| Calificación de seguridad | Estado | Calificación de seguridad general del proyecto |
ArgoCD
Monitorea despliegues de aplicaciones Kubernetes.
| Widget | Tipo | Descripción |
|---|---|---|
| Estado de la aplicación | Estado | Salud y estado de sincronización de una aplicación |
| Lista de aplicaciones | Lista | Todas las aplicaciones con indicadores de salud y sincronización |
| Recursos de la aplicación | Lista | Recursos Kubernetes para una aplicación específica |
| Contador de aplicaciones | Contador | Número total de aplicaciones con filtros opcionales |
PagerDuty
Monitorea incidentes, turnos de guardia y la salud de los servicios.
| Widget | Tipo | Descripción |
|---|---|---|
| Estado de incidentes | Estado | Vista general de incidentes activados y reconocidos |
| Incidentes activos | Lista | Incidentes activos con urgencia y servicio |
| Guardia actual | Lista | Miembros del equipo actualmente de guardia |
| Estado de servicios | Estado | Vista general de la salud de los servicios PagerDuty |
| Contador de incidentes | Contador | Número total de incidentes abiertos |
Configurar una conexión
Las conexiones se gestionan a nivel de organización. Solo los administradores pueden crear o modificar conexiones.
1. Navegar al Marketplace
Ve a Configuración de la organización y selecciona la pestaña Marketplace. Todos los productos disponibles se listan por categoría.
2. Agregar una conexión
- Encuentra el producto que deseas conectar
- Haz clic en Conectar
- Ingresa un nombre para la conexión (ej.: "Datadog Producción" o "GitHub - Equipo Backend")
- Completa las credenciales requeridas
Cada producto requiere campos de configuración diferentes:
| Producto | Campos requeridos |
|---|---|
| Datadog | Clave API, Clave de aplicación, URL del sitio |
| GitHub | Token de acceso personal |
| GitLab | Token de acceso personal, URL de GitLab |
| Prometheus | URL del servidor |
| SonarQube | Token, URL del servidor |
| ArgoCD | Token, URL del servidor |
| PagerDuty | Clave API |
3. Probar la conexión
Haz clic en Probar conexión antes de guardar. Archyl verificará las credenciales y mostrará un mensaje de éxito o error. Si la prueba falla, verifica:
- Que la clave API o token tenga los permisos requeridos
- Que la URL del servidor sea accesible desde internet
- Que las credenciales no hayan expirado
4. Guardar
Una vez que la prueba pase, haz clic en Guardar. La conexión estará disponible en todos los proyectos de tu organización.
Gestionar conexiones
- Editar: Actualiza el nombre o las credenciales de una conexión existente
- Eliminar: Elimina una conexión. Los widgets que la usan dejarán de funcionar y mostrarán un error
- Indicadores de estado: Verde (activa), rojo (error), gris (desconectada)
Puedes crear múltiples conexiones al mismo producto — por ejemplo, conexiones separadas para las cuentas de Datadog de staging y producción.
Agregar widgets
Los widgets muestran datos en tiempo real de tus conexiones en los paneles de proyecto.
1. Abrir la pestaña Integraciones
En tu proyecto, navega a la vista Integraciones. Haz clic en Personalizar para entrar en modo edición.
2. Agregar un widget
- Haz clic en el botón Agregar widget
- Paso 1 — Seleccionar conexión: Elige qué conexión usar. Las conexiones están agrupadas por producto.
- Paso 2 — Elegir tipo de widget: Selecciona el tipo de widget (estado, contador, lista, gráfico o embed). Los tipos disponibles dependen del producto.
- Paso 3 — Configurar: Define el título del widget y las opciones específicas del producto
3. Configurar opciones del widget
Cada tipo de widget tiene campos de configuración específicos:
Widgets de GitHub requieren:
- Propietario: Organización o nombre de usuario de GitHub
- Repositorio: Nombre del repositorio
- Severidad (widgets de seguridad): Filtrar por severidad de alertas
Widgets de Datadog requieren:
- Tags de monitores (monitores/alertas): Filtro por tags separados por comas
- Consulta (métrica): Cadena de consulta de métricas Datadog
- Período (métrica): 1h, 4h, 1d o 1w
- URL de integración (dashboard): URL del dashboard compartido
Widgets de Prometheus requieren:
- Consulta: Expresión PromQL
- Período (gráfico): 15m, 1h, 4h, 1d o 1w
- Etiqueta del eje Y y Unidad (gráfico): Formato de visualización opcional
- Filtro de job (estado de objetivos): Nombre del job de scraping
Widgets de SonarQube requieren:
- Clave del proyecto: Identificador del proyecto SonarQube
- Métrica (medidas): cobertura, bugs, vulnerabilidades, code_smells, etc.
- Severidad y Tipo de issue (issues): Filtros opcionales
Widgets de ArgoCD requieren:
- Nombre de la aplicación (estado/recursos): Nombre de una sola aplicación
- Filtro de aplicaciones (lista/contador): Patrón regex para nombres de aplicaciones
- Proyecto (lista): Filtro por proyecto ArgoCD
- Filtro de salud (contador): Healthy, Degraded, Progressing, etc.
Widgets de PagerDuty requieren:
- ID del servicio (incidentes/estado): Filtro opcional por servicio PagerDuty
- ID de política de escalamiento (guardia): Filtro opcional por política de escalamiento
Tipos de widgets
Contador
Muestra un valor numérico único de forma prominente. Úsalo para métricas como uso de CPU, conteo de peticiones, porcentaje de cobertura o conteo de estrellas.
- Número grande formateado con unidad opcional
- Etiqueta opcional debajo del valor
- Tamaño de texto adaptado a las dimensiones del widget
Estado
Muestra un indicador de salud con código de colores. Úsalo para estado de CI, quality gates, salud de monitores o estado de sincronización de despliegues.
- Badge con colores: verde (ok), ámbar (advertencia), rojo (crítico)
- Conteos de detalle opcionales (ok, advertencia, alerta)
- Mensaje contextual cuando esté disponible
Lista
Muestra una lista desplazable de elementos. Úsalo para pull requests, alertas, issues o inventarios de aplicaciones.
- Cada elemento muestra título, subtítulo opcional y badge de estado
- Los elementos clicables enlazan al servicio externo
- Badges de estado con colores (éxito, advertencia, error, crítico, pendiente)
Gráfico
Renderiza un gráfico de líneas de series temporales. Úsalo para consultas de rango de Prometheus o cualquier métrica a lo largo del tiempo.
- Soporte multi-series con líneas de colores
- Formato adaptativo del eje temporal
- Tooltip al pasar el cursor con valores formateados
- Etiqueta del eje Y y unidad opcionales
Embed
Muestra una página externa en un iframe. Úsalo para dashboards de Datadog, paneles de Grafana o cualquier URL integrable.
- Renderizado completo en iframe
- Sandboxeado por seguridad
- Responsivo al tamaño del widget
Organizar widgets
Secciones
Los widgets se organizan en secciones con nombre. La sección por defecto es General.
- Crear una sección: En modo edición, usa el campo de entrada para agregar una nueva sección
- Renombrar: Haz clic en el ícono de lápiz en el encabezado de la sección
- Eliminar: Haz clic en el ícono de papelera. Los widgets de la sección eliminada se mueven a General
- Colapsar/Expandir: Haz clic en el chevron para alternar la visibilidad de la sección
Reordenamiento
En modo edición:
- Arrastra widgets para reposicionarlos dentro de una sección o moverlos a otra sección
- Arrastra encabezados de sección para reordenar secciones completas
- Redimensiona widgets desde el controlador inferior derecho
Las posiciones de los widgets y las asignaciones de sección se guardan automáticamente.
Cuadrícula de widgets
La cuadrícula usa un layout de 12 columnas. Los widgets pueden redimensionarse desde 1 columna hasta las 12 columnas de ancho, y desde 3 filas de alto hasta cualquier altura. La cuadrícula se compacta verticalmente — los widgets se apilan hacia arriba para llenar espacios.
Alcance
Los widgets pueden definirse en tres niveles:
| Alcance | Visibilidad | Caso de uso |
|---|---|---|
| Organización | Visible en todos los proyectos | Paneles corporativos |
| Proyecto | Visible solo en un proyecto específico | Métricas específicas del proyecto |
| Elemento | Adjunto a un elemento C4 | Monitoreo por servicio |
Los widgets de organización se configuran desde la página de Integraciones de nivel superior. Los widgets de proyecto y elemento se configuran dentro de la pestaña Integraciones del proyecto.
Solución de problemas
El widget muestra "Credenciales inválidas"
Las credenciales de la conexión han expirado o han sido revocadas. Ve a Configuración de la organización > Marketplace, encuentra la conexión y actualiza las credenciales. Haz clic en Probar conexión para verificar.
El widget muestra "No se pudieron cargar los datos"
El servicio externo puede ser inaccesible o la consulta puede ser inválida. Verifica:
- Que el servicio esté activo y accesible
- Que la configuración de la consulta o filtro sea correcta
- Que la clave API de la conexión tenga permiso para acceder al recurso solicitado
No hay conexiones disponibles al agregar un widget
Las conexiones se crean a nivel de organización. Si no eres administrador, pide al administrador de tu organización que configure una conexión en Configuración de la organización > Marketplace.
Mejores prácticas
Nombra las conexiones claramente
Usa nombres descriptivos que indiquen el entorno y el propósito:
- "Datadog — Producción"
- "GitHub — Equipo Backend"
- "SonarQube — Proyecto Principal"
Organiza con secciones
Agrupa widgets relacionados en secciones:
- "Monitoreo" para widgets de Datadog y Prometheus
- "Seguridad" para widgets de SonarQube y GitHub security scanning
- "CI/CD" para widgets de estado de workflow y despliegue
- "Respuesta a incidentes" para widgets de PagerDuty de incidentes y guardia
Comienza con widgets de Estado
Los widgets de estado te dan una vista rápida de la salud. Agrega widgets de contador y lista para más detalle una vez que hayas identificado las métricas clave.
Usa widgets con alcance de elemento
Adjunta widgets directamente a elementos C4 para que tus diagramas de arquitectura muestren contexto operacional en tiempo real. Por ejemplo, adjunta un widget de estado de workflow de GitHub al contenedor que representa tu servicio de API.
Próximos pasos
- Gestión de releases — Rastrea despliegues a través de tu arquitectura
- Insights de arquitectura — Detecta problemas arquitectónicos
- Flujos — Visualiza cómo los datos fluyen a través de tu sistema