API automation
API reference: Query log API reference |
---|
You can use the API to request and download query logs programmatically.
Prerequisites
The following utilities are recommended for the programming language you’re using:
-
An HTTP client
-
A JSON processor
-
A Fauna driver.
Example program
This example program shows you how to use an account key to fetch logs
programmatically. You can extend the program to act on another Region Group
or time interval. It can be extended further to fetch logs using the
resulting presigned_url
and exporting them to your observability
platform.
To run the program, set the ACCOUNT_KEY
environment variable to an account
key in your Fauna account.
The general program flow is:
-
Set up the endpoints and request headers, including the account key.
-
Submit a log request (POST).
-
Poll on log availability, error, or timeout status (GET).
const axios = require('axios').default;
const winston = require('winston');
const lux = 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,
// enable json output, good to send to DD
format: winston.format.json(),
}),
],
});
const today = lux.DateTime.now().toISO();
const yesterday = lux.DateTime.now().minus(lux.Duration.fromISO("P1D")).toISO();
async function getLogs() {
const headers = { Authorization: `Bearer ${process.env["ACCOUNT_KEY"]}` };
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);
await pollResults(querylogRequest, headers, "us-std");
}
if (process.env["ACCOUNT_KEY"] === undefined) {
logger.error("You must set ACCOUNT_KEY in your local environment to run this program!");
return;
}
async function pollResults(
querylogRequest,
headers,
region_group,
) {
let result;
const maxRuntimeMs = 300 * 1000;
const time_start = Date.now();
do {
({ 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}`);
} while (
Date.now() < time_start + 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!"));
Trace queries
A trace uniquely identifies a transaction flow. In distributed scenarios,
a traceparent propagates a contextual identifier, which allows you to
associate logs from disparate services that participate in the application.
The traceparent
request header represents a request in a tracing system
using a common format.
See traceparent.
Fauna query log supports distributed tracing by allowing you to apply a
traceparent header to individual queries. The traceparent
request header
format is similar to this example:
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
.
You use the identifier in the query response in subsequent queries. If the Fauna query logic isn’t the main application, you should use the identifier provided by that application and follow the recommended processing model for mutating the identifier.
If you don’t include a traceparent identifier, one is generated for you and attached to the query response.
Tags
Because the query logs can be large and expensive to store and transmit, the query body isn’t included. Instead, you can tag individual queries with identifiers that can be used to associate operations.
You have the option of specifying an x-fauna-tags
header tag, which is
then propagated and included in the query logs emitted to disk.
-
Tags and associated values can be alphanumeric strings and include the underscore (
_
) character. -
Tag names can be up to 40 characters, and tag values can be up to 80 characters.
-
You can have up to 25 tags per query.
A query fails with a 400 status code if the tag is invalid.
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!