cloudkitty — Interactions

Interactions with other components — CloudKitty — branch stable/2026.2

Branch stable/2026.2 @ 0685cc330e83 — repository https://opendev.org/openstack/cloudkitty — analysed on 2026-11-09

1. RabbitMQ (oslo.messaging RPC)

CloudKitty uses RPC only between its own API and its own processor. It emits no notification and consumes none (no Notifier or notification listener in the code; cloudkitty/messaging.py:25-80).

1.1 Topology

Queues (oslo.messaging rabbit driver conventions [inferred]): cloudkitty (shared), cloudkitty.<host> (direct), cloudkitty_fanout_<uuid> (fanout, one per server).

1.2 RPC methods

1.3 Sample frame (quote call, oslo.messaging v2 envelope [inferred])

{"oslo.version": "2.0",
 "oslo.message": "{\"method\": \"quote\", \"namespace\": \"rating\", \"version\": \"1.0\",
   \"args\": {\"res_data\": {\"usage\": {\"instance\": [
      {\"desc\": {\"groupby\": {\"project_id\": \"p1\"}, \"metadata\": {\"flavor_name\": \"m1.small\"}},
       \"vol\": {\"qty\": \"1\", \"unit\": \"undef\"}}]}}},
   \"_msg_id\": \"…\", \"_reply_q\": \"reply_…\", \"_unique_id\": \"…\", \"_context_…\": …}"}

Reply: {"result": "0.0420", "failure": null, "ending": true}.

2. Database

2.1 Access

oslo.db enginefacade with a thread-local context, SQLite foreign keys enabled (cloudkitty/db/__init__.py:20-38); [database]/connection. Schemas are managed by separate Alembic trees (one version table each [inferred]): core (cloudkitty/db/sqlalchemy/alembic/versions/), hashmap, pyscripts, storage-state, v1 storage. cloudkitty-dbsync upgrade migrates core + rating modules (cloudkitty/cli/dbsync.py:43-75); cloudkitty-storage-init migrates the storage-state tables (cloudkitty/cli/storage.py:21-25, cloudkitty/storage_state/__init__.py:236-237).

2.2 Tables

Money columns: hashmap cost NUMERIC(40,28), threshold level NUMERIC(20,8) (cloudkitty/rating/hash/db/sqlalchemy/models.py:230-232, cloudkitty/rating/hash/db/sqlalchemy/models.py:306-311). Rated prices are not stored in SQL with v2 storage.

2.3 Representative queries (reconstructed)

Active mappings of a service for the period being rated (cloudkitty/rating/hash/db/sqlalchemy/api.py:178-215, cloudkitty/rating/common/db/filters.py:19-53), run twice per service (tenant NULL, then the scope):

SELECT m.mapping_id FROM hashmap_mappings m
  JOIN hashmap_services s ON s.id = m.service_id
 WHERE s.service_id = :service_uuid
   AND m.tenant_id <=> :tenant           -- NULL or the scope id
   AND m.start <= :period_start AND (m.end > :period_start OR m.end IS NULL)
   AND m.deleted IS NULL;

Each id is then re-read with get_mapping (one query per mapping, plus its group) (cloudkitty/rating/hash/__init__.py:50-69). Cost per scope cycle: 1 + Σ_services (1 + 4 + fields × (1 + 4)) + one query per rule — every cycle, for every scope, in every worker.

Overlap check at mapping creation (cloudkitty/rating/hash/db/sqlalchemy/api.py:340-393):

SELECT * FROM hashmap_mappings
 WHERE deleted IS NULL
   AND (name = :name OR ( <window overlaps> AND value = :value AND tenant_id = :tenant
                          AND <field_id|service_id> = :parent AND group_id = :group))
FOR UPDATE;

<window overlaps> is start < :end AND (end >= :start OR end IS NULL) when an end is given, else start > :start OR end IS NULL. Note that tenant_id = NULL / group_id = NULL comparisons are never true in SQL, so global or ungrouped duplicates are caught only by the unique keys [inferred].

Next period of a scope (cloudkitty/storage_state/__init__.py:116-146):

SELECT * FROM cloudkitty_storage_states
 WHERE identifier = :scope AND scope_key = :key AND fetcher = :fetcher AND collector = :collector
 LIMIT 1;
-- fallback for legacy rows: same identifier with scope_key/fetcher/collector IS NULL, then filled in

Unfinished reprocessing schedules (cloudkitty/storage_state/__init__.py:310-347): WHERE current_reprocess_time IS NULL OR current_reprocess_time < end_reprocess_time ORDER BY id DESC LIMIT … OFFSET … (the order is injected with sql.text("id %s" % order) after the API has validated it).

2.4 Transactions and locks

• SELECT … FOR UPDATE on mapping creation, update and delete, threshold update, group delete, module state/priority writes (cloudkitty/rating/hash/db/sqlalchemy/api.py:393, cloudkitty/rating/hash/db/sqlalchemy/api.py:506, cloudkitty/rating/hash/db/sqlalchemy/api.py:636, cloudkitty/db/sqlalchemy/api.py:96-110).
• No lock protects the scope state in SQL: concurrency between workers relies on the tooz lock (§ 6).

3. Collectors (usage sources)

The collector is chosen by [collect]/collector (gnocchi by default) and loaded through stevedore with the validated metric file (cloudkitty/collector/__init__.py:39-56, cloudkitty/collector/__init__.py:122-132).

3.1 Metric file (common part)

Per metric (cloudkitty/collector/__init__.py:81-119, cloudkitty/collector/__init__.py:191-227):

Every collected point also receives groupby keys week_of_the_year, day_of_the_year, month, year computed from the period start (cloudkitty/collector/__init__.py:285-309).

3.2 Gnocchi

Cost per scope and period: one aggregates call per metric (+ one paginated resource search per metric with metadata). Calls for one scope run in a thread pool of [orchestrator]/max_threads (16) with a global timeout of collector_request_timeout (300 s) (cloudkitty/orchestrator.py:70-98, cloudkitty/orchestrator.py:378-391).

3.3 Prometheus and Aetos

Example for etc/cloudkitty/metrics.yml entry openstack_nova_server_status (unit instance, groupby id, metadata flavor_name, period 3600):

max(max_over_time(openstack_nova_server_status{project_id="p1"}[3600s])) by (id, project_id, flavor_name)

The scope id is injected into PromQL by string formatting (cloudkitty/collector/prometheus_base.py:131-136); scope ids come from the fetcher, not from API users.

4. Fetchers (scope discovery)

Chosen by [fetcher]/backend (keystone by default) (cloudkitty/fetcher/__init__.py:20-26). Called at the start of every processor loop, in every worker (cloudkitty/orchestrator.py:760-765).

Costs: the Keystone fetcher makes 1 + N requests per loop and per worker (N = number of projects) unless ignore_rating_role is set; the Gnocchi fetcher sends an ever-growing not in list, so the request size grows with the number of scopes.

5. Storage back ends (rated data)

Chosen by [storage]/version (2) and [storage]/backend (influxdb) (cloudkitty/storage/__init__.py:29-43, cloudkitty/storage/__init__.py:195-212). Contract (cloudkitty/storage/v2/__init__.py:43-167): init, push(frames, scope_id), retrieve(begin, end, filters, metric_types, offset, limit, paginate), delete(begin, end, filters), total(groupby, begin, end, metric_types, filters, custom_fields, offset, limit, paginate).

5.1 InfluxDB (default)

Point written (one per DataPoint, cloudkitty/storage/v2/influx.py:156-195):

{"measurement": "dataframes",
 "time": "2026-11-09T10:00:00+00:00",
 "tags":   {"type": "instance", "project_id": "p1", "id": "vm-1", "user_id": "u1",
            "week_of_the_year": "45", "day_of_the_year": "313", "month": "11", "year": "2026"},
 "fields": {"qty": 1.0, "price": 0.042, "unit": "instance", "description": null,
            "flavor_name": "m1.small",
            "groupby": "type|project_id|id|user_id|week_of_the_year|day_of_the_year|month|year",
            "metadata": "flavor_name", "__ck_collect_period": 3600}}

groupby attributes are tags (indexed, high cardinality with id), metadata attributes are fields. InfluxQL text is assembled by string formatting from API filters (cloudkitty/storage/v2/influx.py:198-227). The v2 retrieve ignores the metric-type filter (cloudkitty/storage/v2/influx.py:523-533).

5.2 Elasticsearch and OpenSearch

OpenSearch differs only by .keyword sub-fields in aggregations and the mapping call (cloudkitty/storage/v2/opensearch/client.py:100-171).

5.3 Loki

The stream label is always named project_id, whatever [collect]/scope_key is (cloudkitty/storage/v2/loki/client.py:329-331).

5.4 v1 storage (deprecated)

sqlalchemy writes rated_data_frames; hybrid keeps state in SQL and data in Gnocchi resource types rating_service_* (cloudkitty/storage/v1/sqlalchemy/__init__.py:36-196, cloudkitty/storage/v1/hybrid/backends/gnocchi.py:100-111). Wrapped by V1StorageAdapter, which only understands the project_id filter and type/project_id group-bys, and whose delete does nothing (cloudkitty/storage/__init__.py:64-192).

6. Coordination (tooz)

Back end [orchestrator]/coordination_url, default file:///var/lib/cloudkitty/locks — a host-local lock: several processor hosts need a shared back end (etcd, ZooKeeper, MySQL…) [inferred from tooz semantics]. Each worker also starts a coordinator with heartbeat (cloudkitty/orchestrator.py:657-661). Note that the reprocessing lock name differs from the rating lock, so a scope can be rated and reprocessed at the same time [inferred].

7. Keystone

8. Other

• Files read: the metric file at every Worker creation and every /v1/info call (cloudkitty/orchestrator.py:301, cloudkitty/api/v1/controllers/info.py:36-39); etc/cloudkitty/api_paste.ini at API start (cloudkitty/api/app.py:77-91).
• Code execution: exec of pyscripts and eval of skip_datapoints_expression inside the processor (cloudkitty/rating/pyscripts/__init__.py:98-101, cloudkitty/orchestrator.py:494-507).
• No subprocess, no privsep, no OVSDB, no cache server.

Source: reverse-spec-cloudkitty/03-interactions_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.