Cisco Meraki

Cisco Meraki

Plugin: go.d.plugin Module: meraki

Overview

Monitor the availability of every device in a Cisco Meraki organization through the Meraki Dashboard API, with each device shown as its own Netdata node.

• Device availability: the status Meraki Dashboard reports for each device: online, alerting, offline or dormant.
• Inventory: how many devices are assigned to the organization’s networks, and which ones.
• Fleet filtering: device nodes and charts carry organization, network, model and product type labels, so a large fleet can be grouped and filtered.

Every device type Meraki reports availability for is covered, including security appliances (MX), switches (MS), wireless access points (MR), cameras (MV), sensors (MT) and cellular gateways (MG).

The collector sends read-only HTTPS requests to the Meraki Dashboard API in the cloud, authenticated with an API key. It never connects to the devices: the Agent needs outbound HTTPS (port 443) to the regional API host and to the Meraki shard hosts the API redirects to, such as n123.meraki.com.

Every collection (every 5 minutes by default) reads these API operations completely, page by page:

When a job starts, one small getOrganizationDevices request checks that the API key can reach the organization.

This collector is supported on all platforms.

This collector supports collecting metrics from multiple instances of this integration.

The collector needs an API key whose owner has at least read-only access to the organization. A Meraki API key acts with the permissions of the Dashboard administrator who created it; the collector only reads.

Default Behavior

Auto-Detection

Nothing is detected automatically: each job monitors the one organization set in organization_id, with the API key you configure. Within that organization, every collection finds all assigned devices and adds a node for each new one.

Limits

• Five-minute data. Meraki refreshes device availability every 5 minutes and gives no sample time, so an update_every below 300 seconds repeats the same values instead of adding detail.
• Shared API budget. Meraki allows 10 requests per second per organization and 100 per source IP address, shared with every other application using them. The collector sends at most 10 requests per second per job, and after a 429 Too Many Requests answer it sends nothing until the Retry-After wait Meraki requested has passed. See Meraki API rate limits.

Performance Impact

The load on the Agent host is negligible. On the Meraki side, each operation costs one request per page, plus one for each redirect Meraki answers with:

An organization with 2,500 devices in 40 networks takes 1 + 1 + 3 + 3 = 8 requests per collection. Increase update_every to make fewer requests; increase timeout if a very large organization cannot finish within it.

Every assigned device becomes a Netdata node: an organization with 2,000 devices adds 2,000 nodes.

Setup

You can configure the meraki collector in two ways:

Important

UI configuration requires paid Netdata Cloud plan.

Prerequisites

Enable Dashboard API access for the organization

API requests are rejected until the organization allows them. In Meraki Dashboard, open Organization > Settings and enable Dashboard API access. See How to use the Meraki Dashboard API.

Create an API key for a read-only administrator

A Meraki API key has the permissions of the administrator who creates it. Use a Dashboard administrator account with read-only access to the organization, and generate an API key from that account’s My profile page. Keep the key out of the configuration file: put it in an environment variable of the Netdata service or in a file readable by the netdata user.

To verify the key, list the organizations it can see with the command shown for the organization_id option.

Allow the Agent’s address if the organization restricts API access by IP

This applies only when the organization limits Dashboard API access to specific source addresses. Add the public IP address the Agent’s requests leave from; otherwise organization requests fail with HTTP 403.

Configuration

Options

Configure one organization per job. The following options can be defined globally: update_every, autodetection_retry.

url

Use the API endpoint of the region that hosts the organization:

The URL must use HTTPS with the path exactly /api/v1 (a prefix such as /meraki/api/v1 is not accepted), without credentials, query or fragment.

A private endpoint or reverse proxy in front of the API also works, with one condition. Meraki’s redirects and next-page links point at Meraki hosts, and with a custom endpoint the collector follows them only within that endpoint. The proxy must therefore rewrite the Location and Link headers to its own address; otherwise every list longer than one page fails with invalid pagination target.

organization_id

The ID of the organization, not its name. The organizations an API key can see, with their IDs, are listed by the command below; for an organization in another region, replace the host with the one in url.

curl -s -H "Authorization: Bearer $MERAKI_API_KEY" https://api.meraki.com/api/v1/organizations

bearer_token_file

Use this when a secret manager rotates the key in place: the next request uses the new key without a restart. The file must be readable by the netdata user.

proxy_url

If the proxy URL contains credentials, use a secret reference such as ${env:MERAKI_PROXY_URL} instead of entering the authenticated URL directly into the form.

via UI

Configure the meraki collector from the Netdata web interface:

