| 1 | { |
| 2 | "$schema": "http://json-schema.org/draft-07/schema#", |
| 3 | "title": "Netdata service discovery (SD) discoverer metadata.", |
| 4 | "oneOf": [ |
| 5 | { |
| 6 | "$ref": "#/$defs/entry" |
| 7 | }, |
| 8 | { |
| 9 | "type": "array", |
| 10 | "minItems": 1, |
| 11 | "items": { |
| 12 | "$ref": "#/$defs/entry" |
| 13 | } |
| 14 | } |
| 15 | ], |
| 16 | "$defs": { |
| 17 | "meta": { |
| 18 | "type": "object", |
| 19 | "description": "Information about the service discovery discoverer.", |
| 20 | "properties": { |
| 21 | "kind": { |
| 22 | "type": "string", |
| 23 | "description": "Runtime discoverer kind, matching the registry name and stock conf filename (e.g. 'snmp', 'docker', 'k8s', 'http', 'net_listeners')." |
| 24 | }, |
| 25 | "name": { |
| 26 | "type": "string", |
| 27 | "description": "Display name shown in docs, sidebar, and the SD hub page." |
| 28 | }, |
| 29 | "tagline": { |
| 30 | "type": "string", |
| 31 | "description": "One-line summary of what this discoverer finds, used in the SD hub page table. Should fit on one line in a markdown table cell." |
| 32 | }, |
| 33 | "link": { |
| 34 | "type": "string", |
| 35 | "description": "Reference link for the underlying technology or protocol (Wikipedia page, vendor page, RFC, etc.)." |
| 36 | }, |
| 37 | "icon_filename": { |
| 38 | "type": "string", |
| 39 | "description": "Icon filename hosted at https://netdata.cloud/img/." |
| 40 | } |
| 41 | }, |
| 42 | "required": ["kind", "name", "tagline", "link", "icon_filename"] |
| 43 | }, |
| 44 | "overview": { |
| 45 | "type": "object", |
| 46 | "description": "General information about the discoverer.", |
| 47 | "properties": { |
| 48 | "description": { |
| 49 | "type": "string", |
| 50 | "description": "What this discoverer does, what it monitors, and when to use it." |
| 51 | }, |
| 52 | "how_it_works": { |
| 53 | "type": "string", |
| 54 | "description": "Optional beginner on-ramp: a short, concrete explanation of the discoverer's lifecycle (probe -> sysinfo/metadata read -> rule match -> job creation). Rendered as '### How it works' under Overview." |
| 55 | }, |
| 56 | "limitations": { |
| 57 | "type": "string", |
| 58 | "description": "Optional explanation of notable limitations or behavior." |
| 59 | } |
| 60 | }, |
| 61 | "required": ["description"] |
| 62 | }, |
| 63 | "verify": { |
| 64 | "type": "object", |
| 65 | "description": "Optional 'Verify discovery worked' section, rendered as a top-level h2 between Service Rules and Troubleshooting. Use it to tell users where discovered jobs appear in the UI, how to read discoverer logs, and what success looks like.", |
| 66 | "properties": { |
| 67 | "description": { |
| 68 | "type": "string", |
| 69 | "description": "Optional intro sentence(s)." |
| 70 | }, |
| 71 | "checks": { |
| 72 | "type": "object", |
| 73 | "properties": { |
| 74 | "list": { |
| 75 | "type": "array", |
| 76 | "minItems": 1, |
| 77 | "description": "Concrete things the user can check to confirm discovery works.", |
| 78 | "items": { |
| 79 | "type": "object", |
| 80 | "properties": { |
| 81 | "name": { |
| 82 | "type": "string", |
| 83 | "description": "Check title (e.g. 'Confirm targets are appearing', 'Read the discoverer log')." |
| 84 | }, |
| 85 | "description": { |
| 86 | "type": "string", |
| 87 | "description": "Step-by-step explanation." |
| 88 | } |
| 89 | }, |
| 90 | "required": ["name", "description"] |
| 91 | } |
| 92 | } |
| 93 | }, |
| 94 | "required": ["list"] |
| 95 | } |
| 96 | }, |
| 97 | "required": ["checks"] |
| 98 | }, |
| 99 | "services_template_variable": { |
| 100 | "type": "object", |
| 101 | "properties": { |
| 102 | "name": { |
| 103 | "type": "string", |
| 104 | "description": "Variable name as used in templates, e.g. '.Port' or '.SysInfo.Name'." |
| 105 | }, |
| 106 | "type": { |
| 107 | "type": "string", |
| 108 | "description": "Variable type (typically 'string'). Document empty/zero-value semantics in description." |
| 109 | }, |
| 110 | "description": { |
| 111 | "type": "string", |
| 112 | "description": "What the variable holds, where it comes from, and what to expect when the value is empty or unset." |
| 113 | } |
| 114 | }, |
| 115 | "required": ["name", "description"] |
| 116 | }, |
| 117 | "services_evaluation_step": { |
| 118 | "type": "object", |
| 119 | "description": "One bullet describing rule evaluation behavior for this discoverer.", |
| 120 | "properties": { |
| 121 | "name": { |
| 122 | "type": "string" |
| 123 | }, |
| 124 | "description": { |
| 125 | "type": "string" |
| 126 | } |
| 127 | }, |
| 128 | "required": ["name", "description"] |
| 129 | }, |
| 130 | "services_example": { |
| 131 | "type": "object", |
| 132 | "properties": { |
| 133 | "name": { |
| 134 | "type": "string", |
| 135 | "description": "Example name." |
| 136 | }, |
| 137 | "description": { |
| 138 | "type": "string", |
| 139 | "description": "Example description." |
| 140 | }, |
| 141 | "config": { |
| 142 | "type": "string", |
| 143 | "description": "YAML snippet showing one or more entries from the 'services:' array." |
| 144 | } |
| 145 | }, |
| 146 | "required": ["name", "description", "config"] |
| 147 | }, |
| 148 | "services": { |
| 149 | "type": "object", |
| 150 | "description": "How 'services:' rules turn discovered targets into collector jobs for this discoverer. Note: shared rule semantics, the full template-function reference, and 'config_template' rendering rules live on the SD hub page; per-discoverer pages should focus on what is specific to this discoverer.", |
| 151 | "properties": { |
| 152 | "description": { |
| 153 | "type": "string", |
| 154 | "description": "Introductory text. Should explain what a rule is for THIS discoverer and link to the hub page for the shared model." |
| 155 | }, |
| 156 | "evaluation": { |
| 157 | "type": "object", |
| 158 | "description": "Optional discoverer-specific notes on rule evaluation order, skip-rules, and multi-job behavior. The shared semantics belong on the hub page; use this only when this discoverer differs (or when a clarification is worth repeating in context).", |
| 159 | "properties": { |
| 160 | "description": { |
| 161 | "type": "string" |
| 162 | }, |
| 163 | "list": { |
| 164 | "type": "array", |
| 165 | "items": { |
| 166 | "$ref": "#/$defs/services_evaluation_step" |
| 167 | } |
| 168 | } |
| 169 | } |
| 170 | }, |
| 171 | "template_variables": { |
| 172 | "type": "object", |
| 173 | "description": "Discoverer-specific variables available inside 'match' and 'config_template'. Do NOT list shared template helper functions (sprig, glob, match, etc.); those live on the hub page.", |
| 174 | "properties": { |
| 175 | "description": { |
| 176 | "type": "string" |
| 177 | }, |
| 178 | "list": { |
| 179 | "type": "array", |
| 180 | "minItems": 1, |
| 181 | "items": { |
| 182 | "$ref": "#/$defs/services_template_variable" |
| 183 | } |
| 184 | } |
| 185 | }, |
| 186 | "required": ["list"] |
| 187 | }, |
| 188 | "examples": { |
| 189 | "type": "object", |
| 190 | "description": "Worked examples of 'services:' rules for this discoverer.", |
| 191 | "properties": { |
| 192 | "description": { |
| 193 | "type": "string" |
| 194 | }, |
| 195 | "list": { |
| 196 | "type": "array", |
| 197 | "minItems": 1, |
| 198 | "items": { |
| 199 | "$ref": "#/$defs/services_example" |
| 200 | } |
| 201 | } |
| 202 | }, |
| 203 | "required": ["list"] |
| 204 | } |
| 205 | }, |
| 206 | "required": ["description", "template_variables", "examples"] |
| 207 | }, |
| 208 | "entry": { |
| 209 | "type": "object", |
| 210 | "description": "Metadata for a single service discovery discoverer.", |
| 211 | "properties": { |
| 212 | "id": { |
| 213 | "$ref": "./shared.json#/$defs/id" |
| 214 | }, |
| 215 | "meta": { |
| 216 | "$ref": "#/$defs/meta" |
| 217 | }, |
| 218 | "keywords": { |
| 219 | "$ref": "./shared.json#/$defs/keywords" |
| 220 | }, |
| 221 | "overview": { |
| 222 | "$ref": "#/$defs/overview" |
| 223 | }, |
| 224 | "setup": { |
| 225 | "$ref": "./shared.json#/$defs/full_setup" |
| 226 | }, |
| 227 | "services": { |
| 228 | "$ref": "#/$defs/services" |
| 229 | }, |
| 230 | "verify": { |
| 231 | "$ref": "#/$defs/verify" |
| 232 | }, |
| 233 | "troubleshooting": { |
| 234 | "$ref": "./shared.json#/$defs/troubleshooting" |
| 235 | } |
| 236 | }, |
| 237 | "required": [ |
| 238 | "id", |
| 239 | "meta", |
| 240 | "keywords", |
| 241 | "overview", |
| 242 | "setup", |
| 243 | "services", |
| 244 | "troubleshooting" |
| 245 | ] |
| 246 | } |
| 247 | } |
| 248 | } |