Statistics reporting

openstacksdk can report statistics on individual API requests/responses in several different formats.

Note that metrics will be reported only when corresponding client libraries (statsd for ‘statsd’ reporting, influxdb for influxdb, etc.) are installed. If libraries are not available then reporting will be silently ignored.

statsd

statsd reporting can be configured via configuration entries or environment variables.

A global metrics entry defines defaults for all clouds. Each cloud can specify a metrics section to override variables; this may be useful to separate results reported for each cloud.

metrics:
  statsd:
    host: __statsd_server_host__
    port: __statsd_server_port__
    prefix: __statsd_prefix__ (default 'openstack.api')
clouds:
  a-cloud:
    auth:
     ...
    metrics:
      statsd:
        prefix: 'openstack.api.a-cloud'

If the STATSD_HOST, STATSD_PORT, or STATSD_PREFIX environment variables are set, they will be taken as the default values (and enable statsd reporting if no other configuration is specified).

Alternatively, statsd can be configured programmatically by passing a statsd_config dict to CloudRegion:

import openstack.config

config = openstack.config.OpenStackConfig()
cloud = config.get_one_cloud(
    cloud='my-cloud',
    statsd_config={
        'host': 'statsd.example.com',
        'port': 8125,
        'prefix': 'openstack.api.my-cloud',
    },
)

InfluxDB

Deprecated since version 4.11.0: InfluxDB support requires the influxdb library, which only supports InfluxDB 1.x and is itself deprecated. InfluxDB support in openstacksdk is therefore also deprecated and will be removed in a future release.

InfluxDB reporting can be configured via configuration entries.

As with statsd, each cloud can provide its own metrics section to override any global defaults.

metrics:
  influxdb:
    host: __influxdb_server_host__
    port: __influxdb_server_port__
    use_udp: __True|False__
    username: __influxdb_auth_username__
    password: __influxdb_auth_password__
    database: __influxdb_db_name__
    measurement: __influxdb_measurement_name__
    timeout: __infludb_requests_timeout__
clouds:
  ..

InfluxDB reporting allows setting additional tags into the metrics based on the selected cloud.

clouds:
  my_cloud:
    profile: some_profile
    ...
    additional_metric_tags:
      environment: production

Prometheus

Prometheus reporting is not configured via configuration entries. Unlike statsd and InfluxDB, Prometheus works on a pull basis. openstacksdk does not run the necessary HTTP service since it is a library. Instead, an application that uses openstacksdk and wants request stats collected should create a CollectorRegistry and pass it via the prometheus_config argument to CloudRegion. The application is then responsible for exposing the registry over HTTP.

import prometheus_client
import openstack.config

registry = prometheus_client.CollectorRegistry()

config = openstack.config.OpenStackConfig()
cloud = config.get_one_cloud(
    cloud='my-cloud',
    prometheus_config={
        'collector_registry': registry,
    },
)

# Use the cloud object; metrics will be recorded in the registry.
# Start the HTTP server to expose metrics to Prometheus.
prometheus_client.start_http_server(8000, registry=registry)