Integrations

An integration connects software you run to Noemata. It can configure telemetry collection and install a frame pack with a semantic layer and dashboards for that software. See Integrations for the concepts behind integrations.

What an integration installs

When you enable one, it can do any of:

• Configure collection — add receivers to the collector, such as a log-file receiver or a database metrics scraper.
• Edit the source’s config — point the application at the collector. Setup asks before writing a config file outside the repository and records the answer as integrations.external_edits.
• Install a frame pack into @frames/@<id>/ — the views and dashboards you browse in the app.
• Write editor skills into your coding agents (gated by integrations.skills — see Editor skills).

Integrations are reconciled on every noemata up, and on demand with noemata reconcile. By default their frame packs are managed — see Ownership & version control for what that means and how to take ownership instead.

If detection fails, Noemata still applies the integration’s file edits, installs its frame pack, and writes its collector component definitions. The integration’s collector pipelines stay inactive until detection succeeds. A stopped dependency does not prevent the collector from starting.

The always-installed integrations

Two integrations are required. They install in every project and the wizard does not offer to turn them off. Other shipped packs use their frames. Neither requires a collector.

• @noemata — Noemata’s own content: these docs, plus a self-monitoring dashboard over Noemata’s own telemetry.
• @opentelemetry — the OpenTelemetry semantic layer every other OTel-based dashboard builds on, plus the dashboards built on it.

The @otel_collector pack turns the managed collector’s own metrics and logs into a health dashboard for it. It’s optional — offered by the wizard rather than required.

Optional integrations

Beyond the two required packs and @otel_collector above, the setup wizard (noemata config) currently offers:

• Claude Code — session transcripts and native OTLP telemetry. Has its own settings (redact_content, the frame-validation hook) — see its page.
• Codex — native OTLP logs and metrics plus thread transcripts, with usage, work, extensibility, reliability, tool, MCP, skill, and thread dashboards.
• ClickHouse — self-monitoring for a ClickHouse you run, via its Prometheus endpoint and system.* tables.
• My machine — collects this machine’s CPU, memory, disk, network, and process metrics. It also enables the hostmetrics collection. The @my_machine hub summarizes this machine and links to the @opentelemetry/hosts dashboards for all reporting hosts.

Each probes for the software it covers and only offers itself when detection succeeds. See Integrations for how detection works. Codex and ClickHouse have no settings beyond enabling them. Claude Code’s settings are on its own page, and My machine’s metric knobs are in Choosing what a metrics integration collects below.

Integrations published as npm packages, such as Docker (@noemata/integration-docker, per-container CPU, memory, network, and block-I/O metrics), are installed with noemata integrations add rather than offered by the wizard.

Enabling and disabling

The wizard (noemata config) is the usual way to change what’s installed. In noemata.json, integrations live under the top-level integrations key:

{
  "integrations": {
    "packages": { "@noemata/integration-docker": {} },
    "installed": { "opentelemetry": {}, "@noemata/integration-docker": {} },
    "managed": true,
    "skills": true,
    "external_edits": true
  }
}

• packages — the npm packages installed into the project that contribute integrations, by package name. noemata integrations add records a package here; the integrations Noemata ships need no entry. A package’s entry holds its options, today trusted (see Trusting a package).
• installed — enabled integrations, keyed by id. Shipped integrations use short ids such as claude_code; npm integrations use their package name. Required integrations install even when omitted. Enabling my_machine also enables hostmetrics, which does not need its own entry. Each id’s value contains that integration’s settings.
• managed — whether Noemata owns the installed frame packs. See Ownership & version control.
• skills — whether integrations install editor skills and which hosts receive them (see Editor skills). The wizard asks before installing skills above the project directory and records a decline here.
• external_edits — whether reconciliation may write outside the repository this project lives in (e.g. ~/.claude/settings.json). The wizard asks once, when an integration you enable writes there, and records a decline here; every later reconcile reads it. When a reconcile does change a file outside the repository it warns, naming each one.
• remove_orphans — whether reconciliation may also delete pack files left behind: an integration that is no longer enabled, or one still enabled that no longer ships a pack. Off by default.

