datadog-structurizr 0.1.0__py3-none-any.whl

datadog_structurizr/__init__.py

@@ -0,0 +1,3 @@
+"""Generate C4 diagrams of a Datadog APM service as Structurizr DSL and Mermaid."""
+
+__version__ = "0.1.0"

datadog_structurizr/client.py

@@ -0,0 +1,263 @@
+"""Datadog API calls.
+
+Plain `requests` so the endpoint being hit is explicit and easy to debug.
+Once every call has succeeded, the responses replace output/raw/ as a whole,
+so a run can be replayed with --offline (no credentials, no API calls) while
+tuning the diagrams, and raw/ never mixes responses from different runs.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import sys
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+import requests
+
+from .config import Config
+
+
+class DatadogAPIError(RuntimeError):
+    """A Datadog call failed; the run stops rather than draw from partial data."""
+
+
+# A 429 is retried after the wait Datadog asks for in x-ratelimit-reset
+# (seconds, checked on a live account), at most this often and this long.
+MAX_RETRIES = 2
+MAX_WAIT_SECONDS = 60
+
+
+def _retry_wait(resp: requests.Response) -> int | None:
+    """Seconds to wait before retrying a 429, or None to give up."""
+    try:
+        wait = int(resp.headers.get("x-ratelimit-reset", ""))
+    except (TypeError, ValueError):
+        return None
+    return max(wait, 1) if wait <= MAX_WAIT_SECONDS else None
+
+
+def _send(call: Callable[..., requests.Response], url: str, **kwargs: Any) -> requests.Response:
+    """requests.get or requests.post, retrying when Datadog answers 429."""
+    for attempt in range(MAX_RETRIES + 1):
+        resp = call(url, **kwargs)
+        if resp.status_code != 429 or attempt == MAX_RETRIES:
+            return resp
+        wait = _retry_wait(resp)
+        if wait is None:
+            return resp
+        limit = resp.headers.get("x-ratelimit-name", "Datadog")
+        print(f"      rate limited ({limit}); retrying in {wait}s", file=sys.stderr)
+        time.sleep(wait)
+    return resp
+
+
+def _check(resp: requests.Response, what: str) -> None:
+    if resp.status_code != 200:
+        raise DatadogAPIError(f"Datadog API error {resp.status_code} for {what}: {resp.text[:500]}")
+
+
+def _headers(cfg: Config) -> dict[str, str]:
+    return {
+        "DD-API-KEY": cfg.api_key,
+        "DD-APPLICATION-KEY": cfg.app_key,
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+
+
+def _base(cfg: Config) -> str:
+    return f"https://api.{cfg.site}"
+
+
+def _replace_raw(cfg: Config, files: dict[str, Any]) -> None:
+    """Write the responses to a new directory, then swap it in for raw/."""
+    staging = Path(tempfile.mkdtemp(prefix=".raw-new-", dir=cfg.output_dir))
+    try:
+        for name, data in files.items():
+            (staging / f"{name}.json").write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    except BaseException:
+        shutil.rmtree(staging, ignore_errors=True)
+        raise
+    old = staging.with_name(staging.name.replace(".raw-new-", ".raw-old-"))
+    if cfg.raw_dir.exists():
+        cfg.raw_dir.rename(old)
+    staging.rename(cfg.raw_dir)
+    shutil.rmtree(old, ignore_errors=True)
+
+
+def _load(cfg: Config, name: str) -> Any:
+    path: Path = cfg.raw_dir / f"{name}.json"
+    if not path.exists():
+        raise SystemExit(f"--offline: {path} not found. Run once online first.")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _dependencies_name(cfg: Config, service: str) -> str:
+    return ("dependencies" if service == cfg.service
+            else "dependencies-" + re.sub(r"[^A-Za-z0-9._-]", "_", service))
+
+
+def fetch_service_dependencies(cfg: Config, service: str | None = None) -> dict[str, Any]:
+    """Upstream (`called_by`) and downstream (`calls`) services of one service.
+
+    `service` defaults to the target; other services (system.include) are
+    saved as raw/dependencies-<service>.json.
+
+    GET /api/v1/service_dependencies/{service}?env=&start=&end=
+    Response: {"name": "...", "calls": [...], "called_by": [...]}
+    Docs: https://docs.datadoghq.com/api/latest/service-dependencies/
+    """
+    service = service or cfg.service
+    if cfg.offline:
+        return _load(cfg, _dependencies_name(cfg, service))
+
+    end = int(time.time())
+    params = {"env": cfg.env, "start": end - cfg.lookback_hours * 3600, "end": end}
+    resp = _send(
+        requests.get, f"{_base(cfg)}/api/v1/service_dependencies/{service}",
+        headers=_headers(cfg), params=params, timeout=30,
+    )
+    _check(resp, f"service dependencies of {service}")
+    return resp.json()
+
+
+def _aggregate(cfg: Config, query: str, facets: list[tuple[str, int]]) -> list[dict[str, Any]]:
+    """Span counts grouped by facets, as [{"by": {facet: value}, "compute": {"c0": n}}]."""
+    order = {"aggregation": "count", "order": "desc", "type": "measure"}
+    body = {
+        "data": {
+            "type": "aggregate_request",
+            "attributes": {
+                "filter": {"from": f"now-{cfg.lookback_hours}h", "to": "now", "query": query},
+                "compute": [{"aggregation": "count", "type": "total"}],
+                "group_by": [{"facet": f, "limit": limit, "sort": order} for f, limit in facets],
+            },
+        }
+    }
+    resp = _send(
+        requests.post, f"{_base(cfg)}/api/v2/spans/analytics/aggregate",
+        headers=_headers(cfg), json=body, timeout=60,
+    )
+    _check(resp, f"spans aggregate ({query})")
+    # Response: {"data": [{"type": "bucket", "attributes": {"by": {...},
+    # "compute": {"c0": n}}}], "meta": {...}}, checked against the live API.
+    data = resp.json().get("data")
+    if not isinstance(data, list):
+        raise DatadogAPIError(f"spans aggregate ({query}): expected a list in 'data', "
+                              f"got {type(data).__name__}")
+    return [b.get("attributes") or {} for b in data]
+
+
+def fetch_resources(cfg: Config) -> list[dict[str, Any]]:
+    """Entry-point resources (endpoints, handlers) of the target, with hit counts.
+
+    POST /api/v2/spans/analytics/aggregate grouped by resource_name.
+    Only covers indexed spans (retention filters), so counts are relative,
+    not absolute traffic. Returns [{"resource": str, "hits": int}, ...].
+    """
+    if cfg.offline:
+        return _load(cfg, "resources")
+
+    base = f"service:{cfg.service} env:{cfg.env}"
+    # Prefer server/consumer spans so client calls (SQL, outbound HTTP) don't
+    # show up as components; fall back only when that query succeeds with no
+    # buckets (the tracer doesn't set span.kind), never after a failed call.
+    buckets = _aggregate(cfg, f"{base} @span.kind:(server OR consumer)", [("resource_name", 100)])
+    if not buckets:
+        buckets = _aggregate(cfg, base, [("resource_name", 100)])
+
+    return [
+        {
+            "resource": str(b.get("by", {}).get("resource_name", "")),
+            "hits": int((b.get("compute") or {}).get("c0") or 0),
+        }
+        for b in buckets
+        if b.get("by", {}).get("resource_name")
+    ]
+
+
+def fetch_service_definition(cfg: Config) -> dict[str, Any]:
+    """Service Catalog metadata (description, team, languages).
+
+    Optional: 404 (no definition) gives {}; any other error stops the run.
+
+    GET /api/v2/services/definitions/{service_name}
+    """
+    if cfg.offline:
+        try:
+            return _load(cfg, "definition")
+        except SystemExit:
+            return {}
+
+    resp = _send(
+        requests.get, f"{_base(cfg)}/api/v2/services/definitions/{cfg.service}",
+        headers=_headers(cfg), timeout=30,
+    )
+    if resp.status_code == 404:
+        # No definition in the Service Catalog: metadata is optional.
+        return {}
+    _check(resp, f"service definition of {cfg.service}")
+    return resp.json()
+
+
+def fetch_span_types(cfg: Config, services: list[str]) -> dict[str, dict[str, int]]:
+    """Span counts per span type for each service, from the services' own spans.
+
+    One spans aggregate grouped by service, then type. A datastore reports one
+    type (sql, redis, ...); an application service mostly web or http.
+    Returns {service: {type: span count}}; "" is spans with no type.
+    """
+    if cfg.offline:
+        try:
+            return _load(cfg, "types")
+        except SystemExit:
+            return {}  # raw/ from before types were fetched: classify by name
+    if not services:
+        return {}
+    names = " OR ".join('"' + s.replace('"', '\\"') + '"' for s in services)
+    buckets = _aggregate(cfg, f"env:{cfg.env} service:({names})",
+                         [("service", len(services)), ("type", 10)])
+    types: dict[str, dict[str, int]] = {}
+    for b in buckets:
+        by = b.get("by", {})
+        if by.get("service"):
+            types.setdefault(str(by["service"]), {})[str(by.get("type") or "")] = \
+                int((b.get("compute") or {}).get("c0") or 0)
+    return types
+
+
+@dataclass
+class Fetched:
+    deps: dict[str, Any]
+    member_deps: dict[str, dict[str, Any]]
+    resources: list[dict[str, Any]]
+    definition: dict[str, Any]
+    types: dict[str, dict[str, int]]
+
+
+def fetch_all(cfg: Config) -> Fetched:
+    """Every input of one run. Online, raw/ is replaced only after all calls succeed."""
+    deps = fetch_service_dependencies(cfg)
+    member_deps = {name: fetch_service_dependencies(cfg, name) for name in cfg.include}
+    neighbours = sorted({n for d in (deps, *member_deps.values())
+                         for n in (d.get("calls") or []) + (d.get("called_by") or [])}
+                        - {cfg.service, *cfg.include})
+    fetched = Fetched(
+        deps=deps, member_deps=member_deps,
+        resources=fetch_resources(cfg),
+        definition=fetch_service_definition(cfg),
+        types=fetch_span_types(cfg, neighbours),
+    )
+    if not cfg.offline:
+        files = {"dependencies": fetched.deps, "resources": fetched.resources,
+                 "types": fetched.types}
+        files.update((_dependencies_name(cfg, name), deps) for name, deps in fetched.member_deps.items())
+        if fetched.definition:
+            files["definition"] = fetched.definition
+        _replace_raw(cfg, files)
+    return fetched

datadog_structurizr/config.py

@@ -0,0 +1,183 @@
+"""Configuration loading and validation.
+
+Precedence, highest first: command-line flags, the --config TOML file,
+environment variables (or a .env file). Datadog keys are only read from the
+environment, never from the config file or the command line.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from dotenv import load_dotenv
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - exercised on Python 3.9/3.10 in CI
+    import tomli as tomllib
+
+# Top-level and per-table keys accepted in the config file; anything else is a typo.
+_FILE_SCHEMA: dict[str, Any] = {
+    "service": str, "env": str, "hours": int, "site": str, "output": str,
+    "ignore": list,
+    "system": {"name": str, "description": str, "include": list},
+    "person": {"enabled": bool, "name": str, "description": str},
+    "classify": {"datastores": list, "external": list, "internal": list},
+    "components": {"max": int, "strip_prefixes": list},
+}
+_SECRET_KEYS = {"api_key", "app_key", "dd_api_key", "dd_app_key", "api-key", "app-key"}
+
+
+@dataclass(frozen=True)
+class Config:
+    api_key: str
+    app_key: str
+    site: str
+    service: str
+    env: str
+    lookback_hours: int
+    output_dir: Path
+    offline: bool  # rebuild from output/raw/*.json instead of calling Datadog
+    # Model inputs. Names in include are exact; the other lists accept fnmatch globs.
+    system_name: str = ""
+    system_description: str = ""
+    include: tuple[str, ...] = ()
+    ignore: tuple[str, ...] = ()
+    datastores: tuple[str, ...] = ()
+    external: tuple[str, ...] = ()
+    internal: tuple[str, ...] = ()
+    person_enabled: bool = True
+    person_name: str = "User"
+    person_description: str = "End user of the web component."
+    max_components: int = 12  # L2 keeps this many, the last one being "Other"
+    strip_prefixes: tuple[str, ...] = ()  # path prefixes removed before grouping routes
+    source_file: Optional[Path] = field(default=None, compare=False)
+
+    @property
+    def raw_dir(self) -> Path:
+        return self.output_dir / "raw"
+
+
+def _check_schema(data: dict[str, Any], schema: dict[str, Any], where: str) -> None:
+    for key, value in data.items():
+        if key.lower() in _SECRET_KEYS:
+            raise SystemExit(f"{where}: '{key}' is not allowed here. "
+                             "Put Datadog keys in DD_API_KEY / DD_APP_KEY environment variables.")
+        if key not in schema:
+            raise SystemExit(f"{where}: unknown key '{key}'. Allowed: {', '.join(schema)}.")
+        expected = schema[key]
+        if isinstance(expected, dict):
+            if not isinstance(value, dict):
+                raise SystemExit(f"{where}: '{key}' must be a table ([{key}]).")
+            _check_schema(value, expected, f"{where} [{key}]")
+        elif expected is list:
+            if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+                raise SystemExit(f"{where}: '{key}' must be a list of strings.")
+        elif not isinstance(value, expected) or (expected is int and isinstance(value, bool)):
+            raise SystemExit(f"{where}: '{key}' must be {expected.__name__}.")
+
+
+def read_config_file(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        raise SystemExit(f"Config file not found: {path}")
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise SystemExit(f"{path}: invalid TOML: {exc}") from None
+    _check_schema(data, _FILE_SCHEMA, str(path))
+    return data
+
+
+def normalize_site(site: str) -> str:
+    """The Datadog site as the tool expects it ("datadoghq.eu"), from forms people
+    copy from the browser or the API docs: "https://api.datadoghq.eu/" or
+    "api.datadoghq.eu". The tool adds "https://api." itself."""
+    site = site.strip().lower()
+    for prefix in ("https://", "http://", "api.", "app."):
+        site = site.removeprefix(prefix)
+    return site.rstrip("/")
+
+
+def load_config(overrides: dict[str, Any] | None = None,
+                config_file: Path | None = None,
+                prompt: Callable[[str], str] | None = None) -> Config:
+    """Build the Config.
+
+    overrides: command-line values (None means not given).
+    prompt: asks for a missing service or env; pass None to never prompt.
+    """
+    # Only ./.env: without a path, load_dotenv searches upwards from this
+    # module's folder, so an editable install would read the repository's .env.
+    load_dotenv(Path.cwd() / ".env")
+    cli = {k: v for k, v in (overrides or {}).items() if v not in (None, "", ())}
+    file = read_config_file(config_file) if config_file else {}
+    system, person, classify = file.get("system", {}), file.get("person", {}), file.get("classify", {})
+    components = file.get("components", {})
+    max_components = components.get("max", 12)
+    if max_components < 2:
+        raise SystemExit(f"{config_file}: [components] 'max' must be at least 2.")
+    strip_prefixes = tuple(components.get("strip_prefixes", []))
+    for prefix in strip_prefixes:
+        if not prefix.startswith("/") or prefix == "/":
+            raise SystemExit(f"{config_file}: [components] 'strip_prefixes' entries are paths "
+                             f"such as \"/shop\", got {prefix!r}.")
+
+    def get(cli_key: str, file_value: Any, env_key: str | None, default: Any = None) -> Any:
+        if cli_key in cli:
+            return cli[cli_key]
+        if file_value is not None:
+            return file_value
+        if env_key and os.getenv(env_key):
+            return os.getenv(env_key)
+        return default
+
+    offline = bool(cli.get("OFFLINE"))
+    service = get("DD_SERVICE", file.get("service"), "DD_SERVICE")
+    env = get("DD_ENV", file.get("env"), "DD_ENV")
+    if prompt:
+        if not service:
+            service = prompt("APM service name: ").strip()
+        if not env:
+            env = prompt("APM environment (for example prod): ").strip()
+
+    api_key, app_key = os.getenv("DD_API_KEY", ""), os.getenv("DD_APP_KEY", "")
+    missing = [name for name, value in (("DD_SERVICE", service), ("DD_ENV", env)) if not value]
+    if not offline:
+        missing += [name for name, value in (("DD_API_KEY", api_key), ("DD_APP_KEY", app_key)) if not value]
+    if missing:
+        raise SystemExit(
+            f"Missing required settings: {', '.join(missing)}. "
+            "Set them in the environment or .env (see .env.example); "
+            "service and env can also come from --service/--env or the config file."
+        )
+
+    output_dir = Path(get("OUTPUT_DIR", file.get("output"), "OUTPUT_DIR", "output"))
+    (output_dir / "raw").mkdir(parents=True, exist_ok=True)
+
+    include = [*system.get("include", []), *cli.get("INCLUDE", ())]
+    return Config(
+        api_key=api_key,
+        app_key=app_key,
+        site=normalize_site(get("DD_SITE", file.get("site"), "DD_SITE", "datadoghq.com")),
+        service=service,
+        env=env,
+        lookback_hours=int(get("DD_LOOKBACK_HOURS", file.get("hours"), "DD_LOOKBACK_HOURS", 24)),
+        output_dir=output_dir,
+        offline=offline,
+        system_name=get("SYSTEM_NAME", system.get("name"), None, ""),
+        system_description=system.get("description", ""),
+        include=tuple(dict.fromkeys(n for n in include if n != service)),
+        ignore=tuple(file.get("ignore", [])),
+        datastores=tuple(classify.get("datastores", [])),
+        external=tuple(classify.get("external", [])),
+        internal=tuple(classify.get("internal", [])),
+        person_enabled="NO_PERSON" not in cli and person.get("enabled", True),
+        person_name=person.get("name", "User"),
+        person_description=person.get("description", "End user of the web component."),
+        max_components=max_components,
+        strip_prefixes=strip_prefixes,
+        source_file=config_file,
+    )

datadog_structurizr/emitter.py

@@ -0,0 +1,212 @@
+"""Write the C4 model as a Structurizr DSL workspace and as Mermaid C4 diagrams."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .model import C4Model, Element
+
+# --------------------------------------------------------------------------
+# Structurizr DSL
+# --------------------------------------------------------------------------
+
+def _q(text: str) -> str:
+    return '"' + text.replace("\\", "\\\\").replace('"', "'") + '"'
+
+
+MODEL_FILE = "datadog-model.dsl"
+VIEWS_FILE = "datadog-views.dsl"
+_GENERATED = ("# Generated by datadog-structurizr and rewritten on every run: do not edit.\n"
+              "# Add what Datadog cannot see to workspace.dsl, which includes this file.\n")
+
+
+def emit_dsl_model(model: C4Model) -> str:
+    """Elements and relationships, for !include inside the model block of workspace.dsl."""
+    lines: list[str] = []
+    w = lines.append
+    w(f"# {model.description}")
+    p = model.person
+    if p:
+        w(f"{p.key} = person {_q(p.name)} {_q(p.description)}")
+        w("")
+    s = model.target_system
+    w(f"{s.key} = softwareSystem {_q(s.name)} {_q(s.description)} {{")
+    for c in s.children:
+        w(f"    {c.key} = container {_q(c.name)} {_q(c.description)} {_q(c.technology)} {{")
+        if c.database:
+            w('        tags "Database"')
+        for comp in c.children:
+            w(f"        {comp.key} = component {_q(comp.name)} {_q(comp.description)} {_q(comp.technology)}")
+        w("    }")
+    w("}")
+    w("")
+    for e in model.systems:
+        tag = "External" if e.external else "Internal Service"
+        w(f"{e.key} = softwareSystem {_q(e.name)} {_q(e.description)} {_q(tag)}")
+    w("")
+    for r in model.relationships:
+        tech = f" {_q(r.technology)}" if r.technology else ""
+        w(f"{r.source_key} -> {r.target_key} {_q(r.description)}{tech}")
+    return _GENERATED + "\n".join(lines) + "\n"
+
+
+def emit_dsl_views(model: C4Model) -> str:
+    """The three views and styles, for !include inside the views block of workspace.dsl.
+
+    `include *` is resolved after the whole model is parsed, so the views also
+    show what workspace.dsl adds by hand.
+    """
+    lines: list[str] = []
+    w = lines.append
+    s = model.target_system
+    w(f'systemContext {s.key} "L0-SystemContext" {{')
+    w("    include *")
+    w("    autolayout lr")
+    w("}")
+    w(f'container {s.key} "L1-Containers" {{')
+    w("    include *")
+    w("    autolayout lr")
+    w("}")
+    w(f'component {model.target_container.key} "L2-Components" '
+      + _q(f"Entry points of {model.target_container.name} seen in Datadog APM "
+           "(HTTP endpoint groups and handlers), not its code structure.") + " {")
+    w("    include *")
+    w("    autolayout lr")
+    w("}")
+    w("styles {")
+    for tag, props in (("Person", ["shape Person"]),
+                       ("Database", ["shape Cylinder"]),
+                       ("External", ["background #999999", "color #ffffff"])):
+        w(f'    element "{tag}" {{')
+        for prop in props:
+            w(f"        {prop}")
+        w("    }")
+    w("}")
+    return _GENERATED + "\n".join(lines) + "\n"
+
+
+def emit_workspace(model: C4Model) -> str:
+    """The workspace.dsl written once, when none exists; never overwritten."""
+    comp = next(iter(model.target_container.children), None)
+    target = next(iter(model.systems), None)
+    example = (f"        # {comp.key} -> {target.key} \"Calls\"\n"
+               if comp and target else "")
+    return (
+        f"workspace {_q(model.name)} {{\n"
+        "    # Created once by datadog-structurizr and never overwritten: keep and edit it.\n"
+        f"    # {MODEL_FILE} and {VIEWS_FILE} are rewritten on every run.\n"
+        "\n"
+        "    model {\n"
+        f"        !include {MODEL_FILE}\n"
+        "\n"
+        "        # Elements and relationships Datadog cannot see, for example:\n"
+        f"{example}"
+        "    }\n"
+        "\n"
+        "    views {\n"
+        f"        !include {VIEWS_FILE}\n"
+        "    }\n"
+        "}\n"
+    )
+
+
+def inline_includes(workspace: str, directory: Path) -> str:
+    """workspace.dsl with the generated fragments pasted in, for the Structurizr playground."""
+    out = []
+    for line in workspace.splitlines():
+        name = line.strip().removeprefix("!include").strip()
+        if line.strip().startswith("!include") and name in (MODEL_FILE, VIEWS_FILE):
+            indent = line[:len(line) - len(line.lstrip())]
+            text = (directory / name).read_text(encoding="utf-8")
+            out += [indent + x if x else x for x in text.splitlines()]
+        else:
+            out.append(line)
+    return "\n".join(out) + "\n"
+
+
+# --------------------------------------------------------------------------
+# Mermaid C4 (renders with mmdc, GitHub, VS Code - no Java)
+# --------------------------------------------------------------------------
+
+def _m(text: str) -> str:
+    return '"' + text.replace('"', "'") + '"'
+
+
+def _owner(key: str, model: C4Model, level: str) -> str | None:
+    """Map an element key onto the element shown at this diagram level."""
+    s, c = model.target_system, model.target_container
+    if (model.person and key == model.person.key) or any(e.key == key for e in model.systems):
+        return key
+    if level == "L0":
+        return s.key
+    if any(x.key == key for x in s.children):
+        return key
+    if any(x.key == key for x in c.children):
+        return key if level == "L2" else c.key
+    return None
+
+
+def _system_line(e: Element) -> str:
+    fn = "System_Ext" if e.external else "System"
+    return f"    {fn}({e.key}, {_m(e.name)}, {_m(e.description)})"
+
+
+def _container_line(x: Element) -> str:
+    fn = "ContainerDb" if x.database else "Container"
+    return f"    {fn}({x.key}, {_m(x.name)}, {_m(x.technology)}, {_m(x.description)})"
+
+
+def _rels(model: C4Model, level: str, visible: set[str]) -> list[str]:
+    seen: set[tuple[str, str]] = set()
+    out = []
+    for r in model.relationships:
+        a, b = _owner(r.source_key, model, level), _owner(r.target_key, model, level)
+        if not a or not b or a == b or (a, b) in seen or a not in visible or b not in visible:
+            continue
+        seen.add((a, b))
+        out.append(f"    Rel({a}, {b}, {_m(r.description)}"
+                   + (f", {_m(r.technology)})" if r.technology else ")"))
+    return out
+
+
+def emit_mermaid(model: C4Model) -> dict[str, str]:
+    p, s, c = model.person, model.target_system, model.target_container
+    person_line = [f"    Person({p.key}, {_m(p.name)}, {_m(p.description)})"] if p else []
+    person_keys = {p.key} if p else set()
+
+    # L0 - System Context
+    l0 = ["C4Context", f"    title L0 System Context - {s.name}", *person_line,
+          f"    System({s.key}, {_m(s.name)}, {_m(s.description)})"]
+    l0 += [_system_line(e) for e in model.systems]
+    l0 += _rels(model, "L0", {*person_keys, s.key, *(e.key for e in model.systems)})
+
+    # L1 - Containers
+    l1 = ["C4Container", f"    title L1 Containers - {s.name}", *person_line,
+          f"    System_Boundary({s.key}, {_m(s.name)}) {{"]
+    l1 += [_container_line(x) for x in s.children]
+    l1.append("    }")
+    l1 += [_system_line(e) for e in model.systems]
+    l1 += _rels(model, "L1", {*person_keys, *(x.key for x in s.children), *(e.key for e in model.systems)})
+
+    # L2 - Components (only elements with a relationship to a component)
+    comp_keys = {x.key for x in c.children}
+    related = {k for r in model.relationships for k in (r.source_key, r.target_key)
+               if r.source_key in comp_keys or r.target_key in comp_keys} - comp_keys
+    l2 = ["C4Component", f"    title L2 Components - {c.name} (entry points seen in APM)"]
+    if person_keys & related:
+        l2 += person_line
+    l2.append(f"    Container_Boundary({c.key}, {_m(c.name)}) {{")
+    for x in c.children:
+        l2.append(f"    Component({x.key}, {_m(x.name)}, {_m(x.technology)}, {_m(x.description)})")
+    l2.append("    }")
+    l2 += [_system_line(e) for e in model.systems if e.key in related]
+    l2 += [_container_line(x) for x in s.children if x.key in related]
+    l2 += _rels(model, "L2", comp_keys | related)
+
+    layout = '    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")'
+    for diagram in (l0, l1, l2):
+        diagram.append(layout)
+    return {
+        "L0-SystemContext": "\n".join(l0) + "\n",
+        "L1-Containers": "\n".join(l1) + "\n",
+        "L2-Components": "\n".join(l2) + "\n",
+    }