| 1 | plugin_name: go.d.plugin |
| 2 | modules: |
| 3 | - meta: |
| 4 | id: collector-go.d.plugin-cato_networks |
| 5 | plugin_name: go.d.plugin |
| 6 | module_name: cato_networks |
| 7 | monitored_instance: |
| 8 | name: Cato Networks |
| 9 | link: https://www.catonetworks.com/ |
| 10 | icon_filename: network-wired.svg |
| 11 | categories: |
| 12 | - data-collection.networking |
| 13 | keywords: |
| 14 | - cato |
| 15 | - cato networks |
| 16 | - sase |
| 17 | - sd-wan |
| 18 | - bgp |
| 19 | - topology |
| 20 | related_resources: |
| 21 | integrations: |
| 22 | list: [] |
| 23 | info_provided_to_referring_integrations: |
| 24 | description: "" |
| 25 | overview: |
| 26 | data_collection: |
| 27 | metrics_description: | |
| 28 | This collector monitors Cato Networks accounts through the Cato GraphQL API. |
| 29 | |
| 30 | It discovers sites, collects site, device, and interface status, traffic and quality metrics, collects BGP peer status, and exposes Cato site/device/PoP/BGP topology data. |
| 31 | Metrics for each selected site are emitted under a generated virtual node named after the Cato site and keyed by the Cato account ID and site ID. Site labels are still attached to metric series for grouping and aggregation. |
| 32 | method_description: | |
| 33 | The collector uses the Cato GraphQL API endpoint with an account ID and API key. |
| 34 | supported_platforms: |
| 35 | include: [] |
| 36 | exclude: [] |
| 37 | multi_instance: true |
| 38 | additional_permissions: |
| 39 | description: | |
| 40 | A Cato API key with permission to read account snapshot, account metrics, entity lookup, and site BGP status data is required. |
| 41 | default_behavior: |
| 42 | auto_detection: |
| 43 | description: | |
| 44 | This collector does not auto-detect Cato accounts. Configure at least one job with `account_id` and `api_key`. |
| 45 | limits: |
| 46 | description: | |
| 47 | Site discovery is paginated and refreshed hourly. The optional `site_selector` filters sites before snapshot, metrics, BGP, topology, and generated site virtual-node creation. Account metrics use bounded concurrent one-site API requests to preserve per-Socket device and interface attribution. BGP status uses one per-site API request for each selected site that is not currently cached as having no BGP peers. |
| 48 | performance_impact: |
| 49 | description: | |
| 50 | The default interval is 60 seconds. Sites that return a successful BGP response with no peers are cached as non-BGP sites for about one hour, with deterministic per-site jitter across multiple collection cycles to avoid synchronized refresh bursts. If BGP is enabled on such a site, BGP metrics can appear after that cache expires. |
| 51 | setup: |
| 52 | prerequisites: |
| 53 | list: |
| 54 | - title: Cato API credentials |
| 55 | description: | |
| 56 | Create or obtain a Cato API key and account ID with read access to the required GraphQL API surfaces. |
| 57 | configuration: |
| 58 | file: |
| 59 | name: go.d/cato_networks.conf |
| 60 | options: |
| 61 | description: | |
| 62 | The following options can be defined globally: update_every, autodetection_retry. |
| 63 | folding: |
| 64 | title: Config options |
| 65 | enabled: true |
| 66 | list: |
| 67 | - name: update_every |
| 68 | description: Data collection interval, in seconds. Must be at least 60. |
| 69 | default_value: 60 |
| 70 | required: false |
| 71 | group: Collection |
| 72 | - name: autodetection_retry |
| 73 | description: Autodetection retry interval, in seconds. Set 0 to disable. |
| 74 | default_value: 0 |
| 75 | required: false |
| 76 | group: Collection |
| 77 | - name: url |
| 78 | description: Cato GraphQL API endpoint. Production endpoints must use HTTPS; HTTP is accepted only for loopback test endpoints. |
| 79 | default_value: https://api.catonetworks.com/api/v1/graphql2 |
| 80 | required: false |
| 81 | group: Target |
| 82 | - name: account_id |
| 83 | description: Cato account ID. |
| 84 | default_value: "" |
| 85 | required: true |
| 86 | group: Authentication |
| 87 | - name: api_key |
| 88 | description: Cato API key. |
| 89 | default_value: "" |
| 90 | required: true |
| 91 | group: Authentication |
| 92 | - name: timeout |
| 93 | description: HTTP request timeout. |
| 94 | default_value: 30 |
| 95 | required: false |
| 96 | group: HTTP |
| 97 | - name: proxy_url |
| 98 | description: HTTP proxy URL. Empty value uses environment proxy variables. |
| 99 | default_value: "" |
| 100 | required: false |
| 101 | group: HTTP |
| 102 | - name: site_selector |
| 103 | description: Space-separated simple patterns matched against the Cato site name when present, otherwise the site ID. Patterns use first-match ordering; put exclusions before broad includes, for example `!lab-* *`. |
| 104 | default_value: "*" |
| 105 | required: false |
| 106 | group: Cardinality |
| 107 | - name: vnode |
| 108 | description: Associates this data collection job with a Virtual Node. |
| 109 | default_value: "" |
| 110 | required: false |
| 111 | group: Virtual Node |
| 112 | examples: |
| 113 | folding: |
| 114 | title: Config |
| 115 | enabled: true |
| 116 | list: |
| 117 | - name: Basic |
| 118 | description: Collect Cato Networks account metrics and topology. |
| 119 | config: | |
| 120 | jobs: |
| 121 | - name: account |
| 122 | account_id: "12345" |
| 123 | api_key: "replace-with-cato-api-key" |
| 124 | troubleshooting: |
| 125 | problems: |
| 126 | list: |
| 127 | - name: API rate limits |
| 128 | description: | |
| 129 | Increase `update_every` or narrow `site_selector` if the Cato API reports rate limiting. |
| 130 | - name: Connection, TLS, or proxy failures |
| 131 | description: | |
| 132 | Check DNS, firewall egress, TLS inspection, proxy settings, endpoint region, and the collector logs. |
| 133 | alerts: |
| 134 | - name: cato_networks_site_disconnected |
| 135 | metric: cato_networks.site_connectivity_status |
| 136 | info: "Cato site ${label:site_name} reports disconnected connectivity status" |
| 137 | link: https://github.com/netdata/netdata/blob/master/src/health/health.d/cato_networks.conf |
| 138 | - name: cato_networks_site_degraded |
| 139 | metric: cato_networks.site_connectivity_status |
| 140 | info: "Cato site ${label:site_name} reports degraded connectivity status" |
| 141 | link: https://github.com/netdata/netdata/blob/master/src/health/health.d/cato_networks.conf |
| 142 | - name: cato_networks_site_packet_loss |
| 143 | metric: cato_networks.site_packet_loss |
| 144 | info: "Cato site ${label:site_name} packet loss over the last 10 minutes" |
| 145 | link: https://github.com/netdata/netdata/blob/master/src/health/health.d/cato_networks.conf |
| 146 | - name: cato_networks_bgp_session_down |
| 147 | metric: cato_networks.bgp_session_status |
| 148 | info: "Cato BGP session to peer ${label:peer_ip} (${label:peer_asn}) is down" |
| 149 | link: https://github.com/netdata/netdata/blob/master/src/health/health.d/cato_networks.conf |
| 150 | metrics: |
| 151 | folding: |
| 152 | title: Metrics |
| 153 | enabled: false |
| 154 | description: "" |
| 155 | availability: [] |
| 156 | scopes: |
| 157 | - name: site |
| 158 | description: These metrics refer to a Cato site. |
| 159 | labels: |
| 160 | - name: site_id |
| 161 | description: Cato site ID. |
| 162 | - name: site_name |
| 163 | description: Cato site name. |
| 164 | - name: pop_name |
| 165 | description: Cato PoP name. |
| 166 | metrics: |
| 167 | - name: cato_networks.site_connectivity_status |
| 168 | description: Site connectivity status. |
| 169 | unit: status |
| 170 | chart_type: line |
| 171 | dimensions: |
| 172 | - name: connected |
| 173 | - name: disconnected |
| 174 | - name: degraded |
| 175 | - name: unknown |
| 176 | - name: cato_networks.site_operational_status |
| 177 | description: Site operational status. |
| 178 | unit: status |
| 179 | chart_type: line |
| 180 | dimensions: |
| 181 | - name: active |
| 182 | - name: disabled |
| 183 | - name: locked |
| 184 | - name: unknown |
| 185 | - name: cato_networks.site_hosts |
| 186 | description: Site hosts. |
| 187 | unit: hosts |
| 188 | chart_type: line |
| 189 | dimensions: |
| 190 | - name: hosts |
| 191 | - name: cato_networks.site_traffic |
| 192 | description: Site traffic. |
| 193 | unit: bytes |
| 194 | chart_type: area |
| 195 | dimensions: |
| 196 | - name: upstream |
| 197 | - name: downstream |
| 198 | - name: cato_networks.site_packet_loss |
| 199 | description: Site packet loss. |
| 200 | unit: percentage |
| 201 | chart_type: line |
| 202 | dimensions: |
| 203 | - name: upstream |
| 204 | - name: downstream |
| 205 | - name: cato_networks.site_discarded_packets |
| 206 | description: Site discarded packets. |
| 207 | unit: packets |
| 208 | chart_type: line |
| 209 | dimensions: |
| 210 | - name: upstream |
| 211 | - name: downstream |
| 212 | - name: cato_networks.site_jitter |
| 213 | description: Site jitter. |
| 214 | unit: milliseconds |
| 215 | chart_type: line |
| 216 | dimensions: |
| 217 | - name: upstream |
| 218 | - name: downstream |
| 219 | - name: cato_networks.site_latency |
| 220 | description: Site latency. |
| 221 | unit: milliseconds |
| 222 | chart_type: line |
| 223 | dimensions: |
| 224 | - name: rtt |
| 225 | - name: last_mile |
| 226 | - name: cato_networks.site_last_mile_packet_loss |
| 227 | description: Site last mile packet loss. |
| 228 | unit: percentage |
| 229 | chart_type: line |
| 230 | dimensions: |
| 231 | - name: loss |
| 232 | - name: device |
| 233 | description: These metrics refer to a Cato Socket or vSocket attached to a site. |
| 234 | labels: |
| 235 | - name: site_id |
| 236 | description: Cato site ID. |
| 237 | - name: site_name |
| 238 | description: Cato site name. |
| 239 | - name: device_id |
| 240 | description: Cato device ID. |
| 241 | - name: device_name |
| 242 | description: Cato device name. |
| 243 | metrics: |
| 244 | - name: cato_networks.device_connection_status |
| 245 | description: Device connection status. |
| 246 | unit: status |
| 247 | chart_type: line |
| 248 | dimensions: |
| 249 | - name: connected |
| 250 | - name: disconnected |
| 251 | - name: interface |
| 252 | description: These metrics refer to a Cato site interface. |
| 253 | labels: |
| 254 | - name: site_id |
| 255 | description: Cato site ID. |
| 256 | - name: site_name |
| 257 | description: Cato site name. |
| 258 | - name: device_id |
| 259 | description: Cato device ID when the interface owner is known. |
| 260 | - name: device_name |
| 261 | description: Cato device name when the interface owner is known. |
| 262 | - name: interface_id |
| 263 | description: Cato interface ID. |
| 264 | - name: interface_name |
| 265 | description: Interface name. |
| 266 | metrics: |
| 267 | - name: cato_networks.interface_connection_status |
| 268 | description: Interface connection status. |
| 269 | unit: status |
| 270 | chart_type: line |
| 271 | dimensions: |
| 272 | - name: connected |
| 273 | - name: disconnected |
| 274 | - name: cato_networks.interface_tunnel_uptime |
| 275 | description: Interface tunnel uptime. |
| 276 | unit: seconds |
| 277 | chart_type: line |
| 278 | dimensions: |
| 279 | - name: uptime |
| 280 | - name: cato_networks.interface_traffic |
| 281 | description: Interface traffic. |
| 282 | unit: bytes |
| 283 | chart_type: area |
| 284 | dimensions: |
| 285 | - name: upstream |
| 286 | - name: downstream |
| 287 | - name: cato_networks.interface_packet_loss |
| 288 | description: Interface packet loss. |
| 289 | unit: percentage |
| 290 | chart_type: line |
| 291 | dimensions: |
| 292 | - name: upstream |
| 293 | - name: downstream |
| 294 | - name: cato_networks.interface_discarded_packets |
| 295 | description: Interface discarded packets. |
| 296 | unit: packets |
| 297 | chart_type: line |
| 298 | dimensions: |
| 299 | - name: upstream |
| 300 | - name: downstream |
| 301 | - name: cato_networks.interface_jitter |
| 302 | description: Interface jitter. |
| 303 | unit: milliseconds |
| 304 | chart_type: line |
| 305 | dimensions: |
| 306 | - name: upstream |
| 307 | - name: downstream |
| 308 | - name: cato_networks.interface_latency |
| 309 | description: Interface latency. |
| 310 | unit: milliseconds |
| 311 | chart_type: line |
| 312 | dimensions: |
| 313 | - name: rtt |
| 314 | - name: bgp peer |
| 315 | description: These metrics refer to a Cato site BGP peer. |
| 316 | labels: |
| 317 | - name: site_id |
| 318 | description: Cato site ID. |
| 319 | - name: site_name |
| 320 | description: Cato site name. |
| 321 | - name: peer_ip |
| 322 | description: BGP peer IP. |
| 323 | - name: peer_asn |
| 324 | description: BGP peer ASN. |
| 325 | metrics: |
| 326 | - name: cato_networks.bgp_session_status |
| 327 | description: BGP session status. |
| 328 | unit: status |
| 329 | chart_type: line |
| 330 | dimensions: |
| 331 | - name: up |
| 332 | - name: down |
| 333 | - name: unknown |
| 334 | - name: cato_networks.bgp_routes |
| 335 | description: BGP route counts. |
| 336 | unit: routes |
| 337 | chart_type: line |
| 338 | dimensions: |
| 339 | - name: accepted |
| 340 | - name: limit |
| 341 | - name: rib_out |
| 342 | - name: cato_networks.bgp_routes_limit_status |
| 343 | description: BGP route limit exceeded status. |
| 344 | unit: status |
| 345 | chart_type: line |
| 346 | dimensions: |
| 347 | - name: ok |
| 348 | - name: exceeded |