Prometheus Todoist Exporter

Extract Todoist API metrics via Prometheus with this exporter.

Important

This project is not affiliated with Todoist. It is a community-driven project.

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_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

Grafana Dashboard

This project includes a pre-configured Grafana dashboard to visualize the exported metrics. You can find the dashboard definition in grafana/dashboard.json.

To import the dashboard into your Grafana instance:

1. Navigate to your Grafana UI.
2. Go to Dashboards -> Browse.
3. Click the Import button (usually in the top right).
4. Click Upload JSON file and select the grafana/dashboard.json file from this repository.
5. Alternatively, you can paste the JSON content directly into the text area.
6. Configure the dashboard options, such as selecting your Prometheus data source.
7. Click Import.

This dashboard provides panels for visualizing active tasks, completion trends, task breakdowns by project/priority/label, and exporter health metrics.

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 Kubernetes

Kubernetes manifests are provided in the deploy/kubernetes directory. These can be applied directly or deployed with Kustomize.

1. Create the namespace:

   kubectl create namespace monitoring

2. Create a Secret with your Todoist API token:

   TODOIST_API_TOKEN_B64=$(echo -n 'your-todoist-api-token' | base64)
   sed "s/<BASE64_ENCODED_API_TOKEN>/$TODOIST_API_TOKEN_B64/" deploy/kubernetes/secret.yaml | kubectl apply -f -

   Or create the Secret manually:

   kubectl create secret generic todoist-secret -n monitoring --from-literal=api-token=your-todoist-api-token

3. Deploy with Kustomize:

   kubectl apply -k deploy/kubernetes

4. To access the metrics endpoint:

   kubectl port-forward -n monitoring service/prometheus-todoist-exporter 9090:9090

5. View the metrics at http://localhost:9090/metrics

Using Helm

A Helm chart is available in the deploy/helm/prometheus-todoist-exporter directory.

1. Deploy the chart:

   helm install todoist-exporter ./deploy/helm/prometheus-todoist-exporter \
     --namespace monitoring --create-namespace \
     --set todoist.apiToken="your-todoist-api-token"

2. Configure with custom values:

   helm install todoist-exporter ./deploy/helm/prometheus-todoist-exporter \
     --namespace monitoring --create-namespace \
     --set todoist.apiToken="your-todoist-api-token" \
     --set exporter.collectionInterval=30 \
     --set service.type=NodePort

3. Using a custom values file:

   # Create a values.yaml file with your custom configuration
   cat > my-values.yaml << EOF
   todoist:
     apiToken: "your-todoist-api-token"
   exporter:
     collectionInterval: 30
   serviceMonitor:
     enabled: true
   EOF
   
   # Install with custom values
   helm install todoist-exporter ./deploy/helm/prometheus-todoist-exporter \
     --namespace monitoring --create-namespace \
     --values my-values.yaml

4. To upgrade the deployment:

   helm upgrade todoist-exporter ./deploy/helm/prometheus-todoist-exporter \
     --namespace monitoring \
     --reuse-values \
     --set exporter.completedTasksDays=14

5. To uninstall:

   helm uninstall todoist-exporter --namespace monitoring

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

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

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

# Deploy to Kubernetes with kustomize
task k8s-deploy

# Delete Kubernetes deployment
task k8s-delete

# Deploy with Helm
task helm-deploy

# Delete Helm deployment
task helm-delete

# Lint Helm chart
task helm-lint

# Generate Kubernetes manifests from Helm chart
task helm-template

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

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:

   • POETRY_PYPI_TOKEN_PYPI: 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:
     ```bash
     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

Helm Chart Management

The project includes a Helm chart in the deploy/helm/prometheus-todoist-exporter directory. When making changes to the Helm chart, follow these guidelines:

Chart Versioning

1. The Helm chart follows semantic versioning (major.minor.patch)
2. Chart version is specified in deploy/helm/prometheus-todoist-exporter/Chart.yaml
3. When updating the chart:
   • For non-breaking changes, increment the patch version
   • For new features (non-breaking), increment the minor version
   • For breaking changes, increment the major version

Testing Chart Changes

Before committing chart changes:

1. Lint the chart:

   task helm-lint

2. Test template rendering:

   task helm-template

3. Test installation in a dev environment:

   task helm-deploy

Chart Documentation

Keep the chart documentation in deploy/helm/prometheus-todoist-exporter/README.md synchronized with any changes to:

• Chart parameters and defaults
• Required Kubernetes versions
• Examples

Release Process

When a new version of the exporter is released, the chart's appVersion should be updated to match the released version.