1. Go to Nodes.
2. Select the node where you want the meraki data-collection job to run and click the :gear: (Configure this node). That node will run the data collection.
3. The Collectors → Jobs view opens by default.
4. In the Search box, type meraki (or scroll the list) to locate the meraki collector.
5. Click the + next to the meraki collector to add a new job.
6. Fill in the job fields, then click Test to verify the configuration and Submit to save.
   • Test validates the provided settings and checks the collector’s startup prerequisites. Successful validation does not guarantee that every metric will be available during collection.
   • If it fails, an error message appears with details (for example, connection refused, timeout, or command execution errors), so you can adjust and retest.

via File

The configuration file name for this integration is go.d/meraki.conf.

The file format is YAML. Generally, the structure is:

update_every: 1
autodetection_retry: 0
jobs:
  - name: some_name1
  - name: some_name2

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config go.d/meraki.conf

Examples

Basic

Monitor one organization, with the API key read from an environment variable.

jobs:
  - name: meraki
    organization_id: "123456"
    api_key: ${env:MERAKI_API_KEY}

API key in a rotated file

Read the key from a file that a secret manager rotates. The file is read again for every request.

jobs:
  - name: meraki
    organization_id: "123456"
    bearer_token_file: /run/secrets/meraki_api_key

Regional API endpoint

Monitor an organization hosted outside the global region, here Canada.

jobs:
  - name: meraki-canada
    url: https://api.meraki.ca/api/v1
    organization_id: "123456"
    api_key: ${env:MERAKI_API_KEY}

Through an HTTP proxy

Reach the API through an outbound proxy.

jobs:
  - name: meraki
    organization_id: "123456"
    api_key: ${env:MERAKI_API_KEY}
    proxy_url: http://proxy.example.com:3128

Several organizations

One job per organization. Each organization has its own API budget; the jobs share the per-IP budget.

jobs:
  - name: meraki-hq
    organization_id: "123456"
    api_key: ${env:MERAKI_API_KEY}

  - name: meraki-retail
    organization_id: "654321"
    api_key: ${env:MERAKI_API_KEY}

Troubleshooting

Diagnostics

Debug Mode

Important: Debug mode is not supported for data collection jobs created via the UI using the Dyncfg feature.

To troubleshoot issues with the meraki collector, run the go.d.plugin with the debug option enabled. The output should give you clues as to why the collector isn’t working.

• Navigate to the plugins.d directory, usually at /usr/libexec/netdata/plugins.d/. If that’s not the case on your system, open netdata.conf and look for the plugins setting under [directories].

  cd /usr/libexec/netdata/plugins.d/
  

• Switch to the netdata user.

  sudo -u netdata -s
  

• Run the go.d.plugin to debug the collector:

  ./go.d.plugin -d -m meraki
  

  To debug a specific job:

  ./go.d.plugin -d -m meraki -j jobName
  

Getting Logs

If you’re encountering problems with the meraki collector, follow these steps to retrieve logs and identify potential issues:

• Run the command specific to your system (systemd, non-systemd, or Docker container).
• Examine the output for any warnings or error messages that might indicate issues. These messages should provide clues about the root cause of the problem.

System with systemd

Use the following command to view logs generated since the last Netdata service restart:

journalctl _SYSTEMD_INVOCATION_ID="$(systemctl show --value --property=InvocationID netdata)" --namespace=netdata --grep meraki

System without systemd

Locate the collector log file, typically at /var/log/netdata/collector.log, and use grep to filter for collector’s name:

grep meraki /var/log/netdata/collector.log

Note: This method shows logs from all restarts. Focus on the latest entries for troubleshooting current issues.

Docker Container

If your Netdata runs in a Docker container named “netdata” (replace if different), use this command:

docker logs netdata 2>&1 | grep meraki

Known Errors

operation: HTTP status 401

Cause

Meraki rejected the API key. It is mistyped, revoked, or belongs to a deleted administrator account.

Fix

Generate a new API key and update api_key and restart the job, or replace the contents of the file named by bearer_token_file, which is read again on the next request.

operation: HTTP status 403

Cause

The API key’s owner lacks permission for the request, or the organization restricts API access by source IP and the Agent’s address is not allowed.

Fix

Grant the key’s owner read-only access to the organization and, if it restricts API access by IP, allow the Agent’s public address. See the prerequisites.

operation: HTTP status 404

Cause

Meraki answers 404 when the API key cannot reach the organization at all. The organization ID is wrong, the key’s owner has no access to it, or Dashboard API access is disabled for it.

Fix

Check organization_id against the organizations the key can see (see the organization_id option), grant the key’s owner read-only access, and enable Dashboard API access for the organization.

configured organization_id is not visible to the Meraki credential

Cause

The API key works, but the organization in organization_id is not among the organizations it can see.

Fix

Check organization_id against the organizations the key can see (see the organization_id option), or use an API key of an administrator of that organization.

operation: HTTP status 429

Cause

Meraki rate-limited the request. The budgets of 10 requests per second per organization and 100 per source IP address are shared with every other application and job using them.

Fix

