prometheus-todoist-exporter 0.1.0

A Prometheus exporter for Todoist

Prometheus Todoist Exporter

Extract Todoist API metrics via Prometheus with this exporter.

Features

• Collects metrics from the Todoist API using the official Python client
• Exposes these metrics in Prometheus format
• Provides comprehensive task, project, collaborator, section, and comment metrics
• Tracks completed tasks through the Todoist Sync API
• Monitors tasks by labels, sections, and due dates
• Configurable through environment variables
• Includes Docker support for easy deployment
• Uses Poetry for dependency management
• Includes Taskfile for command orchestration
• Manages tool versions with asdf
• Uses Ruff for lightning-fast Python linting and formatting

Metrics

The exporter provides the following metrics:

Metric	Description	Labels
todoist_tasks_total	Total number of active tasks	project_name, project_id
todoist_tasks_overdue	Number of overdue tasks	project_name, project_id
todoist_tasks_due_today	Number of tasks due today	project_name, project_id
todoist_tasks_completed	Number of completed tasks (counter)	project_name, project_id
todoist_project_collaborators	Number of collaborators per project	project_name, project_id
todoist_sections_total	Number of sections per project	project_name, project_id
todoist_comments_total	Number of comments	project_name, project_id
todoist_priority_tasks	Number of tasks by priority	project_name, project_id, priority
todoist_api_errors	Number of API errors encountered	endpoint
todoist_scrape_duration_seconds	Time taken to collect Todoist metrics	-
todoist_tasks_completed_today	Number of tasks completed today	project_name, project_id
todoist_tasks_completed_week	Number of tasks completed in the last N days	project_name, project_id, days
todoist_tasks_completed_hours	Number of tasks completed in the last N hours	project_name, project_id, hours
todoist_section_tasks	Number of tasks in a section	project_name, project_id, section_name, section_id
todoist_label_tasks	Number of tasks with a specific label	label_name
todoist_tasks_with_due_date	Number of tasks with a due date	project_name, project_id
todoist_recurring_tasks	Number of recurring tasks	project_name, project_id
todoist_sync_api_completed_tasks	Number of tasks completed via Sync API	project_name, project_id, timeframe

Configuration

The exporter can be configured using environment variables:

Variable	Description	Default
TODOIST_API_TOKEN	Todoist API token (required)	-
EXPORTER_PORT	Port for the HTTP server	9090
METRICS_PATH	HTTP path for metrics	/metrics
COLLECTION_INTERVAL	Seconds between metric collections	60
COMPLETED_TASKS_DAYS	Number of days to look back for completed tasks	7
COMPLETED_TASKS_HOURS	Number of hours to look back for completed tasks	24

Installation

Using Docker

Pull the latest image from GitHub Container Registry:

docker pull ghcr.io/echohello-dev/prometheus-todoist-exporter:latest

Run the exporter:

docker run -p 9090:9090 -e TODOIST_API_TOKEN=your_api_token ghcr.io/echohello-dev/prometheus-todoist-exporter:latest

Using Docker Compose

1. Copy the example environment file and edit it with your API token:

cp .env.example .env
# Edit .env with your Todoist API token

2. Then start the services:

docker-compose up -d

This will start both the Todoist exporter and a Prometheus instance configured to scrape metrics from the exporter.

Using Poetry

1. Install Poetry (if not already installed):

   curl -sSL https://install.python-poetry.org | python3 -
   

2. Install the package:

   poetry add prometheus-todoist-exporter
   

3. Set up your environment variables:

   cp .env.example .env
   # Edit .env with your Todoist API token
   

4. Run the exporter:

   source .env && poetry run todoist-exporter
   

Local Development

Quick Start

1. Clone the repository:

   git clone https://github.com/echohello-dev/prometheus-todoist-exporter.git
   cd prometheus-todoist-exporter
   

