# python-diamond/diamond architecture

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

- Interactive diagram: https://gitdiagram.com/python-diamond/diamond
- Repository: https://github.com/python-diamond/diamond

## Overview

Diamond is a Python metrics-collection daemon: it polls host and service sources, turns observations into metrics, then routes them to configured publishing handlers. The README highlights system metrics, extensible custom collectors, and Graphite plus other destinations. The graph shows the server, collector framework, metric/queue boundary, and representative output adapters. The source excerpts are partial, so detailed wiring among unsampled collectors and handlers is not asserted.

Main entry points: [`src/diamond/handler/Handler.py`](https://github.com/python-diamond/diamond/blob/master/src/diamond/handler/Handler.py) (Handler framework), [`src/diamond/metric.py`](https://github.com/python-diamond/diamond/blob/master/src/diamond/metric.py) (Metric model), [`src/diamond/server.py`](https://github.com/python-diamond/diamond/blob/master/src/diamond/server.py) (Diamond server), [`src/diamond/utils/scheduler.py`](https://github.com/python-diamond/diamond/blob/master/src/diamond/utils/scheduler.py) (Collector scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collect["Metric collection"]
  node_collector_base["Collector API<br/>[collector.py]"]
  node_host_collectors["Host collectors<br/>[cpu.py]"]
  node_service_collectors["Service collectors<br/>[elasticsearch.py]"]
  node_database_collectors["Database collectors<br/>[postgres.py]"]
  node_custom_collectors["Custom collectors<br/>[userscripts.py]"]
end

subgraph group_runtime["Daemon runtime"]
  node_server["Diamond server<br/>[server.py]"]
  node_scheduler["Collector scheduler<br/>[scheduler.py]"]
  node_config["Configuration utilities<br/>[config.py]"]
  node_metric["Metric model<br/>[metric.py]"]
  node_metric_queue["Metric queue<br/>[server.py]"]
end

subgraph group_publish["Metric publishing"]
  node_handler_base["Handler framework<br/>[Handler.py]"]
  node_graphite_handler["Graphite handler<br/>[graphite.py]"]
  node_influx_handler["InfluxDB handler<br/>[influxdbHandler.py]"]
  node_http_handler["HTTP POST handler<br/>[httpHandler.py]"]
  node_librato_handler["Librato handler<br/>[libratohandler.py]"]
end

node_sources(("Monitored systems"))
node_service_sources(("Service APIs"))
node_graphite_service(("Graphite"))
node_influx_service(("InfluxDB"))
node_http_service(("HTTP endpoint"))
node_librato_service(("Librato"))

node_server -->|"loads settings"| node_config
node_server -->|"manages polling"| node_scheduler
node_server -->|"creates queue"| node_metric_queue
node_server -->|"loads collectors"| node_collector_base
node_scheduler -->|"schedules"| node_host_collectors
node_scheduler -->|"schedules"| node_service_collectors
node_scheduler -->|"schedules"| node_database_collectors
node_scheduler -->|"schedules"| node_custom_collectors
node_sources -->|"read metrics"| node_host_collectors
node_service_sources -->|"query APIs"| node_service_collectors
node_service_sources -->|"query databases"| node_database_collectors
node_collector_base -->|"publishes metrics"| node_metric
node_host_collectors -->|"publishes metrics"| node_metric
node_service_collectors -->|"publishes metrics"| node_metric
node_database_collectors -->|"publishes metrics"| node_metric
node_custom_collectors -->|"publishes metrics"| node_metric
node_metric -->|"queued for dispatch"| node_metric_queue
node_server -->|"loads handlers"| node_handler_base
node_metric_queue -->|"dispatches metrics"| node_handler_base
node_handler_base -->|"processes metrics"| node_graphite_handler
node_handler_base -->|"processes metrics"| node_influx_handler
node_handler_base -->|"processes metrics"| node_http_handler
node_handler_base -->|"processes metrics"| node_librato_handler
node_graphite_handler -->|"publishes"| node_graphite_service
node_influx_handler -->|"publishes"| node_influx_service
node_http_handler -->|"POSTs batches"| node_http_service
node_librato_handler -->|"submits metrics"| node_librato_service

click node_server "https://github.com/python-diamond/diamond/blob/master/src/diamond/server.py"
click node_scheduler "https://github.com/python-diamond/diamond/blob/master/src/diamond/utils/scheduler.py"
click node_config "https://github.com/python-diamond/diamond/blob/master/src/diamond/utils/config.py"
click node_collector_base "https://github.com/python-diamond/diamond/blob/master/src/diamond/collector.py"
click node_host_collectors "https://github.com/python-diamond/diamond/blob/master/src/collectors/cpu/cpu.py"
click node_service_collectors "https://github.com/python-diamond/diamond/blob/master/src/collectors/elasticsearch/elasticsearch.py"
click node_database_collectors "https://github.com/python-diamond/diamond/blob/master/src/collectors/postgres/postgres.py"
click node_custom_collectors "https://github.com/python-diamond/diamond/blob/master/src/collectors/userscripts/userscripts.py"
click node_metric "https://github.com/python-diamond/diamond/blob/master/src/diamond/metric.py"
click node_metric_queue "https://github.com/python-diamond/diamond/blob/master/src/diamond/server.py"
click node_handler_base "https://github.com/python-diamond/diamond/blob/master/src/diamond/handler/Handler.py"
click node_graphite_handler "https://github.com/python-diamond/diamond/blob/master/src/diamond/handler/graphite.py"
click node_influx_handler "https://github.com/python-diamond/diamond/blob/master/src/diamond/handler/influxdbHandler.py"
click node_http_handler "https://github.com/python-diamond/diamond/blob/master/src/diamond/handler/httpHandler.py"
click node_librato_handler "https://github.com/python-diamond/diamond/blob/master/src/diamond/handler/libratohandler.py"

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_collector_base,node_host_collectors,node_service_collectors,node_database_collectors,node_custom_collectors toneBlue
class node_server,node_scheduler,node_config,node_metric,node_metric_queue toneAmber
class node_handler_base,node_graphite_handler,node_influx_handler,node_http_handler,node_librato_handler,node_service_sources toneMint
class node_sources,node_graphite_service,node_influx_service,node_http_service,node_librato_service toneIndigo
```

## Components

### Metric collection

- [Collector API](https://github.com/python-diamond/diamond/blob/master/src/diamond/collector.py): `src/diamond/collector.py`
- [Host collectors](https://github.com/python-diamond/diamond/blob/master/src/collectors/cpu/cpu.py): `src/collectors/cpu/cpu.py`
- [Service collectors](https://github.com/python-diamond/diamond/blob/master/src/collectors/elasticsearch/elasticsearch.py): `src/collectors/elasticsearch/elasticsearch.py`
- [Database collectors](https://github.com/python-diamond/diamond/blob/master/src/collectors/postgres/postgres.py): `src/collectors/postgres/postgres.py`
- [Custom collectors](https://github.com/python-diamond/diamond/blob/master/src/collectors/userscripts/userscripts.py): `src/collectors/userscripts/userscripts.py`

### Daemon runtime

- [Diamond server](https://github.com/python-diamond/diamond/blob/master/src/diamond/server.py): `src/diamond/server.py`
- [Collector scheduler](https://github.com/python-diamond/diamond/blob/master/src/diamond/utils/scheduler.py): `src/diamond/utils/scheduler.py`
- [Configuration utilities](https://github.com/python-diamond/diamond/blob/master/src/diamond/utils/config.py): `src/diamond/utils/config.py`
- [Metric model](https://github.com/python-diamond/diamond/blob/master/src/diamond/metric.py): `src/diamond/metric.py`
- [Metric queue](https://github.com/python-diamond/diamond/blob/master/src/diamond/server.py): `src/diamond/server.py`

### Metric publishing

- [Handler framework](https://github.com/python-diamond/diamond/blob/master/src/diamond/handler/Handler.py): `src/diamond/handler/Handler.py`
- [Graphite handler](https://github.com/python-diamond/diamond/blob/master/src/diamond/handler/graphite.py): `src/diamond/handler/graphite.py`
- [InfluxDB handler](https://github.com/python-diamond/diamond/blob/master/src/diamond/handler/influxdbHandler.py): `src/diamond/handler/influxdbHandler.py`
- [HTTP POST handler](https://github.com/python-diamond/diamond/blob/master/src/diamond/handler/httpHandler.py): `src/diamond/handler/httpHandler.py`
- [Librato handler](https://github.com/python-diamond/diamond/blob/master/src/diamond/handler/libratohandler.py): `src/diamond/handler/libratohandler.py`

### Other components

- **Monitored systems**
- **Service APIs**
- **Graphite**
- **InfluxDB**
- **HTTP endpoint**
- **Librato**

## Connections

- Diamond server → Configuration utilities: loads settings
- Diamond server → Collector scheduler: manages polling
- Diamond server → Metric queue: creates queue
- Diamond server → Collector API: loads collectors
- Collector scheduler → Host collectors: schedules
- Collector scheduler → Service collectors: schedules
- Collector scheduler → Database collectors: schedules
- Collector scheduler → Custom collectors: schedules
- Monitored systems → Host collectors: read metrics
- Service APIs → Service collectors: query APIs
- Service APIs → Database collectors: query databases
- Collector API → Metric model: publishes metrics
- Host collectors → Metric model: publishes metrics
- Service collectors → Metric model: publishes metrics
- Database collectors → Metric model: publishes metrics
- Custom collectors → Metric model: publishes metrics
- Metric model → Metric queue: queued for dispatch
- Diamond server → Handler framework: loads handlers
- Metric queue → Handler framework: dispatches metrics
- Handler framework → Graphite handler: processes metrics
- Handler framework → InfluxDB handler: processes metrics
- Handler framework → HTTP POST handler: processes metrics
- Handler framework → Librato handler: processes metrics
- Graphite handler → Graphite: publishes
- InfluxDB handler → InfluxDB: publishes
- HTTP POST handler → HTTP endpoint: POSTs batches
- Librato handler → Librato: submits metrics