extremeempress/ouradb

A Docker container for posting Oura data to InfluxDB and browsing it using Grafana

Docker Image with InfluxDB and Grafana

This Docker image is specifically intended for storing Oura sleep data in an InfluxDB database, and being able to easily do queries from the data using Grafana. It also has a cron job which checks for new data to upload to the database once per hour.

The Docker image is based on original work from Samuele Bistoletti in the Docker Image with Telegraf (StatsD), InfluxDB and Grafana and specifically on the improvements made by Phil Hawthorne for persistence in this Docker Image.

This repository also contains a python script, which can alone be used for querying data from the Oura API.

First Step: Get Personal Access Token from Oura

As the very first step, you need to get yourself a Personal Access Token (PAT) from the Oura website, here: https://cloud.ouraring.com/personal-access-tokens

Select "Create New Personal Access Token", and store the token in a safe place. Copy the oura/PAT_empty.txt file to a file named oura/PAT.txt and copy the 32 character long PAT to the new file.

Second step (optional): Do a test query

To make sure your PAT works, do a test run to get today's sleep data:

python3 oura/oura_query.py --pat=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

If you don't want to have a database and Grafana, you can just manually browse your data with this script.

Example: Get temperature deviations with 2 decimal accuracy for first week of October 2022 (requires jq):

user@machine:~/repos/ouradb$ python3 oura/oura_query.py --pat=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX --start=2022-10-01 --end=2022-10-07|jq '.temperature_deviation'
0.17
0.28
0.19
0.14
0.31
0.34
0.15

Third Step: Build and run the docker image

Now you need to build and run the image. When the image runs for the first time, it posts the current day's data to the database.

docker build -t ouradata .

After building, you'll need to run the image. You'll want to build it with persistence, to make sure you don't lose your data. Replace the paths with paths suitable for your environment.

docker run -d \
  --name docker-ouradb \
  -p 3003:3003 \
  -p 3004:8083 \
  -p 8086:8086 \
  -v /path/for/influxdb:/var/lib/influxdb \
  -v /path/for/grafana:/var/lib/grafana \
  ouradata:latest

To stop the container:

docker stop docker-ouradb

To start the container again:

docker start docker-ouradb

Fourth Step: Post old data to the database

You probably want to have historic data in the database as well. You can do that by providing the start and end dates for the script oura_post_to_influxdb.py.

Example: You got your ring on 1st January 2022. You want to get historic data for the entire January 2022.

docker exec docker-ouradb python3 /etc/oura/oura_post_to_influxdb.py --start=2022-01-01 --end=2022-01-31

Fifth Step: Create a Grafana dashboard

Next, you want to observe your data in Grafana.

Go to http://localhost:3003 in your browser, and login with username: root, password: root. (Remember to change these!)

You will first need to add InfluxDB as a datasource.

1. On the left panel, select the cogwheel ("Configuration") > Data Sources.
2. Select "Add data source".
3. Select InfluxDB.
4. Under "HTTP" > "URL", manually insert "http://localhost:8086". (Even though it looks like it already is there!)
5. Under "InfluxDB Details", set:
  - Database: ouradb
  - User: root
  - Password: root
6. Select "Save & Test".

Now, you want to create a dashboard. As an example we will create a dashboard with a panel showing temperatures ("temperature_deviation").

1. On the left, select "+" > "Create".
2. Select "Add new panel".
3. At the bottom, in the Query section, select:
  FROM default oura_measurements WHERE
  SELECT field(temperature_deviation) last()
  GROUP BY time($_interval) fill(linear)
4. On the right side, give the Panel a title.
5. On the top right, select "Save". Give your Dashboard a name.
6. To change the amount of days showing on the panel, at the top right you can change the time. Select for example "Last 30 days".

Now you are ready to start creating your own panels and exploring your Oura data!

ouradb's Issues

Mutliple sections for data return on days with naps- APIv2

I figured i'd leave this here so we can collab on the v2 update

The way things are now, the query looks at data index position 0
resp = response["data"][0]

The problem is on days with naps there is now data [0] and data [1]. Where the long sleep section is shifts around with naps. Maybe it is possible to figure out which section is the long sleep and pull that only?

The data looks like this in json

data :
{
stuff
}
{
stuff2
}

Nap data was missing from the old api it was

sleep:
{
stuff
}

i know how to tell it fetch a specific entry of 0 or 1 or 2, but I dont know how to make it do them all without knowing how many items are in the return from the beginning. Somehow it needs to iterate over the items in data [ ].

This works IF you manage to guess the right number of entries for the day. It may be easy enough to tell it to discard errors if it cant find [1] or [2] or [3].

  response = requests.request('GET', url, headers=headers, params=params).json()
   resp = response["data"][0]
   resp2 = response["data"][1]
   resp3 = response["data"][2]
   # resp4 = response["data"][3]
   resp.update(resp2)
   resp.update(resp3)
   print (json.dumps(resp, indent=4)) 

There may be an easy solution to this but I'm a noob at coding really

Temperature deviation query returns error

This was working great up until 2 weeks ago but I just tried to run the query again today and am now getting an error.

Here's my query:

py oura/oura_query.py --pat=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX --start=2022-09-27 --end=2022-10-07|jq '.temperature_deviation'

Here's the error:

File "C:\users\jenny\ouradb-main\oura\oura_query.py", line 83, in <module>
    main()
  File "C:\users\jenny\ouradb-main\oura\oura_query.py", line 78, in main
    data = fetch_data(tmp_date,end_date,datatype,pat)
  File "C:\users\jenny\ouradb-main\oura\oura_query.py", line 15, in fetch_data
    if not response[datatype]:
KeyError: 'sleep'

Appreciate you creating this, it makes tracking temps with the oura ring so much easier!

Datafield names changed after upgrade to API V2

Looks like Oura has changed the field names for some values between API V1 and V2.

Some examples:

• "awake" in API V1 is "awake_time" in API V2
• "breath_average" in API V1 is "average_breath" in API V2
• "deep", "light" in API V1 are "deep_sleep_duration", "light_sleep_duration" in API V2

Probably there are more.

This means that after changing to V2, the values posted to database will change. Long time tracking will suffer when performing the change.

It is an unfortunate decision from Oura to change the field names from one API version to another and lose consistency. But I am not sure if this should be fixed in the scripts. I would prefer using the field names that Oura themselves use in the scripts.

Still, I would personally like to have data consistency over naming consistency, as I have now pushed the data into a database for a long while. So perhaps an optional field name convertor function should be added into oura_post_to_influxdb.py, which can be used if moving from using API V1 to using API V2.