netdata

Use when migrating alerting rules from VictoriaMetrics (vmalert), Prometheus, Thanos Ruler, or Mimir/Cortex to Netdata health alerts. These tools share the same Prometheus alerting-rule YAML and PromQL/MetricsQL, so the method is identical. Covers the stock-first decision (Netdata already ships alerts for most common signals), the translation methodology from PromQL expressions to Netdata lookup/calc/warn/crit on a chart context, the constructs that do not map cleanly (cross-metric joins, predict_linear, histogram_quantile, fleet aggregations, absent), notification-routing parity with Alertmanager (agent roles and Netdata Cloud), and automatic verification over MCP. Pairs with netdata-mcp-integration to connect and netdata-custom-collector when a rule alerts on a metric Netdata does not yet collect.

Use when you need Netdata to collect metrics from something it does not already monitor, such as a custom application, an internal service, the output of a script or CLI tool, or a device. Covers the decision tree from the built-in StatsD server (zero collector code) through writing a collector in any language via the external-plugin line protocol (CHART/DIMENSION/BEGIN/SET/END on stdout), or the legacy python.d and charts.d module frameworks. Teaches how to pick the cheapest approach that works, scaffold it from a real example, and, when a Netdata MCP server is connected, automatically verify over MCP that the metrics are collected in the right format without user handholding.

Use when building or modifying an OpenTelemetry Collector pipeline that forwards telemetry to Netdata. Covers receivers, processors, exporters, and three deployment patterns (DaemonSet, gateway, and OpenTelemetry Operator). Teaches how to shape chart dimensions via an OTLP attribute plus a mapping file, since Netdata does not expose producer-driven annotations for chart layout.

Use when a customer or prospect has sent a written requirements document, architecture brief, or RFP and the deliverable is a config bundle (Netdata otel.yaml, OpenTelemetry Collector pipelines, per-language instrumentation handoff, verification playbook) that the customer applies themselves. Unlike netdata-instrumentation and netdata-otel-setup, this skill operates without access to the customer's codebase or running infrastructure: inputs are prose, outputs are YAML files, Markdown runbooks, and an explicit list of open questions for the account team. Covers requirements extraction, ambiguity flagging, bundle layout, and composition with netdata-otel-setup, netdata-collector-config, netdata-instrumentation, and netdata-migration.

Use when adding OpenTelemetry instrumentation to application code that will report to Netdata. Covers SDK setup, resource attributes, auto-instrumentation, and patterns for Node.js, Python, Java, Go, .NET, Ruby, and PHP. Emits metrics and logs via OTLP gRPC to Netdata. Traces are not yet supported by Netdata; use an alternative trace backend until Q2 2026.