To skip integrations for one run, use the up flags: --no-integrations (regenerate service configs only), --no-skills, or --no-external-edits.

Installing integrations from npm

Integrations can be published as npm packages. See Build an integration for details. Install a package in the project directory with:

noemata integrations add @noemata/integration-docker

The command uses the project’s package manager to add the package to package.json, records it under packages and installed, then reconciles. Add @<version> to pin a version. Pass a path to link a local checkout for development. Pass an integration id, such as clickhouse, to enable an integration that is already available without installing a package.

A package can provide several integrations with separate ids. Adding the package prints its ids; run noemata integrations add <id> to enable one. The shipped integrations are provided by @noemata/integrations. Adding a version of that package replaces the copy built into the CLI for this project. If multiple packages provide the same id, the first package wins. noemata integrations list reports the others.

An installed package is always enabled: unlike the integrations Noemata ships, it is never offered as a choice by the wizard, and its dashboards and collector configuration reconcile whether or not the software it observes is present. When that software is missing, the package’s own collector pipelines stay inactive until a later reconcile finds it, as for any other integration.

noemata integrations list shows each enabled integration’s source and load status. Noemata skips a package when its version range excludes the running version, a required integration is missing, its settings fail schema validation, or its package files cannot be read. The output gives the reason. A skipped package keeps its existing frame files. noemata integrations remove <package> uninstalls the package and removes its installed entry. Its frame files remain until remove_orphans is enabled.

Frame packs from npm install under @frames/ by package name: @noemata/integration-docker lands at @frames/@noemata/integration-docker/, and an unscoped package noemata-foo at @frames/@noemata-foo/. Managed, ownership, and orphan removal apply to them exactly as to the packs Noemata ships.

Trusting a package

A package installed from npm runs code on your machine during reconcile, and can propose edits to files outside the repository, such as an application’s own configuration under your home directory. Those edits are off for every npm package until its entry under integrations.packages sets trusted:

{
  "integrations": {
    "packages": { "@noemata/integration-docker": { "trusted": true } }
  }
}

The wizard asks when a package you install first proposes such an edit, listing the files it would write, and sets trusted on the package if you agree. Until then reconcile skips the edit and prints what it would have written and the setting that allows it. external_edits still applies: with it off, no integration writes outside the repository, trusted or not. Edits inside the repository, frame packs, and skills need no trust; the package manager already installed the package into the project, and those writes stay within it.

Choosing what a metrics integration collects

An integration collects its source’s whole metric catalogue rather than the subset today’s dashboards happen to render — so the question you ask next has data behind it. The only things left out are metrics that restate one already collected (a utilization gauge is its counter divided by itself, which a view expression does at query time) and a couple of families whose cost scales with something other than the number of machines.

Those exceptions are named knobs under the integration’s own key, each describing what it observes rather than a volume tier:

{
  "integrations": {
    "installed": {
      "hostmetrics": { "metrics": { "process_details": true, "hugepages": false } },
      "@noemata/integration-docker": { "metrics": { "per_core_cpu": true } }
    }
  }
}

• hostmetrics.metrics — cpu_frequency, hugepages and conntrack are collected by default and take false. process_details (per-process uptime, context switches, page faults, disk operations, pending signals) is off by default and takes true: it is per-PID, and one such metric costs roughly 100k rows an hour on a busy machine.
• @noemata/integration-docker’s metrics — cgroup_memory (raw cgroup memory accounting) and block_io_details (queue depth, merges, service and wait time) are collected by default and take false. per_core_cpu is off by default and takes true: it is the one container metric that scales with cores × containers.

A metric your platform doesn’t support costs nothing — the receiver simply emits no rows for it — so these defaults are the same everywhere.