Carbon for receiving and persisting Graphite metrics

Carbon's place in the Graphite metric pipeline

Carbon solves the ingestion and persistence stage of a Graphite deployment. It is intended for operators that collect measurements from networked applications, hosts, and services and need those measurements available to the rest of Graphite. The README identifies three distinct components: Graphite-Web, which renders graphs and dashboards; Carbon's metric processing daemons; and Whisper, the time-series database library. That division is important because Carbon is not the complete Graphite system.

Its specific responsibility is to receive metrics over the network. It then keeps those values in memory for recent queries associated with Graphite-Web and writes them to disk through Whisper. This makes Carbon the bridge between metric producers and the stored time-series files that Graphite-Web can query. A deployment that only needs graph rendering does not need Carbon for that purpose, while a deployment that already has compatible network producers still needs a receiver such as Carbon before those values can enter the Graphite storage path.

How Carbon handles incoming time-series values

The documented data flow has three operations: network receipt, in-memory caching, and disk persistence. Carbon accepts metric data from clients over the network. Recent data is cached in memory for "hot queries" from Graphite-Web. The same component then persists data through the Whisper time-series library.

This design separates a fast query path from durable storage. The cache serves recent Graphite-Web requests, while Whisper handles data written to disk. Carbon therefore performs both a transport role and a processing-buffer role. It is not merely an HTTP or TCP endpoint, and it is not merely a file writer. Its operational behavior depends on the interaction between client protocols, cache behavior, daemon configuration, and the selected storage setup.

The top-level `conf/` directory indicates that configuration is packaged with the repository, but the README directs readers to the Graphite documentation instead of explaining those settings. Consequently, a review of Carbon should not assume that receiving a metric necessarily makes it immediately durable. The repository only confirms the intended combination of network receipt, memory caching, and Whisper-backed persistence.

Installing Carbon without assuming undocumented daemon steps

The README does not provide a complete installation or first-run tutorial. It sends readers to `http://graphite.readthedocs.org/` for instructions, so the official Graphite documentation is the real source for daemon setup and usage. The repository's `setup.py` does print an installation command when `GRAPHITE_NO_PREFIX` is present. This command places Carbon in Python's default location rather than the historical `/opt/graphite` prefix.

The script states the following command:

$ GRAPHITE_NO_PREFIX=True python setup.py install

That command addresses installation into the active Python environment, but it does not by itself establish a working Graphite installation. The README does not say how to create or edit the daemon configuration, which daemon to launch, or which client command sends a first metric. It also does not document a verification command for checking a newly written Whisper file. Those operations would have to come from the linked documentation, not from inference.

The repository includes `examples/example-client.py`, `examples/example-pickle-client.py`, and `examples/example-protobuf-client.py`. Their filenames indicate that the project includes plain Python, pickle, and protobuf client examples. The README does not state arguments or execution commands for these examples. A first real use therefore begins with a Carbon daemon configured through the Graphite documentation, followed by one of those clients only after its documented invocation has been checked.

Package dependencies and the Whisper boundary

Carbon's declared runtime dependencies show that it is not a dependency-free file writer. `requirements.txt` lists `Twisted>=13.2.0`, Whisper from its Git repository, `txAMQP`, `cachetools`, and `urllib3`. Whisper supplies the on-disk time-series format and persistence layer.

The Whisper dependency uses a direct Git URL in `requirements.txt`:

git+https://github.com/graphite-project/whisper.git#egg=whisper

No commit or tag is shown in that line. As a result, the exact Whisper revision selected during installation is not established by the repository content. That is a concrete upgrade concern because Carbon's storage behavior depends on Whisper. Operators changing Carbon or its Python environment should first confirm which Whisper revision their existing Graphite deployment uses.

The presence of `txAMQP` suggests support for an AMQP-based path in the dependency set, but the README does not describe how that path is configured or which operational mode it serves. It would be unsafe to present AMQP as a ready first-use option without the missing configuration and command documentation. The confirmed default role is narrower: receive metrics, cache recent values, and persist them with Whisper.

Why Carbon differs from Graphite-Web and Whisper

The clearest alternative comparison is with the other named Graphite components, although they are not direct substitutes. Graphite-Web is a Django application for rendering graphs and dashboards. It sits downstream of stored metric data and does not serve as Carbon's network metric receiver. Whisper is the time-series database library that writes data to disk. Carbon is the daemon layer connecting network input and Whisper storage.

Carbon is therefore the appropriate choice when the missing capability is ingestion, caching, and forwarding into Graphite's storage model. Whisper alone is the relevant alternative when the requirement is the on-disk time-series library rather than a network-facing metric processing daemon. Graphite-Web is relevant when the requirement is dashboards and graph rendering. None of those descriptions turns Whisper or Graphite-Web into a complete replacement for Carbon's stated responsibilities.

Carbon is the wrong tool for organizations that need only a local library, a visualization application, or a general-purpose database interface. It also adds operational responsibilities associated with a daemon and Python service. The README does not cover deployment hardening, authentication, high availability, capacity planning, or backup procedures, so none should be assumed from adoption.

Carbon maintenance, releases, and Apache-2.0 obligations

The repository is not archived. Its last push was on 2026-09-30, which is a more recent maintenance signal than the release list alone. The latest listed releases are 1.1.10 from 2022-05-22, 1.1.8 from 2021-04-18, and 1.1.7 from 2020-03-16. The gap between recent repository activity and older listed releases means that commit activity and published package releases should be evaluated separately.

The README and repository metadata identify the Apache License, version 2.0, as `Apache-2.0`. The `LICENSE` file is the authoritative project license text. This article does not provide legal interpretation or dependency license conclusions. An adopter still needs to account for the licenses of Python, Twisted, Whisper, `txAMQP`, `cachetools`, and `urllib3` in its own distribution and compliance review.

Upgrade cost is not fully quantified in the repository. The presence of a direct Git dependency on Whisper, daemon configuration under `conf/`, and storage created through Whisper means that a Carbon upgrade should be considered alongside the Graphite configuration and existing data files. The repository does not document a formal upgrade procedure or rollback command.

Editorial conclusion

Adopt Carbon when an existing Graphite deployment needs a Python daemon to receive network metrics, cache recent values, and write time-series data through Whisper. Do not choose it for graph rendering or as a standalone time-series database. Verify the current installation procedure, daemon configuration, supported Python environment, and Whisper compatibility first. Based on the repository metadata, the last push was on 2026-09-30, although the newest listed release is 1.1.10 from 2022-05-22.

Frequently asked questions

Official sources

1. graphite-project/carbon on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases