Dieser Post setzt den elften Teil fort. Architekturdiagramme zeigen Struktur — aber nicht wie es dem System gerade geht. Mit dem Overlay-Feature lassen sich externe Metriken als Heatmap direkt auf die draw.io-Elemente legen.

Das Konzept

bausteinsicht overlay apply lädt eine JSON-Datei mit Metriken und färbt die draw.io-Elemente entsprechend ein. Die Originalfarben werden in Metadaten des Diagramms gesichert — overlay remove stellt sie exakt wieder her.

Typische Anwendungsfälle:

  • Error-Rate pro Service nach einem Incident

  • Test-Coverage pro Modul vor einem Release

  • Latenz-P99 aus Prometheus/Datadog

  • Deployment-Frequenz aus dem CI-System

Metriken-Datei vorbereiten

Die Metriken liegen in einer JSON-Datei mit festem Schema:

{
  "meta": {
    "source": "Datadog",
    "generated": "2025-06-11T06:00:00Z",
    "metric_descriptions": {
      "error_rate": "HTTP 5xx Rate (letzte 1h)",
      "p99_latency_ms": "P99 Latenz in Millisekunden"
    }
  },
  "metrics": [
    {
      "id": "shop.frontend",
      "values": {
        "error_rate": 0.02,
        "p99_latency_ms": 145
      }
    },
    {
      "id": "authservice",
      "values": {
        "error_rate": 0.08,
        "p99_latency_ms": 312
      }
    },
    {
      "id": "paymentservice",
      "values": {
        "error_rate": 0.41,
        "p99_latency_ms": 890
      }
    },
    {
      "id": "shop.db",
      "values": {
        "error_rate": 0.01,
        "p99_latency_ms": 22
      }
    }
  ]
}

Die id-Felder müssen den Element-IDs im Modell entsprechen. Elemente ohne Eintrag in der Metriken-Datei bleiben unverändert.

bausteinsicht overlay list

Welche Metriken sind in der Datei verfügbar?

bausteinsicht overlay list metrics.json

Ausgabe:

📊 Metrics from: Datadog (2025-06-11T06:00:00Z)

Available metrics (4 elements):
  • error_rate: HTTP 5xx Rate (letzte 1h)
  • p99_latency_ms: P99 Latenz in Millisekunden

bausteinsicht overlay apply

# Error-Rate als Heatmap anzeigen
bausteinsicht overlay apply metrics.json --metric error_rate

# Latenz als Heatmap anzeigen
bausteinsicht overlay apply metrics.json --metric p99_latency_ms

# Andere draw.io-Datei als Ziel
bausteinsicht overlay apply metrics.json --metric error_rate \
  --output architecture-incident.drawio

Bausteinsicht berechnet automatisch die Farbskala: niedrige Werte werden grün, hohe Werte rot eingefärbt (Standard-Farbschema).

Nach dem Apply sieht das Diagramm so aus (farblich):

shop.frontend   → hellgrün  (error_rate: 0.02 — niedrig)
authservice     → gelb      (error_rate: 0.08 — mittel)
paymentservice  → rot       (error_rate: 0.41 — kritisch)
shop.db         → grün      (error_rate: 0.01 — sehr niedrig)

Das Diagramm öffnet sich in draw.io mit den Heatmap-Farben. Elemente ohne Metrik-Eintrag bleiben in ihrer Originalfarbe.

JSON-Ausgabe

bausteinsicht overlay apply metrics.json --metric error_rate --format json
{
  "status": "applied",
  "metric": "error_rate",
  "file": "architecture.drawio"
}

bausteinsicht overlay remove

Heatmap entfernen und Originalfarben wiederherstellen:

bausteinsicht overlay remove

Bausteinsicht liest die gesicherten Originalstile aus den draw.io-Metadaten und stellt jeden Element-Style exakt wieder her. Keine manuelle Farbanpassung nötig.

Originalfarben werden beim ersten overlay apply in draw.io-Elementmetadaten gespeichert. Solange kein overlay remove ausgeführt wird, bleiben sie dort — auch wenn die draw.io-Datei in Git committed wird.

Metriken aus externen Quellen erzeugen

Die Metriken-JSON kann aus jedem System kommen. Beispiele:

Prometheus / Grafana

# HTTP Error-Rate der letzten Stunde als JSON exportieren
promtool query instant \
  'rate(http_requests_total{status=~"5.."}[1h]) / rate(http_requests_total[1h])' \
  | jq '...' > metrics.json

CI-System (Test Coverage)

# Coverage-Report aus Go Test in das Overlay-Format konvertieren
go test ./... -coverprofile=coverage.out
# Dann Coverage per Service aggregieren und in metrics.json schreiben

GitHub Actions: Automatisches Overlay vor Review

- name: Fetch metrics and apply overlay
  run: |
    curl -s "$METRICS_API_URL" > /tmp/metrics.json
    bausteinsicht overlay apply /tmp/metrics.json --metric error_rate

- name: Upload diagram with overlay
  uses: actions/upload-artifact@v4
  with:
    name: architecture-with-metrics
    path: architecture.drawio

Grenzen

  • Bausteinsicht erzeugt keine Metriken — es visualisiert nur externe Daten

  • Die Farbskala ist linear (Min → Grün, Max → Rot); keine logarithmische Skalierung

  • Nur numerische Metriken werden unterstützt — keine kategorischen Werte

  • Das --metric-Flag wählt genau eine Metrik pro Apply; für mehrere Metriken mehrfach aufrufen

Beispiel-Modell

Das Basis-Modell für die Overlay-Beispiele in diesem Teil liegt unter teil_12.jsonc.

So sieht das Ergebnis in draw.io aus (bausteinsicht sync):

Das draw.io-File dafür findest du hier: teil_12.drawio

Generierte PNG-Dateien via bausteinsicht export --image-format png:

context
services

Generierte PlantUML-Diagramme via bausteinsicht export-diagram:

Diagram
Diagram

Was als nächstes kommt

Offizielle Dokumentation: User Manual · Tutorial auf doctoolchain.org