# pdf/zfs_exporter architecture

> Architecture diagram of the GitHub repository pdf/zfs_exporter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pdf/zfs_exporter
- Repository: https://github.com/pdf/zfs_exporter

## Overview

ZFS Exporter exposes ZFS pool and dataset state as Prometheus metrics. A scrape enters the HTTP metrics handler, which invokes the registered exporter; its collection coordinator selects pools and enabled collector types, queries ZFS, transforms selected properties, and emits metrics. The coordinator also enforces deadlines and serves cached values while a slow collection continues. The README documents pool, filesystem, snapshot, volume, property, exclusion, and host-root controls; the excerpts show the collection and CLI layers, but not all configuration or host-root wiring.

Main entry points: [`collector/zfs.go`](https://github.com/pdf/zfs_exporter/blob/master/collector/zfs.go) (Scrape Coordinator), [`zfs/zfs.go`](https://github.com/pdf/zfs_exporter/blob/master/zfs/zfs.go) (ZFS Client), [`collector/collector.go`](https://github.com/pdf/zfs_exporter/blob/master/collector/collector.go) (Property Mapping), [`collector/pool.go`](https://github.com/pdf/zfs_exporter/blob/master/collector/pool.go) (Pool Metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Exporter Runtime"]
  node_app["Exporter Main<br/>[zfs_exporter.go]"]
  node_http["Metrics HTTP<br/>[zfs_exporter.go]"]
end

subgraph group_collect["Metric Collection"]
  node_coordinator["Scrape Coordinator<br/>[zfs.go]"]
  node_cache[("Metric Cache<br/>[cache.go]")]
  node_poolmetrics["Pool Metrics<br/>[pool.go]"]
  node_filesystem["Filesystem Metrics<br/>[dataset.go]"]
  node_snapshot["Snapshot Metrics<br/>[dataset.go]"]
  node_volume["Volume Metrics<br/>[dataset.go]"]
  node_properties["Property Mapping<br/>[collector.go]"]
  node_transforms["Value Transforms<br/>[transform.go]"]
end

subgraph group_zfsapi["ZFS Access"]
  node_client["ZFS Client<br/>[zfs.go]"]
  node_poolquery["Pool Queries<br/>[pool.go]"]
  node_datasetquery["Dataset Queries<br/>[dataset.go]"]
  node_runner["CLI Runner<br/>[zfs.go]"]
  node_hostroot["Host-Root Runner<br/>[hostroot_linux.go]"]
end

subgraph group_output["Metric Output"]
  node_metrics["Prometheus Metrics<br/>[zfs_exporter.go]"]
end

node_scraper(("Prometheus Scraper"))
node_zfscli["ZFS CLI"]

node_scraper -->|"scrapes"| node_http
node_app -->|"constructs"| node_coordinator
node_http -->|"serves"| node_metrics
node_coordinator -->|"reads and updates"| node_cache
node_coordinator -->|"dispatches"| node_poolmetrics
node_coordinator -->|"dispatches"| node_filesystem
node_coordinator -->|"dispatches"| node_snapshot
node_coordinator -->|"dispatches"| node_volume
node_poolmetrics -->|"queries"| node_client
node_filesystem -->|"queries"| node_client
node_snapshot -->|"queries"| node_client
node_volume -->|"queries"| node_client
node_poolmetrics -->|"maps properties"| node_properties
node_filesystem -->|"maps properties"| node_properties
node_snapshot -->|"maps properties"| node_properties
node_volume -->|"maps properties"| node_properties
node_properties -->|"converts values"| node_transforms
node_client -->|"creates"| node_poolquery
node_client -->|"creates"| node_datasetquery
node_poolquery -->|"executes commands"| node_runner
node_datasetquery -->|"executes commands"| node_runner
node_runner -->|"runs"| node_zfscli
node_hostroot -->|"runs chrooted"| node_zfscli
node_coordinator -->|"emits"| node_metrics

click node_app "https://github.com/pdf/zfs_exporter/blob/master/zfs_exporter.go"
click node_http "https://github.com/pdf/zfs_exporter/blob/master/zfs_exporter.go"
click node_coordinator "https://github.com/pdf/zfs_exporter/blob/master/collector/zfs.go"
click node_cache "https://github.com/pdf/zfs_exporter/blob/master/collector/cache.go"
click node_poolmetrics "https://github.com/pdf/zfs_exporter/blob/master/collector/pool.go"
click node_filesystem "https://github.com/pdf/zfs_exporter/blob/master/collector/dataset.go"
click node_snapshot "https://github.com/pdf/zfs_exporter/blob/master/collector/dataset.go"
click node_volume "https://github.com/pdf/zfs_exporter/blob/master/collector/dataset.go"
click node_properties "https://github.com/pdf/zfs_exporter/blob/master/collector/collector.go"
click node_transforms "https://github.com/pdf/zfs_exporter/blob/master/collector/transform.go"
click node_client "https://github.com/pdf/zfs_exporter/blob/master/zfs/zfs.go"
click node_poolquery "https://github.com/pdf/zfs_exporter/blob/master/zfs/pool.go"
click node_datasetquery "https://github.com/pdf/zfs_exporter/blob/master/zfs/dataset.go"
click node_runner "https://github.com/pdf/zfs_exporter/blob/master/zfs/zfs.go"
click node_hostroot "https://github.com/pdf/zfs_exporter/blob/master/zfs/hostroot_linux.go"
click node_metrics "https://github.com/pdf/zfs_exporter/blob/master/zfs_exporter.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_http toneBlue
class node_coordinator,node_cache,node_poolmetrics,node_filesystem,node_snapshot,node_volume,node_properties,node_transforms toneAmber
class node_client,node_poolquery,node_datasetquery,node_runner,node_hostroot toneMint
class node_metrics toneRose
class node_scraper,node_zfscli toneIndigo
```

## Components

### Exporter Runtime

- [Exporter Main](https://github.com/pdf/zfs_exporter/blob/master/zfs_exporter.go): `zfs_exporter.go`
- [Metrics HTTP](https://github.com/pdf/zfs_exporter/blob/master/zfs_exporter.go): `zfs_exporter.go`

### Metric Collection

- [Scrape Coordinator](https://github.com/pdf/zfs_exporter/blob/master/collector/zfs.go): `collector/zfs.go`
- [Metric Cache](https://github.com/pdf/zfs_exporter/blob/master/collector/cache.go): `collector/cache.go`
- [Pool Metrics](https://github.com/pdf/zfs_exporter/blob/master/collector/pool.go): `collector/pool.go`
- [Filesystem Metrics](https://github.com/pdf/zfs_exporter/blob/master/collector/dataset.go): `collector/dataset.go`
- [Snapshot Metrics](https://github.com/pdf/zfs_exporter/blob/master/collector/dataset.go): `collector/dataset.go`
- [Volume Metrics](https://github.com/pdf/zfs_exporter/blob/master/collector/dataset.go): `collector/dataset.go`
- [Property Mapping](https://github.com/pdf/zfs_exporter/blob/master/collector/collector.go): `collector/collector.go`
- [Value Transforms](https://github.com/pdf/zfs_exporter/blob/master/collector/transform.go): `collector/transform.go`

### ZFS Access

- [ZFS Client](https://github.com/pdf/zfs_exporter/blob/master/zfs/zfs.go): `zfs/zfs.go`
- [Pool Queries](https://github.com/pdf/zfs_exporter/blob/master/zfs/pool.go): `zfs/pool.go`
- [Dataset Queries](https://github.com/pdf/zfs_exporter/blob/master/zfs/dataset.go): `zfs/dataset.go`
- [CLI Runner](https://github.com/pdf/zfs_exporter/blob/master/zfs/zfs.go): `zfs/zfs.go`
- [Host-Root Runner](https://github.com/pdf/zfs_exporter/blob/master/zfs/hostroot_linux.go): `zfs/hostroot_linux.go`

### Metric Output

- [Prometheus Metrics](https://github.com/pdf/zfs_exporter/blob/master/zfs_exporter.go): `zfs_exporter.go`

### Other components

- **Prometheus Scraper**
- **ZFS CLI**

## Connections

- Prometheus Scraper → Metrics HTTP: scrapes (evidence: `README.md`)
- Exporter Main → Scrape Coordinator: constructs (evidence: `zfs_exporter.go`)
- Metrics HTTP → Prometheus Metrics: serves (evidence: `zfs_exporter.go`)
- Scrape Coordinator → Metric Cache: reads and updates (evidence: `collector/zfs.go`)
- Scrape Coordinator → Pool Metrics: dispatches (evidence: `collector/zfs.go`)
- Scrape Coordinator → Filesystem Metrics: dispatches (evidence: `collector/zfs.go`)
- Scrape Coordinator → Snapshot Metrics: dispatches (evidence: `collector/zfs.go`)
- Scrape Coordinator → Volume Metrics: dispatches (evidence: `collector/zfs.go`)
- Pool Metrics → ZFS Client: queries (evidence: `collector/pool.go`)
- Filesystem Metrics → ZFS Client: queries (evidence: `collector/dataset.go`)
- Snapshot Metrics → ZFS Client: queries (evidence: `collector/dataset.go`)
- Volume Metrics → ZFS Client: queries (evidence: `collector/dataset.go`)
- Pool Metrics → Property Mapping: maps properties (evidence: `collector/pool.go`)
- Filesystem Metrics → Property Mapping: maps properties (evidence: `collector/dataset.go`)
- Snapshot Metrics → Property Mapping: maps properties (evidence: `collector/dataset.go`)
- Volume Metrics → Property Mapping: maps properties (evidence: `collector/dataset.go`)
- Property Mapping → Value Transforms: converts values (evidence: `collector/collector.go`)
- ZFS Client → Pool Queries: creates (evidence: `zfs/zfs.go`)
- ZFS Client → Dataset Queries: creates (evidence: `zfs/zfs.go`)
- Pool Queries → CLI Runner: executes commands (evidence: `zfs/pool.go`)
- Dataset Queries → CLI Runner: executes commands (evidence: `zfs/dataset.go`)
- CLI Runner → ZFS CLI: runs (evidence: `zfs/zfs.go`)
- Host-Root Runner → ZFS CLI: runs chrooted (evidence: `zfs/hostroot_linux.go`)
- Scrape Coordinator → Prometheus Metrics: emits (evidence: `collector/zfs.go`)
