Access Fauna Logs using the HTTP API
You can use the Fauna Logs endpoints of the Fauna Account HTTP API to request and download Fauna Logs programmatically.
For more information about the API, check out the Fauna Account API reference docs.
Create an account key
To authenticate the Fauna Account API requests, you must have an account key. You can create an account key in the Fauna Dashboard.
-
Log in to the Fauna Dashboard and click Account in the left navigation.
-
Click Account Keys.
-
Click Create Key.
-
Enter a Name and an optional TTL. The TTL is the number of days until the account key expires.
-
Click Create.
-
Copy the Key Secret.
You can pass the secret as a Bearer token in Fauna Account API requests.
API workflow
To fetch logs using the API, use the following workflow:
-
Make a request to the Request Fauna Logs HTTP API endpoint to initiate a request for a set of Fauna Logs.
You must specify:
-
A
region_group
ordatabase
.If a
database
, you must provide a path to the database that includes the Region Group. For example, to request Fauna Logs for theECommerce
database in theus-std
Region Group, use"database": "us-std/ECommerce"
. -
A
time_start
in ISO 8601 format. -
A
time_end
in ISO 8601 format. You can specify a future time. The interval between thetime_start
andtime_end
can’t exceed 90 days.
curl -X POST \ 'https://account.fauna.com/api/v1/logs?type=query' \ -H 'Authorization: Bearer <ACCOUNT_KEY_SECRET>' \ -H 'Content-Type: application/json' \ -d '{ "database": "us-std/ECommerce", "time_start": "2099-07-10T07:46:05Z", "time_end": "2099-07-11T07:46:05Z" }'
The response includes a
request_id
you can use to check the status of the request:{ "request_id": "<REQUEST_ID>", "state": "Pending", "time_start": "2099-07-10T07:46:05Z", "time_end": "2099-07-11T07:46:05Z", "region_group": "us-std", "updated_at": "2099-07-11T21:53:47.398213Z", "version": 0, "database": "us-std/ECommerce" }
-
-
Use the request ID to make a request to the Get Fauna Logs Request Status endpoint:
curl -X GET \ 'https://account.fauna.com/api/v1/logs/<REQUEST_ID>?type=query®ionGroup=us-std' \ -H 'Authorization: Bearer <ACCOUNT_KEY_SECRET>'
The API response includes the Fauna Logs request’s current
state
. You can periodically poll the endpoint until thestate
isComplete
.Once
Complete
, the response includes apresigned_url
that links to the compressed log file:{ "request_id": "<REQUEST_ID>", "state": "Complete", "time_start": "2099-07-10T07:46:05Z", "time_end": "2099-07-11T07:46:05Z", "region_group": "us-std", "updated_at": "2099-07-11T21:53:54.899268Z", "version": 2, "presigned_url": "https://link.to.your.logs.com", "presigned_url_expiration_time": "2099-07-11T22:53:54Z", "database": "us-std/ECommerce" }
The
presigned_url
is valid until thepresigned_url_expiration_time
. -
After the
presigned_url_expiration_time
, you can get a new log file link by making a request to the Create Fauna Logs File URL API endpoint:curl -X POST \ 'https://account.fauna.com/api/v1/logs/<REQUEST_ID>/url?type=query®ionGroup=us-std' \ -H 'Authorization: Bearer <ACCOUNT_KEY_SECRET>'
{ "presigned_url": "https://new.link.to.your.logs.com", "state": "CreatingNewUrl", "time_end": "2099-07-11T07:46:05Z", "version": 3, "region_group": "us-std", "time_start": "2099-07-10T07:46:05Z", "request_id": "<REQUEST_ID>", "presigned_url_expiration_time": "2099-07-11T22:53:54Z", "updated_at": "2099-07-11T22:00:32.164516Z" }
Example: Programmatically fetch Fauna Logs
The following Node.js application programmatically fetches Fauna Logs from the
us-std
Region Group. The app follows the general API
workflow.
To run the app:
-
Create a project directory and navigate to it:
mkdir query-logs-demo cd query-logs-demo
-
Install app dependencies:
npm install axios dotenv luxon winston
-
Create a
.env
file. In the file, set theACCOUNT_KEY_SECRET
environment variable to an account key secret:// .env file ACCOUNT_KEY_SECRET=fnacapi...
-
Create a
node.js
file and add the following JavaScript to it:require('dotenv').config(); const axios = require('axios').default; const winston = require('winston'); const { DateTime, Duration } = require("luxon"); const faunaClient = axios.create({ baseURL: "https://account.fauna.com", timeout: 10000, }); const logger = winston.createLogger({ level: 'info', format: winston.format.json(), defaultMeta: { service: 'querylogs-demo' }, transports: [ new winston.transports.Console({ level: "debug", handleExceptions: true, format: winston.format.json(), }), ], }); const today = DateTime.now().toISO(); const yesterday = DateTime.now().minus(Duration.fromISO("P1D")).toISO(); async function getLogs() { if (process.env["ACCOUNT_KEY_SECRET"] === undefined) { throw new Error("You must set ACCOUNT_KEY_SECRET in your local environment to run this program!"); } try { const headers = { Authorization: `Bearer ${process.env["ACCOUNT_KEY_SECRET"]}` }; const { data: querylogRequest } = await faunaClient.post( "/api/v1/logs?type=query", { region_group: "us-std", time_start: yesterday, time_end: today}, { headers } ); logger.info(querylogRequest); return await pollResults(querylogRequest, headers, "us-std"); } catch (error) { logger.error("Error in getLogs:", error); throw error; } } async function pollResults( querylogRequest, headers, region_group, ) { let result; const maxRuntimeMs = 300 * 1000; const time_start = DateTime.now(); do { try { ({ data: result } = await faunaClient.get( `/api/v1/logs/${querylogRequest.request_id}?regionGroup=${region_group}&type=query`, { headers } )); await new Promise((resolve) => setTimeout(resolve, 1000)); logger.info(`State: ${result.state}`); } catch (error) { logger.error("Error in polling:", error); throw error; } } while ( DateTime.now().diff(time_start).as('milliseconds') < maxRuntimeMs && !["Complete", "DoesNotExist", "Failed", "TimedOut"].includes(result.state) ); logger.info(result); return result; } getLogs() .then(() => logger.info("Thanks for trying out Fauna Logs! Please give us any and all feedback!")) .catch(error => logger.error("An error occurred:", error));
-
Save
app.js
and run:node app.js
The app prints console logs containing the Fauna Logs request’s state. When the Fauna Logs are ready for download, it prints a console log containing the presigned URL for the Fauna Logs file.
You can extend the app to download the logs and export them to a third-party service for visualization or analysis.
Is this article helpful?
Tell Fauna how the article can be improved:
Visit Fauna's forums
or email docs@fauna.com
Thank you for your feedback!