> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring Extensions

> Select the monitoring extensions your project contributes to the observability stack — the built-in claude-code extension, loose local extensions, and bundled extensions

A **monitoring extension** is a self-contained observability contribution — the
OpenSearch indices, ingest pipelines, dashboards, and collector routing that
turn a stream of telemetry into something you can query. Clawker's monitoring
stack is preconfigured from the monitoring extensions your project selects.

This page covers selecting and consuming extensions. For the stack itself
(OpenSearch, Dashboards, Prometheus, the collector, and the bootstrap
pipeline), see [Monitoring](/monitoring).

## Selecting extensions

List the extensions your project contributes under `monitor.extensions`:

```yaml theme={"dark"}
# clawker.yaml
monitor:
  extensions:
    - claude-code
    - acme.tools.postgres
```

`monitor.extensions` is a whole-value selection: the highest config layer that
sets it wins, so a project can replace — or deselect — what a user-level config
provides. The default selection is the built-in `claude-code` extension; set an
explicit empty list (`extensions: []`) to opt out of all monitoring.

Each entry is a component name — bare for a built-in or loose extension, or a
qualified `namespace.bundle.component` address for a bundled extension.

## How consumption works

Monitoring is seeded, not registered. Nothing is pinned in a host-side
registry; the active set is a projection of the project you seed from.

* `clawker monitor up` is bring-up only. When the stack is down it starts it
  and seeds the extensions your **current project** selects — creating the
  indices, pipelines, and dashboards. When the stack is already running, `up`
  prints so and exits without touching it.
* To apply extension changes — a new selection or edited content — to a
  running stack, run `clawker monitor reload`, the explicit disruptive apply:
  it seeds your project's selection, re-renders the collector config, and
  recreates the collector so the new routing takes effect (briefly
  interrupting telemetry ingestion).
* Seeded artifacts persist in the stack's volumes until you prune them.
* Collector routing is regenerated from the union of every extension ever seeded
  into the stack, so seeding from one project never drops another project's
  routing.

To reset the monitoring stack — clearing all seeded extensions along with the
telemetry data — tear it down with its volumes:

```bash theme={"dark"}
clawker monitor down --volumes
```

<Note>
  When two projects each ship a **loose** monitoring extension of the same bare
  name with different content, the seed is refused — the seeding command
  (`monitor up` at bring-up, `monitor reload` on a running stack) fails with an
  error naming both project roots. Rename one of the extensions, or reset the
  seeded stack with `clawker monitor down --volumes`. An identical-content
  re-seed from another project is a harmless no-op, and bundled extensions
  carry qualified names and never collide this way.
</Note>

## Where extensions come from

Extension names resolve across the same three tiers as every component. A bare
name resolves **user convention directory, then project convention directory,
then the built-in floor**; a qualified name resolves from an installed bundle.
See [where components come from](/bundles#where-components-come-from) for the
canonical resolution model. `clawker monitor extensions` lists every
resolvable extension with its provenance — a bundled extension names its
owning bundle, and a shadow is marked with `!`.

### Built-in extension

Clawker ships `claude-code`, which lands Claude Code session telemetry (cost,
tokens, tool calls) and its dashboards. It resolves by bare name and updates
with the clawker binary.

### Loose local extensions

Drop a monitoring extension directory into a convention directory and it exists
immediately, bare-named:

```
project:  .clawker/monitoring/<name>/
user:     ~/.config/clawker/monitoring/<name>/
```

### Bundled extensions

An extension shipped in a bundle is addressed by its qualified name and becomes
available once the bundle is declared and installed. See [Bundles](/bundles).

## Authoring an extension

Writing your own monitoring extension — the `monitoring.yaml` manifest, its log
lanes, index templates, ingest pipelines, and saved objects — is covered in
[Authoring monitoring extensions](/authoring-monitoring).