| 1 | # Add Graph Presentation To A Topology |
| 2 | |
| 3 | ## Question |
| 4 | |
| 5 | How should a topology producer add polished graph presentation to |
| 6 | `netdata.topology.v1` without making the UI domain-specific? |
| 7 | |
| 8 | ## Inputs |
| 9 | |
| 10 | - A topology producer that emits `netdata.topology.v1`. |
| 11 | - Actor and link compact tables with required `type` columns. |
| 12 | - Type registry entries under `data.types`. |
| 13 | - Optional evidence and actor-detail tables used by port bullets or |
| 14 | highlight-path behavior. |
| 15 | |
| 16 | ## Schema Choices |
| 17 | |
| 18 | - Put actor visuals in `data.types.actor_types.<id>.presentation`. |
| 19 | - Put link visuals in `data.types.link_types.<id>.presentation`. |
| 20 | - Put port bullet visuals in `data.types.port_types.<id>.presentation`. |
| 21 | - Put cross-type graph behavior in `data.presentation`. |
| 22 | - Use only schema-defined tokens for colors, icons, opacity, width, line style, |
| 23 | curves, and arrows. |
| 24 | - Use `label_policy.columns` for actor labels. Do not use canonical identity |
| 25 | arrays as display text. |
| 26 | - Use `ports.sources[]` when `ports.show_bullets` is true. |
| 27 | - Use `selection.actor_click.mode: highlight_path` only with path table, |
| 28 | path-member actor-column, and order-column references. Add an owner actor |
| 29 | column when the same table stores different paths for different clicked |
| 30 | actors. |
| 31 | |
| 32 | ## Implementation Steps |
| 33 | |
| 34 | 1. Define type-level presentation for every actor type that should have a |
| 35 | domain-specific visual profile. |
| 36 | 2. Define link presentation for every renderable link type, including direction |
| 37 | arrow and curve tokens. |
| 38 | 3. Define `port_types` and `ports.sources[]` together: |
| 39 | - `source: links` reads bullets from the graph links table; |
| 40 | - `source: evidence` reads bullets from a named evidence type; |
| 41 | - `source: actor_table` reads bullets from a named actor detail table. |
| 42 | 4. Make `name_column` a scalar display column. Do not use `actor_ref`, |
| 43 | `link_ref`, `evidence_ref`, `array`, or `json` as bullet labels. |
| 44 | 5. Add graph-level `data.presentation.legend`, `port_fields`, `scale_keys`, and |
| 45 | `selection.actor_click`. |
| 46 | 6. Update producer tests or fixtures so the new presentation path is exercised. |
| 47 | |
| 48 | ## Validation |
| 49 | |
| 50 | - Validate JSON against `src/plugins.d/FUNCTION_TOPOLOGY_SCHEMA.json`. |
| 51 | - Run `topologyv1.ValidateDecodedResponse()` or the function-validation tool so |
| 52 | semantic references are checked. |
| 53 | - Add negative tests for: |
| 54 | - missing label-policy columns; |
| 55 | - non-display label columns; |
| 56 | - missing port-bullet source tables; |
| 57 | - bad highlight-path columns; |
| 58 | - invalid token values. |
| 59 | - Check C producers with the compile command from `build/compile_commands.json` |
| 60 | using `-fsyntax-only` when a full local build is blocked. |
| 61 | |
| 62 | ## Gotchas |
| 63 | |
| 64 | - Presentation is production payload data, not compatibility reconstruction |
| 65 | data. |
| 66 | - Type ids are producer-local until Cloud aggregation namespaces and |
| 67 | canonicalizes them. |
| 68 | - `profile_version` is diagnostic. Do not use it to drop facts or rows. |
| 69 | - If a presentation source depends on optional runtime data, still declare a |
| 70 | stable table/evidence type so validators can catch typos. |
| 71 | - Sensitive identifiers may exist in topology detail tables. Do not reference |
| 72 | them in `label_policy`, graph hover, port bullet labels, logs, docs, SOWs, or |
| 73 | durable review artifacts. |