| 1 | # Define Per-Actor Highlight Paths |
| 2 | |
| 3 | ## Question |
| 4 | |
| 5 | How should a `netdata.topology.v1` producer encode highlight paths when each |
| 6 | clicked actor has its own ordered path? |
| 7 | |
| 8 | ## Inputs |
| 9 | |
| 10 | - A producer that needs `data.presentation.selection.actor_click.mode: |
| 11 | highlight_path`. |
| 12 | - An actor detail table that stores path rows. |
| 13 | - Actor row references for the clicked actor and every member of its path. |
| 14 | |
| 15 | ## Schema Choices |
| 16 | |
| 17 | Use one actor detail table with: |
| 18 | |
| 19 | - `path_owner_column`: optional `actor_ref`; the actor whose click should use |
| 20 | the row. |
| 21 | - `path_actor_column`: required `actor_ref`; the actor that appears in the |
| 22 | highlighted path. |
| 23 | - `path_order_column`: required numeric column; the deterministic path order. |
| 24 | |
| 25 | Do not point `path_actor_column` at the owner column unless every actor shares |
| 26 | one global path table. For producer-specific per-actor paths, owner and member |
| 27 | must be separate columns. |
| 28 | |
| 29 | ## Implementation Steps |
| 30 | |
| 31 | 1. Define the table type with `role: actor_detail`, `owner: actor`, and |
| 32 | `aggregation: append`. |
| 33 | 2. Add an owner actor-ref column such as `actor`. |
| 34 | 3. Add a path-member actor-ref column such as `path_actor`. |
| 35 | 4. Add a numeric order column such as `path_index`. |
| 36 | 5. Set `data.presentation.selection.actor_click` to: |
| 37 | |
| 38 | ```json |
| 39 | { |
| 40 | "mode": "highlight_path", |
| 41 | "path_table": "stream_path", |
| 42 | "path_owner_column": "actor", |
| 43 | "path_actor_column": "path_actor", |
| 44 | "path_order_column": "path_index" |
| 45 | } |
| 46 | ``` |
| 47 | |
| 48 | ## Validation |
| 49 | |
| 50 | - Validate the payload with `FUNCTION_TOPOLOGY_SCHEMA.json`. |
| 51 | - Run the topology v1 validator. It checks that owner/member columns are |
| 52 | `actor_ref` and the order column is numeric. |
| 53 | - Add a frontend fixture where two actors have different rows in the same path |
| 54 | table, then verify each click resolves only that actor's path. |
| 55 | |
| 56 | ## Gotchas |
| 57 | |
| 58 | - The owner column is intentionally optional for backward compatibility and for |
| 59 | a single shared global path. |
| 60 | - Reusing the owner column as the path-member column causes each actor click to |
| 61 | highlight only itself or direct graph neighbors, because the UI never receives |
| 62 | the ordered path members. |
| 63 | - Keep path rows as actor-owned detail data, not graph links. Graph links remain |
| 64 | the compact renderable topology; path rows drive selection behavior. |