2. Set up development environment:

   task setup-dev
   

   This will:

   • Copy .env.example to .env (if it doesn't exist)
   • Install dependencies via Poetry
   • Install pre-commit hooks

3. Edit the .env file with your Todoist API token:

   # Edit .env with your preferred editor
   nano .env
   

4. Run the exporter:

   source .env && task run
   

Using asdf for tool version management

This project uses asdf to manage tool versions (Python, Poetry, Task).

1. Install asdf following the installation instructions.

2. Clone the repository:

   git clone https://github.com/echohello-dev/prometheus-todoist-exporter.git
   cd prometheus-todoist-exporter
   

3. Install the required tools with asdf:

   task setup
   

   This will install the correct versions of Python, Poetry, and Task as specified in .tool-versions, and set up your development environment.

4. Run the exporter:

   source .env && task run
   

5. Run tests:

   task test
   

Pre-commit Hooks

This project uses pre-commit to enforce code quality and standards. The hooks ensure that all code commits meet the project's requirements.

To install the pre-commit hooks:

task pre-commit-install

To manually run the pre-commit checks:

task pre-commit-run

The following checks are included:

• Code formatting with Ruff
• Linting with Ruff
• Basic file checks (trailing whitespace, YAML validation, etc.)
• Poetry configuration verification
• Running tests

Using Taskfile

This project includes a Taskfile for easy command orchestration. You need to have Task installed, or you can use the version installed by asdf.

Available tasks:

# Set up local development environment (copy .env.example to .env and install deps)
task setup-dev

# Set up asdf with all required tools
task setup

# Install dependencies
task install

# Format the code with Ruff
task format

# Run linting with Ruff
task lint

# Run linting and fix issues with Ruff
task lint-fix

# Run tests
task test

# Run the exporter
task run

# Install pre-commit hooks
task pre-commit-install

# Run pre-commit checks on all files
task pre-commit-run

# Update pre-commit hooks to latest versions
task pre-commit-update

# Build Docker image
task docker-build

# Run Docker container
task docker-run

# Run all quality checks (format, lint, test)
task all

# Start services with docker-compose
task docker-compose-up

# Stop services with docker-compose
task docker-compose-down

Building from Source

1. Clone the repository:

   git clone https://github.com/echohello-dev/prometheus-todoist-exporter.git
   cd prometheus-todoist-exporter
   

2. Install tools and dependencies (requires asdf):

   task setup-asdf
   task install
   

3. Build the Docker image:

   task docker-build
   

License

This project is licensed under the MIT License.

GitHub Workflow Setup

This repository uses GitHub Actions workflows for continuous integration, release management, and container publishing.

Workflow Overview

1. CI Workflow (ci.yml)

   • Runs linting and tests for every push and pull request
   • Ensures code quality and functionality

2. Release Please Workflow (release-please.yml)

   • Automates versioning and release creation
   • Creates a PR with version bump and changelog updates
   • When merged, creates a GitHub release with appropriate tags

3. PyPI Publish Workflow (publish-pypi.yml)

   • Triggered when Release Please creates a new release
   • Builds and publishes the Python package to PyPI

4. Docker Publish Workflow (docker-publish.yml)

   • Builds and tests the Docker image
   • Publishes the image to GitHub Container Registry (ghcr.io)
   • Tags the image with:
     • Latest release version
     • Latest tag (for release only)
     • Branch name (for non-release builds)
     • Git SHA

Required Secrets

To enable these workflows, ensure the following secrets are set in your repository:

1. For PyPI publishing:

   • PYPI_API_TOKEN: A PyPI API token with upload permissions

2. For Docker publishing:

   • GitHub Token with packages:write permission (automatic)

Development to Production Workflow

1. Local Development

   • Set up local environment using:

     cp .env.example .env  # Add your Todoist API token
     task setup-dev  # Install dependencies
     

   • Make code changes and test locally with:

     source .env && task run
     

2. Submit Changes

   • Create a pull request with your changes
   • CI will run tests to ensure quality

3. Release Process

   • Release Please will automatically create a release PR when changes are merged to main
   • When the release PR is merged:
     • A GitHub release is created
     • The PyPI package is published
     • The Docker container is built and published to GHCR

4. Using the Released Version

   • Pull the latest container image:

     docker pull ghcr.io/echohello-dev/prometheus-todoist-exporter:latest
     

   • Or run with docker-compose:

     cp .env.example .env  # Add your Todoist API token
     docker-compose up -d