Graphyte

1.7.1 verified Mon Apr 27 auth: no python maintenance

A simple Python 3 compatible library to send metrics to a Graphite Carbon server (plaintext or pickle protocol, TCP or UDP). Current version: 1.7.1. Low release cadence (last update 2020).

pip install graphyte

Common errors

error ModuleNotFoundError: No module named 'graphyte' ↓

cause Package not installed or installed for wrong Python version.

fix

Run 'pip install graphyte' and verify you're using Python 3.

error AttributeError: module 'graphyte' has no attribute 'init' ↓

cause Common mistake: import graphyte; graphyte.init() but init is not a top-level attribute of the package.

fix

Use 'from graphyte import init' instead.

error graphyte.exceptions.InvalidMetric: name 'test.load' contains non-graphite-compatible characters ↓

cause Metric names must match Graphite's allowed characters (alphanumeric, underscores, hyphens, dots).

fix

Remove illegal characters from metric name. For example, 'test.load' is fine, but 'test load' is not.

error Connection refused or timeout when sending metrics ↓

cause Graphite Carbon server is not running on the specified host/port or network issues.

fix

Verify Carbon is running: check host/port, ensure firewall allows traffic, test with 'nc -v <host> <port>'.

Warnings

breaking Python 2 is not supported. Graphyte requires Python 3. Using it with Python 2 will fail. ↓

fix Use Python 3.6+.

gotcha The default protocol is TCP. To use UDP, you must pass protocol='udp' when initializing the sender. ↓

fix For UDP metrics: init('localhost', protocol='udp') or Sender('localhost', protocol='udp').

gotcha Tags with whitespace in keys or values will be rejected (since v1.6.0). Metric paths with spaces may also cause issues. ↓

fix Ensure tag keys and values do not contain spaces. Use underscores or other separators.

deprecated The old import path 'graphyte.init' is still supported but using 'from graphyte import init' is preferred. ↓

fix Use 'from graphyte import init'.

Imports

init
```
from graphyte import init
```
Sender
```
from graphyte import Sender
```

Quickstart

Initialize a default sender and send a metric. Uses environment variables for configuration.

import os
from graphyte import init, send

# Initialize with default sender (uses GRAPHITE_HOST env var or 'localhost')
init(
    host=os.environ.get('GRAPHITE_HOST', 'localhost'),
    port=int(os.environ.get('GRAPHITE_PORT', 2003)),
    prefix=os.environ.get('GRAPHITE_PREFIX', 'test')
)

# Send a metric
send('cpu.load', 0.5, timestamp=1234567890)