Metadata-Version: 2.4
Name: beanstalkd-exporter
Version: 0.1.1
Summary: Prometheus exporter with Beanstalkd server
Author-email: this-made-ai <this.made.ai@gmail.com>
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: prometheus-client==0.26.0
Requires-Dist: PyYAML==6.0.3
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# beanstalkd-exporter

Prometheus metrics exporter for Beanstalkd, running as a single service (with Beanstalkd and the Exporter running).

## Installation

### As a standalone Pip Package

You can install the exporter directly via `pip`:

```bash
pip install beanstalkd-exporter
```

Once installed, you can start the exporter. By default, it connects to a running Beanstalkd instance on `127.0.0.1:11300`.

```bash
beanstalkd-exporter
```

#### Configuration Environment Variables
- `LISTEN_HOST`: Host for the Prometheus metrics server to listen on (default: `0.0.0.0`)
- `EXPORTER_PORT`: Port for the Prometheus metrics server (default: `9419`)
- `BEANSTALK_PORT`: Port where Beanstalkd is running (default: `11300`)
- `SCRAPE_INTERVAL`: How often to scrape metrics in seconds (default: `5.0`)

### As a Unified Docker Container

The provided Docker image serves as a universal container. It starts both the `beanstalkd` daemon and the `beanstalkd-exporter` service automatically.

```bash
docker pull madebyai/beanstalkd-exporter:latest
docker run -d --name beanstalkd-exporter -p 11300:11300 -p 9419:9419 madebyai/beanstalkd-exporter:latest
```

Metrics will be available at `http://localhost:9419/metrics`. Beanstalkd will be accessible on `11300`.

## What It Does

This exporter connects to a local Beanstalkd server, regularly runs `stats` and `stats-tube` commands, and converts the responses to Prometheus format.

### Exported Metrics

Metrics are prefixed with `beanstalk_` and map directly to native Beanstalkd stats.

**Global Server Metrics:**
- `beanstalk_current_jobs_ready` (Gauge): Total ready jobs across all tubes.
- `beanstalk_current_connections` (Gauge): Active connections to the server.
- `beanstalk_cmd_put_total` (Counter): Cumulative number of `put` commands.
- *...and all other standard global Beanstalkd stats.*

**Tube-Specific Metrics:** (These include the `tube="<tube_name>"` label)
- `beanstalk_tube_current_jobs_ready` (Gauge): Ready jobs in a specific tube.
- `beanstalk_tube_cmd_delete_total` (Counter): Number of delete commands issued in a specific tube.
- *...and all other standard tube-level Beanstalkd stats.*

**Exporter Health Metrics:**
- `beanstalk_up`: `1` if Beanstalkd is reachable and successfully scraped, `0` otherwise.
- `beanstalk_exporter_scrape_duration_seconds`: Time taken to complete a scrape cycle.
- `beanstalk_exporter_scrape_errors_total`: Number of errors encountered while scraping.

## Example: Prometheus Configuration

To configure Prometheus to scrape this exporter, simply add a new job to your `prometheus.yml` file:

```yaml
scrape_configs:
  - job_name: 'beanstalkd'
    scrape_interval: 5s
    static_configs:
      - targets: ['localhost:9419']
```

## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.

**Author:** [made-ai](https://github.com/made-ai)