Use when an AI coding agent needs to connect to a Netdata Agent, Parent, or Netdata Cloud via MCP to verify telemetry, query live metrics, cross-reference instrumentation with infrastructure signals, or troubleshoot services. Covers Claude Code, Cursor, Codex, and Gemini CLI client configs for both local (http://HOST:19999/mcp) and Netdata Cloud endpoints.

Use when migrating observability from Datadog, New Relic, Dynatrace, or Prometheus to Netdata. Covers SDK replacement, exporter reconfiguration, Prometheus endpoint passthrough, and dashboard parity expectations.

Use when enabling the Netdata otel.plugin, writing /etc/netdata/otel.yaml, defining metric-to-chart mappings, configuring TLS on the OTLP receiver, or debugging OTLP ingestion issues with Netdata. Covers OTLP gRPC ingestion for metrics (v2.7.0+) and logs (v2.9.0+). Traces are not yet supported.

Use when creating or migrating a Go go.d collector to framework V2, touching CollectorV2, metrix.CollectorStore, ChartTemplateYAML/charts.yaml, charttpl/chartengine, V2 host scopes/vnodes, or V2 collector tests. Focuses on concise maintainer-preferred V2 collector patterns.

Netdata integrations pipeline reference. Use when editing metadata.yaml or taxonomy.yaml; modifying integrations generators, schemas, taxonomy registries, templates, generated integration docs, integrations.js, integrations.json, integrations/taxonomy.json, COLLECTORS.md, SECRETS.md, or SERVICE-DISCOVERY.md; changing collector consistency artifacts; or working with ibm.d contexts.yaml to metadata.yaml generation.

Use when editing Netdata SNMP trap profile YAMLs, trap profile metric rules, the trap profile-format documentation, the snmp-trap-profile-gen Go helper, or running a regeneration of the OOB trap profile pack. Enforces the closed 8-category / 8-severity taxonomy, the file-scoped varbinds-table pattern, metric cardinality discipline, and stock/operator separation.

Best practices and orientation for AI assistants authoring or modifying Netdata data-collection plugins or modules in any language. Read before adding a new collector, modifying an existing one, working on logs, topology, NetFlow/sFlow/IPFIX, OTEL ingestion, SNMP profiles, statsd, Prometheus scraping, or interactive Functions. Covers the mental model, framework-agnostic best practices, dashboard-shaping mechanisms (NIDL, SNMP profiles, statsd synthetic_charts, OTEL mappings, Prometheus exposition), production quality criteria, the plugin landscape, per-data-type patterns (metrics, logs, snapshots, topology, enrichment), per-domain common practices, and a pre-PR self-check.

Address pull-request comments and reviews iteratively until the PR is clean — fetch all comments with paranoid pagination, classify by author (AI bot vs human), verify each finding, address it, find similar patterns, reply per-thread, resolve threads, check CI before pushing, retrigger AI reviewers (cubic-dev-ai, copilot), and wait for new feedback. Use when the user says "address PR comments", "look at the reviews on PR N", "deal with the bot comments", "iterate on PR N until clean", or anything mentioning PR comments / reviews / cubic / copilot.

Bug-investigation tool for the Netdata agent-events ingestion namespace -- triage crashes, panics, fatals across the fleet by downloading events of interest and clustering locally. Covers the three transports (Cloud API and direct agent API are primary; ssh is operator-only), the verified AE_* field map and enum meanings, the dedup model (23h client-side per agent and event signature), the after-the-fact event timing (POST only on agent restart), and the Netdata systemd-journal plugin multi-value filter syntax (FIELD in A, B, C) AND ... Use when investigating crashes / panics / fatals; when grepping for events touching a specific function or file or version; when looking for regressions across versions; when an agent is reported crashing in a way you want to triage. Ships scripts get-events.sh and analyze-events.sh that fetch events with index-friendly filters and compute group-by stats. Defaults to last 24 hours and to the latest stable plus latest 2-3 nightlies.

Query Netdata Agents (parents and children) directly via their HTTP API on port 19999. Includes a bearer-token helper that mints, caches, and transparently refreshes a per-agent bearer from a long-lived Netdata Cloud token, and auto-detects bearer-protected agents. Use when the user asks how to call an agent's REST API or Function directly, query an agent's logs/metrics/alerts directly, mint a bearer token from a cloud token, or work around bearer protection.

Query Netdata Cloud via its REST API -- metrics, logs (systemd-journal / windows-events / macos-logs / otel-logs), topology graphs (topology:snmp), network flows (flows:netflow), alerts, dynamic configuration (DynCfg), and generic Functions on a node. Use when the user asks about querying Netdata Cloud, fetching metrics from the cloud, querying logs / topology / netflow / sflow / ipfix through Cloud, listing or modifying configurations via DynCfg, calling agent Functions through Cloud, listing spaces/rooms/nodes, or building a curl command against `app.netdata.cloud`. Pairs with the `query-netdata-agents` skill when direct-agent access is needed.

Apply ai-viewer coding standards for production-quality Go and TypeScript changes. Use for implementation, refactoring, runtime behavior changes, and any change where clean code, separation of concerns, modularity, or maintainability matters.

Apply Go-specific patterns used in ai-viewer for fsnotify watching, SQLite access, SSE streaming, and structured logging. Use when editing internal/ingest, internal/store, internal/presenter, internal/adapters, internal/canonical, or internal/obs.

Run ai-viewer's external reviewer gates. Use on meaningful chunks of work, at least per SOW and per substantial SOW milestone: gap analysis, implementation plan, and implementation review. Reviewers are glm, minimax, kimi, mimo, deepseek, and qwen. They are gates, not implementers.

Master orchestration cycle for ai-viewer work — gap→plan→spec→test→code→gates→review→commit. The CTO writes implementation directly. Helper subagents are optional for bounded investigation, not the implementation norm. External reviewers are three milestone gates per meaningful feature, substantial batch, or SOW, not routine delegation.

Catalog of every automated quality gate ai-viewer enforces — commands, thresholds, and what to do when a gate fails. Use before claiming any work done, before any commit, when adding a new gate, or when investigating a CI failure. The runtime companion to .agents/sow/specs/quality-gates.md.

Keep ai-viewer specs synchronized with code. Use whenever a code change touches runtime behavior, defaults, schemas, contracts, file layouts, or external interfaces.

Helper-subagent patterns for ai-viewer. Use when bounded read-only investigation, summarization, or parallel context gathering would help. Do not use this skill to delegate implementation by default, and do not use helper subagents as external reviewer gates.

Install, run, and operate ai-viewer on the operator's workstation — the system install (/opt/ai-viewer, runs-as-operator, explicit --source flags, systemd units), the user install alternative, build/run/upgrade/uninstall commands, and the threat-model reasoning behind the run-as-operator decision. Use when installing or upgrading ai-viewer, debugging source-discovery / permission-denied errors, or answering "how do I run this / what port / where's the data".

Mandatory compatibility rules when changing journal file readers, writers, fixtures, conformance tests, interoperability tests, or journalctl rewrites.

Use when creating, checking, or pushing release tags for this repository, especially Go module release tags.

Mandatory rules when creating or editing consumer wiki documentation under docs/, including the verified-examples contract, marker grammar, placeholder paths, and validation commands.

Mandatory workflow when planning, delegating, implementing, reviewing, or closing SOW-driven work through external agents in this repository.

Mandatory workflow for copying, syncing, vendoring, or merging plugin-ipc NetIPC source changes into a Netdata checkout. Use whenever work mentions Netdata vendoring, vendor drift, vendor-to-netdata, diff-netdata-vendor.sh, vendor-to-netdata.sh, or updating src/libnetdata/netipc, src/crates/netipc, or src/go/pkg/netipc in Netdata.