Integrazioni Marketplace
Il Marketplace ti permette di collegare servizi esterni ad Archyl e visualizzare i loro dati come widget live sulle dashboard della tua architettura. Monitora i deploy, monitora la qualità del codice, osserva le metriche e revisiona gli alert di sicurezza -- tutto direttamente accanto al tuo modello C4.
Panoramica
Le integrazioni Marketplace funzionano su tre livelli:
- Prodotti -- I servizi esterni disponibili per l'integrazione (Datadog, GitHub, SonarQube, ecc.)
- Connessioni -- Credenziali a livello di organizzazione che autenticano con l'API di un prodotto
- Widget -- Schede visive posizionate sulle dashboard del progetto che visualizzano dati live da una connessione
Una singola connessione può alimentare più widget su diversi progetti. I widget si aggiornano automaticamente ogni 30 secondi.
Prodotti Supportati
Datadog
Monitora la salute dell'infrastruttura e delle applicazioni.
| Widget | Tipo | Descrizione |
|---|---|---|
| Stato Monitor | Stato | Stato di salute dei monitor Datadog filtrati per tag |
| Query Metriche | Contatore | Valore corrente di una query metrica Datadog |
| Alert Attivi | Lista | Lista dei monitor attualmente in allarme |
| Dashboard Incorporata | Incorporamento | Dashboard o notebook Datadog incorporato |
GitHub
Monitora repository, workflow e risultati di sicurezza.
| Widget | Tipo | Descrizione |
|---|---|---|
| Stato Workflow | Stato | Stato dell'ultima esecuzione del workflow CI |
| Pull Request Aperte | Lista | PR attive con badge di stato |
| Statistiche Repository | Contatore | Stelle, fork, issue aperte o conteggio PR aperte |
| Alert Dependabot | Lista | Alert di vulnerabilità delle dipendenze aperte |
| Stato Dependabot | Stato | Gravità complessiva degli alert Dependabot |
| Alert Secret Scanning | Lista | Segreti rilevati nel repository |
| Alert Code Scanning | Lista | Risultati CodeQL o di terze parti per la scansione del codice |
| Stato Code Scanning | Stato | Salute complessiva della scansione del codice |
GitLab
Monitora pipeline, merge request e scanner di sicurezza.
| Widget | Tipo | Descrizione |
|---|---|---|
| Stato Pipeline | Stato | Stato dell'ultima esecuzione della pipeline |
| Merge Request Aperte | Lista | MR attive con stato |
| Statistiche Progetto | Contatore | Stelle, fork, issue aperte o MR aperte |
| Alert Vulnerabilità | Lista | Risultati scansione dipendenze |
| Stato Vulnerabilità | Stato | Gravità complessiva delle vulnerabilità |
| Alert SAST | Lista | Risultati analisi statica |
| Alert Secret Detection | Lista | Segreti rilevati |
| Alert DAST | Lista | Risultati analisi dinamica |
Prometheus
Interroga metriche e monitora target.
| Widget | Tipo | Descrizione |
|---|---|---|
| Query Istantanea | Contatore | Valore corrente di una query PromQL |
| Query Range | Grafico | Grafico a linee di serie temporali su un intervallo configurabile |
| Stato Target Up | Stato | Salute del target scrape per nome job |
SonarQube
Monitora qualità del codice e analisi di sicurezza.
| Widget | Tipo | Descrizione |
|---|---|---|
| Stato Quality Gate | Stato | Stato pass/fail del quality gate del progetto |
| Misure Progetto | Contatore | Coverage, bug, vulnerabilità, code smell, debito tecnico, ecc. |
| Issue | Lista | Bug, vulnerabilità e code smell per gravità |
| Security Hotspot | Lista | Posizioni nel codice che richiedono revisione di sicurezza |
| Rating di Sicurezza | Stato | Rating di sicurezza complessivo del progetto |
ArgoCD
Monitora i deploy di applicazioni Kubernetes.
| Widget | Tipo | Descrizione |
|---|---|---|
| Stato Applicazione | Stato | Salute e stato di sync di una singola app |
| Lista Applicazioni | Lista | Tutte le applicazioni con indicatori di salute e sync |
| Risorse Applicazione | Lista | Risorse Kubernetes per un'applicazione specifica |
| Conteggio Applicazioni | Contatore | Numero totale di applicazioni con filtri opzionali |
PagerDuty
Monitora incidenti, turni di reperibilità e salute dei servizi.
| Widget | Tipo | Descrizione |
|---|---|---|
| Stato Incidenti | Stato | Panoramica degli incidenti attivati e riconosciuti |
| Incidenti Attivi | Lista | Incidenti attualmente attivi con urgenza e servizio |
| Reperibilità Corrente | Lista | Membri del team attualmente di turno |
| Stato Servizi | Stato | Panoramica della salute dei servizi PagerDuty |
| Conteggio Incidenti | Contatore | Numero totale di incidenti aperti |
Configurare una Connessione
Le connessioni sono gestite a livello di organizzazione. Solo gli admin dell'organizzazione possono creare o modificare connessioni.
1. Naviga al Marketplace
Vai su Impostazioni Organizzazione e seleziona la scheda Marketplace. Tutti i prodotti disponibili sono elencati per categoria.
2. Aggiungi una Connessione
- Trova il prodotto che vuoi connettere
- Clicca su Connetti
- Inserisci un nome per la connessione (es. "Datadog Produzione" o "GitHub - Repo Backend")
- Compila le credenziali richieste
Ogni prodotto richiede campi di configurazione diversi:
| Prodotto | Campi Richiesti |
|---|---|
| Datadog | API Key, Application Key, Site URL |
| GitHub | Personal Access Token |
| GitLab | Personal Access Token, GitLab URL |
| Prometheus | Server URL |
| SonarQube | Token, Server URL |
| ArgoCD | Token, Server URL |
| PagerDuty | API Key |
3. Testa la Connessione
Clicca su Testa Connessione prima di salvare. Archyl verificherà le credenziali e mostrerà un messaggio di successo o errore. Se il test fallisce, controlla:
- Il token o la chiave API ha i permessi necessari
- L'URL del server è raggiungibile da internet
- Le credenziali non sono scadute
4. Salva
Una volta che il test è passato, clicca su Salva. La connessione è ora disponibile in tutti i progetti della tua organizzazione.
Gestione delle Connessioni
- Modifica: Aggiorna il nome o le credenziali di una connessione esistente
- Elimina: Rimuovi una connessione. I widget che la usano smetteranno di funzionare e mostreranno uno stato di errore
- Indicatori di stato: Verde (attiva), rosso (errore), grigio (disconnessa)
Puoi creare più connessioni allo stesso prodotto -- ad esempio, connessioni separate per gli account Datadog di staging e produzione.
Aggiungere Widget
I widget visualizzano dati live dalle tue connessioni sulle dashboard dei progetti.
1. Apri la Scheda Integrazioni
Nel tuo progetto, naviga alla vista Integrazioni. Clicca su Personalizza per entrare in modalità modifica.
2. Aggiungi un Widget
- Clicca sul pulsante Aggiungi Widget
- Passo 1 -- Seleziona Connessione: Scegli quale connessione usare. Le connessioni sono raggruppate per prodotto.
- Passo 2 -- Scegli Tipo Widget: Seleziona il tipo di widget (stato, contatore, lista, grafico o incorporamento). I tipi disponibili dipendono dal prodotto.
- Passo 3 -- Configura: Imposta il titolo del widget e le opzioni specifiche del prodotto
3. Configura le Opzioni del Widget
Ogni tipo di widget ha campi di configurazione specifici:
Widget GitHub richiedono:
- Owner: Organizzazione GitHub o username
- Repository: Nome del repository
- Gravità (widget sicurezza): Filtra per gravità dell'alert
Widget Datadog richiedono:
- Tag Monitor (monitor/alert): Filtro tag separati da virgola
- Query (metrica): Stringa query metrica Datadog
- Intervallo (metrica): 1h, 4h, 1d o 1w
- URL Embed (dashboard): URL dashboard condivisa
Widget Prometheus richiedono:
- Query: Espressione PromQL
- Intervallo (grafico): 15m, 1h, 4h, 1d o 1w
- Etichetta asse Y e Unità (grafico): Formattazione display opzionale
- Filtro Job (stato target): Nome job scrape
Widget SonarQube richiedono:
- Chiave Progetto: Identificatore progetto SonarQube
- Metrica (misure): coverage, bugs, vulnerabilities, code_smells, ecc.
- Gravità e Tipo Issue (issue): Filtri opzionali
Widget ArgoCD richiedono:
- Nome Applicazione (stato/risorse): Nome singola app
- Filtro Applicazione (lista/conteggio): Pattern regex che corrisponde ai nomi app
- Progetto (lista): Filtro progetto ArgoCD
- Filtro Salute (conteggio): Healthy, Degraded, Progressing, ecc.
Widget PagerDuty richiedono:
- ID Servizio (incidenti/stato): Filtro opzionale per servizio PagerDuty
- ID Policy Escalation (reperibilità): Filtro opzionale per policy di escalation
Tipi di Widget
Contatore
Visualizza un singolo valore numerico in evidenza. Usa per metriche come utilizzo CPU, conteggio richieste, percentuale di coverage o conteggio stelle.
- Numero grande formattato con unità opzionale
- Etichetta opzionale sotto il valore
- Dimensione testo adattiva alle dimensioni del widget
Stato
Mostra un indicatore di salute con codifica colore. Usa per stato CI, quality gate, salute monitor o stato di sync deploy.
- Badge con codifica colore: verde (ok), ambra (warning), rosso (critico)
- Conteggi breakdown opzionali (ok, warning, alert)
- Messaggio contestuale quando disponibile
Lista
Visualizza una lista scorrevole di elementi. Usa per pull request, alert, issue o inventari di applicazioni.
- Ogni elemento mostra titolo, sottotitolo opzionale e badge di stato
- Elementi cliccabili collegano al servizio esterno
- Badge di stato con codifica colore (successo, warning, errore, critico, in attesa)
Grafico
Renderizza un grafico a linee di serie temporali. Usa per query range Prometheus o qualsiasi metrica nel tempo.
- Supporto multi-serie con linee colorate
- Formattazione adattiva dell'asse temporale
- Tooltip al passaggio del mouse con valori formattati
- Etichetta asse Y e unità opzionali
Incorporamento
Visualizza una pagina esterna in un iframe. Usa per dashboard Datadog, pannelli Grafana o qualsiasi URL incorporabile.
- Rendering iframe completo
- Sandboxed per sicurezza
- Responsive alle dimensioni del widget
Organizzare i Widget
Sezioni
I widget sono organizzati in sezioni nominate. La sezione predefinita è Generale.
- Crea una sezione: In modalità modifica, usa il campo input sezione per aggiungere una nuova sezione
- Rinomina: Clicca l'icona matita sull'intestazione della sezione
- Elimina: Clicca l'icona cestino. I widget nella sezione eliminata si spostano in Generale
- Comprimi/Espandi: Clicca la freccia per alternare la visibilità della sezione
Riordinamento
In modalità modifica:
- Trascina widget per riposizionarli all'interno di una sezione o spostarli in una sezione diversa
- Trascina intestazioni sezione per riordinare intere sezioni
- Ridimensiona widget dal manico in basso a destra
Le posizioni dei widget e le assegnazioni alle sezioni vengono salvate automaticamente.
Griglia Widget
La griglia usa un layout a 12 colonne. I widget possono essere ridimensionati da 1 colonna a tutte le 12 colonne, e da 3 righe di altezza a qualsiasi altezza. La griglia compatta verticalmente -- i widget si impilano verso l'alto per riempire gli spazi.
Ambito
I widget possono avere ambito su tre livelli:
| Ambito | Visibilità | Caso d'Uso |
|---|---|---|
| Organizzazione | Visibile in tutti i progetti | Dashboard aziendali |
| Progetto | Visibile solo in un progetto specifico | Metriche specifiche del progetto |
| Elemento | Allegato a un elemento C4 | Monitoraggio per servizio |
I widget a livello organizzazione sono configurati dalla pagina Integrazioni di alto livello. I widget per progetto e per elemento sono configurati nella scheda Integrazioni del progetto.
Risoluzione Problemi
Il widget mostra "Credenziali non valide"
Le credenziali della connessione sono scadute o sono state revocate. Vai su Impostazioni Organizzazione > Marketplace, trova la connessione e aggiorna le credenziali. Clicca su Testa Connessione per verificare.
Il widget mostra "Impossibile caricare i dati"
Il servizio esterno potrebbe essere irraggiungibile o la query potrebbe essere non valida. Controlla:
- Il servizio è attivo e accessibile
- La configurazione della query o del filtro è corretta
- La chiave API della connessione ha il permesso di accedere alla risorsa richiesta
Nessuna connessione disponibile quando si aggiunge un widget
Le connessioni vengono create a livello di organizzazione. Se non sei un admin, chiedi all'amministratore della tua organizzazione di configurare una connessione in Impostazioni Organizzazione > Marketplace.
Best Practice
Nomina le Connessioni Chiaramente
Usa nomi descrittivi che indichino l'ambiente e lo scopo:
- "Datadog -- Produzione"
- "GitHub -- Team Backend"
- "SonarQube -- Progetto Principale"
Organizza con Sezioni
Raggruppa widget correlati in sezioni:
- "Monitoraggio" per widget Datadog e Prometheus
- "Sicurezza" per widget SonarQube e security scanning GitHub
- "CI/CD" per widget di stato workflow e deploy
- "Risposta Incidenti" per widget incidenti PagerDuty e reperibilità
Inizia con Widget di Stato
I widget di stato ti danno una panoramica rapida della salute. Aggiungi widget contatore e lista per più dettagli una volta identificate le metriche chiave.
Usa Widget con Ambito Elemento
Allega widget direttamente agli elementi C4 così i tuoi diagrammi architetturali mostrano contesto operativo live. Ad esempio, allega un widget stato workflow GitHub al container che rappresenta il tuo servizio API.
Prossimi Passi
- Gestione Release -- Tracciare i deploy attraverso la tua architettura
- Insight Architetturali -- Rilevare problemi architetturali
- Flussi -- Visualizzare come i dati si muovono nel tuo sistema