oura-exporter

Every data point of the Oura Ring API in Prometheus, at the time it was measured: each heart rate sample, the 5-minute sleep HRV, heart rate and sleep phases, MET per minute, battery samples, workouts, sessions, tags and the daily scores. Based on legnoh/oura-exporter.

How it works

Oura delivers data late, in bulk and with timestamps in the past, which a scrape cannot represent. The exporter therefore pushes samples with their real measurement time via Prometheus remote write and only serves its own health metrics on /metrics.

The receiver must accept remote write and out-of-order samples. Every fetch re-reads the last OURA_LOOKBACK_DAYS (default 3), so the out-of-order window has to be at least that long.

Prometheus: start it with --web.enable-remote-write-receiver and add to prometheus.yml:

storage:
  tsdb:
    out_of_order_time_window: 7d

Mimir and Grafana Cloud: enable the out-of-order window for the tenant (out_of_order_time_window).

A receiver keeps the first value of a timestamp, so values Oura still revises (the last two activity slots of today, a sleep period until the ring has synced 30 minutes after it ended) are held back until they settle.

Quick start

1. Create an application in the Oura developer portal and register the redirect URI http://localhost:8000/callback.
2. cp .env.example .env and set OURA_CLIENT_ID, OURA_CLIENT_SECRET and OURA_REMOTE_WRITE_URL (for example http://prometheus:9090/api/v1/write).
3. docker compose run --rm -it oura-exporter, open the link it prints, approve access, paste the address you land on and stop with Ctrl-C.
4. docker compose up -d. Samples show up in the receiver within a poll interval; /metrics on http://127.0.0.1:8000 has the exporter's own health.

Load history with oura-exporter backfill, see docs/details.md. All options are in .env.example. Headless setup, alerting and more are in docs/details.md.

Metrics

Every series has job="oura-exporter". Values Oura does not report are left out instead of being 0, enums are numbers (the codes are in each metric's help text), and a few low-cardinality fields such as the sleep type or the workout activity are labels.

• Sleep · oura_sleep_* · every sleep period, stamped with its end
  total_sleep_duration_seconds, deep_sleep_duration_seconds, rem_sleep_duration_seconds, light_sleep_duration_seconds, awake_time_seconds, time_in_bed_seconds, efficiency_percent, latency_seconds, average_hrv_milliseconds, lowest_heart_rate_bpm, average_heart_rate_bpm, average_breath, restless_periods, low_battery_alert, readiness_score_delta, sleep_score_delta, sleep_algorithm_version (1-2), sleep_analysis_reason (1-4), readiness_score, readiness_temperature_deviation_celsius, readiness_temperature_trend_deviation_celsius, readiness_contributors_activity_balance, readiness_contributors_body_temperature, readiness_contributors_hrv_balance, readiness_contributors_previous_day_activity, readiness_contributors_previous_night, readiness_contributors_recovery_index, readiness_contributors_resting_heart_rate, readiness_contributors_sleep_balance, readiness_contributors_sleep_regularity, heart_rate_bpm, hrv_milliseconds, phase_5_min, phase_30_sec, app_phase_5_min, movement_30_sec
• Sleep score · oura_daily_sleep_* · daily value
  score
  contributors (contributors_*): deep_sleep, efficiency, latency, rem_sleep, restfulness, timing, total_sleep
• Readiness · oura_daily_readiness_* · daily value
  score, temperature_deviation_celsius, temperature_trend_deviation_celsius
  contributors (contributors_*): activity_balance, body_temperature, hrv_balance, previous_day_activity, previous_night, recovery_index, resting_heart_rate, sleep_balance, sleep_regularity
• Activity · oura_daily_activity_* · daily value
  score, steps, active_calories_kilocalories, total_calories_kilocalories, target_calories_kilocalories, equivalent_walking_distance_meters, target_meters, meters_to_target, high_activity_time_seconds, medium_activity_time_seconds, low_activity_time_seconds, sedentary_time_seconds, resting_time_seconds, non_wear_time_seconds, inactivity_alerts, average_met_minutes, high_activity_met_minutes, medium_activity_met_minutes, low_activity_met_minutes, sedentary_met_minutes, met, class_5_min
  contributors (contributors_*): meet_daily_targets, move_every_hour, recovery_time, stay_active, training_frequency, training_volume
• Heart rate · oura_heartrate_* · every sample
  bpm, source (1-6)
• Stress · oura_daily_stress_* · daily value
  stress_high_seconds, recovery_high_seconds, day_summary (1-3)
• Resilience · oura_daily_resilience_* · daily value
  level (1-5)
  contributors (contributors_*): sleep_recovery, daytime_recovery, stress
• SpO2 · oura_daily_spo2_* · daily value
  average_percent, breathing_disturbance_index
• Ring battery · oura_ring_battery_* · every sample
  level_percent, charging, in_charger
• Workouts · oura_workout_* · every event
  calories_kilocalories, distance_meters, duration_seconds
• Sessions · oura_session_* · every event
  heart_rate_bpm, heart_rate_variability_milliseconds, motion_count, duration_seconds
• Bedtime guidance · oura_sleep_time_* · daily value
  optimal_bedtime_day_tz_offset_seconds, optimal_bedtime_start_offset_seconds, optimal_bedtime_end_offset_seconds, recommendation (1-6), status (1-5)
• VO2 max · oura_vo2_max_* · daily value
  ml_per_minute_per_kilogram
• Cardiovascular age · oura_daily_cardiovascular_age_* · daily value
  vascular_age_years, pulse_wave_velocity_meters_per_second
• Tags · oura_enhanced_tag_* · every event
  duration_seconds
• Rest mode · oura_rest_mode_* · every event
  duration_seconds
• Profile · oura_personal_info_* · refreshed hourly
  age_years, weight_kilograms, height_meters, biological_sex_info
• Ring · oura_ring_* · refreshed hourly
  size, color_info, design_info, hardware_type_info, firmware_version_info, set_up_at_info

Plus the oura_exporter_* health metrics on /metrics, with the standard process_* and python_info.

License

MIT. Not affiliated with or endorsed by Oura.