The collector sends nothing until the Retry-After delay Meraki requested has passed. If this happens when the job starts, the job retries after that delay only when autodetection_retry is set.

If it happens regularly, reduce the organization’s other API usage, move other API clients off the Agent’s address, or increase update_every.

Meraki API Retry-After delay has not elapsed

Cause

An earlier request was rate-limited and the wait Meraki requested is still running, so the collector skipped this collection without contacting the API.

Fix

No action is needed; collection resumes when the wait ends. If it recurs, see the HTTP status 429 entry.

operation: HTTP status 5xx

Cause

The Meraki API had a temporary failure, or a proxy in between could not reach it.

Fix

Usually none; the next collection tries again. If it persists, check Meraki’s service status and, when proxy_url is set, the proxy.

operation: HTTP request failed: reason

Cause

The request got no HTTP answer. The end of the message says why; for context deadline exceeded, see that entry.

Fix

To test the same path from the Agent host, preferably as the netdata user (replace the host with the one in url for another region):

curl -sS -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $MERAKI_API_KEY" https://api.meraki.com/api/v1/organizations

context deadline exceeded

Cause

A collection or the startup check took longer than timeout. Every page counts toward it, and the collector sends at most 10 requests per second, so a very large organization or a slow network can run out of time.

Fix

Check connectivity to the API endpoint. If requests succeed but the organization cannot finish in time, increase timeout.

operation: invalid pagination target

Cause

A next-page link pointed outside the endpoint in url. This happens when url is a proxy or private endpoint that passes Meraki’s Link headers through unchanged, and only for lists longer than one page.

Fix

Configure the proxy to rewrite Location and Link headers to its own address, or set url to the Meraki API endpoint of the organization’s region.

operation: cannot prepare authenticated request

When

bearer_token_file is set.

Cause

The key file is missing, empty or not readable by the netdata user.

Fix

Check the path in bearer_token_file, that the file contains the API key, and that the netdata user can read it.

operation: invalid JSON array response

Cause

The endpoint answered with something other than Meraki API data, typically because url points to another service or a proxy answered with its own page.

Fix

Set url to a Meraki API endpoint with the path /api/v1 (see the url option), and check proxy_url.

Meraki requires exactly one API key or bearer token file

Cause

Both authentication options are empty, both are set, or api_key contains a line break.

Fix

Set either api_key or bearer_token_file and clear the other. Make sure the key is on one line.

Meraki base URL must be an HTTPS /api/v1 URL without credentials, query or fragment

Cause

url is not an HTTPS URL with the path /api/v1, or it contains a user name, password, query or fragment.

Fix

Use one of the regional endpoints listed for the url option, or your endpoint’s HTTPS URL with the path /api/v1.

organization_id must be a nonempty organization ID without surrounding whitespace

Cause

organization_id is empty, has leading or trailing spaces, or is . or ...

Fix

Set organization_id to the organization’s ID, quoted as a string in YAML ("123456").

cannot initialize Meraki HTTP transport; check proxy and TLS configuration

Cause

proxy_url is not a valid URL, or a TLS file in tls_ca, tls_cert or tls_key cannot be read or parsed.

Fix

Check proxy_url, and that the TLS files exist, are readable by the netdata user and contain PEM data.

tls_cert and tls_key must be configured together

Cause

Only one of the client certificate options is set.

Fix

Set both tls_cert and tls_key, or neither.

Meraki assigned device has no serial

Cause

The assigned-device list from Meraki contained an entry without a serial number. The whole collection is dropped rather than shown with a device missing.

Fix

Usually temporary; the next collection reads the list again. If it persists, report it to Cisco Meraki support with the time of the error.

conflicting Meraki assigned-device records

Cause

The assigned-device list listed the same serial twice with different details, typically because a device was renamed or moved while the pages were read. The whole collection is dropped.

Fix

Usually temporary; the next collection reads the list again. If it persists, report it to Cisco Meraki support.

conflicting Meraki network records

Cause

The network list listed the same network ID twice with different names, typically because a network was renamed while the pages were read. The whole collection is dropped.

Fix

Usually temporary; the next collection reads the list again. If it persists, report it to Cisco Meraki support.

conflicting Meraki organization records

Cause

The organization list listed the configured organization ID twice with different details. The whole collection is dropped.

Fix

Usually temporary; the next collection reads the list again. If it persists, report it to Cisco Meraki support.

Meraki network belongs to a different organization

Cause

The network list for the configured organization contained a network of another organization. The whole collection is dropped.

Fix

Usually temporary; the next collection reads the list again. If it persists, report it to Cisco Meraki support.

Device node shows inventory but no availability chart

Cause

Meraki did not report a usable status for the device in the last collection. Availability can lag a new assignment or a network move by one refresh.

Fix

Check the device’s status in Dashboard and wait for the next 5-minute refresh. Run the collector in debug mode (see Diagnostics) to see how many devices had no usable status.